+
+### Gold and Silver Sponsors
@@ -55,6 +60,8 @@ The key features are:
+
+
@@ -113,6 +120,12 @@ The key features are:
---
+## FastAPI mini documentary
+
+There's a FastAPI mini documentary released at the end of 2025, you can watch it online:
+
+
+
## **Typer**, the FastAPI of CLIs
@@ -125,7 +138,7 @@ If you are building a CLI app to be
FastAPI stands on the shoulders of giants:
-* Starlette for the web parts.
+* Starlette for the web parts.
* Pydantic for the data parts.
## Installation
@@ -231,7 +244,7 @@ INFO: Application startup complete.
fastapi dev main.py...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.
+* 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[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to FastAPI Cloud.
diff --git a/docs/az/docs/index.md b/docs/az/docs/index.md
deleted file mode 100644
index 4e14d7060..000000000
--- a/docs/az/docs/index.md
+++ /dev/null
@@ -1,467 +0,0 @@
-
- 
-
- FastAPI framework, yüksək məshuldarlı, öyrənməsi asan, çevik kodlama, istifadəyə hazırdır -
- - ---- - -**Sənədlər**: https://fastapi.tiangolo.com - -**Qaynaq Kodu**: https://github.com/fastapi/fastapi - ---- - -FastAPI Python ilə API yaratmaq üçün standart Python tip məsləhətlərinə əsaslanan, müasir, sürətli (yüksək performanslı) framework-dür. - -Əsas xüsusiyyətləri bunlardır: - -* **Sürətli**: Çox yüksək performans, **NodeJS** və **Go** səviyyəsində (Starlette və Pydantic-ə təşəkkürlər). [Ən sürətli Python frameworklərindən biridir](#performans). -* **Çevik kodlama**: Funksiyanallıqları inkişaf etdirmək sürətini təxminən 200%-dən 300%-ə qədər artırın. * -* **Daha az xəta**: İnsan (developer) tərəfindən törədilən səhvlərin təxminən 40% -ni azaldın. * -* **İntuitiv**: Əla redaktor dəstəyi. Hər yerdə otomatik tamamlama. Xətaları müəyyənləşdirməyə daha az vaxt sərf edəcəksiniz. -* **Asan**: İstifadəsi və öyrənilməsi asan olması üçün nəzərdə tutulmuşdur. Sənədləri oxumaq üçün daha az vaxt ayıracaqsınız. -* **Qısa**: Kod təkrarlanmasını minimuma endirin. Hər bir parametr tərifində birdən çox xüsusiyyət ilə və daha az səhvlə qarşılaşacaqsınız. -* **Güclü**: Avtomatik və interaktiv sənədlərlə birlikdə istifadəyə hazır kod əldə edə bilərsiniz. -* **Standartlara əsaslanan**: API-lar üçün açıq standartlara əsaslanır (və tam uyğun gəlir): OpenAPI (əvvəlki adı ilə Swagger) və JSON Schema. - -* Bu fikirlər daxili development komandasının hazırladıqları məhsulların sınaqlarına əsaslanır. - -## Sponsorlar - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Əgər siz veb API əvəzinə terminalda istifadə ediləcək CLI proqramı qurursunuzsa, **Typer**-a baxa bilərsiniz.
-
-**Typer** FastAPI-ın kiçik qardaşıdır. Və o, CLI-lərin **FastAPI**-ı olmaq üçün nəzərdə tutulub. ⌨️ 🚀
-
-## Tələblər
-
-FastAPI nəhənglərin çiyinlərində dayanır:
-
-* Web tərəfi üçün Starlette.
-* Data tərəfi üçün Pydantic.
-
-## Quraşdırma
-
-
-
-
-
-async def...uvicorn main:app --reload əmri haqqında...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.
-
-Starlette tərəfindən istifadə olunanlar:
-
-* httpx - Əgər `TestClient` strukturundan istifadə edəcəksinizsə, tələb olunur.
-* jinja2 - Standart şablon konfiqurasiyasından istifadə etmək istəyirsinizsə, tələb olunur.
-* python-multipart - `request.form()` ilə forma "çevirmə" dəstəyindən istifadə etmək istəyirsinizsə, tələb olunur.
-* itsdangerous - `SessionMiddleware` dəstəyi üçün tələb olunur.
-* pyyaml - `SchemaGenerator` dəstəyi üçün tələb olunur (Çox güman ki, FastAPI istifadə edərkən buna ehtiyacınız olmayacaq).
-* ujson - `UJSONResponse` istifadə etmək istəyirsinizsə, tələb olunur.
-
-Həm FastAPI, həm də Starlette tərəfindən istifadə olunur:
-
-* uvicorn - Yaratdığımız proqramı servis edəcək veb server kimi fəaliyyət göstərir.
-* orjson - `ORJSONResponse` istifadə edəcəksinizsə tələb olunur.
-
-Bütün bunları `pip install fastapi[all]` ilə quraşdıra bilərsiniz.
-
-## Lisenziya
-
-Bu layihə MIT lisenziyasının şərtlərinə əsasən lisenziyalaşdırılıb.
diff --git a/docs/az/docs/learn/index.md b/docs/az/docs/learn/index.md
deleted file mode 100644
index cc32108bf..000000000
--- a/docs/az/docs/learn/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Öyrən
-
-Burada **FastAPI** öyrənmək üçün giriş bölmələri və dərsliklər yer alır.
-
-Siz bunu kitab, kurs, FastAPI öyrənmək üçün rəsmi və tövsiyə olunan üsul hesab edə bilərsiniz. 😎
diff --git a/docs/az/mkdocs.yml b/docs/az/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/az/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/bn/docs/about/index.md b/docs/bn/docs/about/index.md
deleted file mode 100644
index b6d611ae9..000000000
--- a/docs/bn/docs/about/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# সম্পর্কে
-
-**FastAPI** সম্পর্কে বিস্তারিত — এর ডিজাইন, অনুপ্রেরণা ও আরও অনেক কিছু। 🤓
diff --git a/docs/bn/docs/environment-variables.md b/docs/bn/docs/environment-variables.md
deleted file mode 100644
index 9122ca5bf..000000000
--- a/docs/bn/docs/environment-variables.md
+++ /dev/null
@@ -1,298 +0,0 @@
-# এনভায়রনমেন্ট ভেরিয়েবলস
-
-/// tip
-
-আপনি যদি "এনভায়রনমেন্ট ভেরিয়েবলস" কী এবং সেগুলো কীভাবে ব্যবহার করতে হয় সেটা জানেন, তাহলে এই অংশটি স্কিপ করে যেতে পারেন।
-
-///
-
-এনভায়রনমেন্ট ভেরিয়েবল (সংক্ষেপে "**env var**" নামেও পরিচিত) হলো এমন একটি ভেরিয়েবল যা পাইথন কোডের **বাইরে**, **অপারেটিং সিস্টেমে** থাকে এবং আপনার পাইথন কোড (বা অন্যান্য প্রোগ্রাম) দ্বারা যাকে রিড করা যায়।
-
-এনভায়রনমেন্ট ভেরিয়েবলস অ্যাপ্লিকেশনের **সেটিংস** পরিচালনা করতে, পাইথনের **ইনস্টলেশন** প্রক্রিয়ার অংশ হিসেবে, ইত্যাদি কাজে উপযোগী হতে পারে।
-
-## Env Vars তৈরী এবং ব্যবহার
-
-আপনি **শেল (টার্মিনাল)**-এ, পাইথনের প্রয়োজন ছাড়াই, এনভায়রনমেন্ট ভেরিয়েবলস **তৈরি** এবং ব্যবহার করতে পারবেনঃ
-
-//// tab | লিনাক্স, ম্যাকওএস, উইন্ডোজ Bash
-
-
-
-
- FastAPI উচ্চক্ষমতা সম্পন্ন, সহজে শেখার এবং দ্রুত কোড করে প্রোডাকশনের জন্য ফ্রামওয়ার্ক। -
- - ---- - -**নির্দেশিকা নথি**: https://fastapi.tiangolo.com - -**সোর্স কোড**: https://github.com/fastapi/fastapi - ---- - -FastAPI একটি আধুনিক, দ্রুত ( বেশি ক্ষমতা ) সম্পন্ন, Python 3.6+ দিয়ে API তৈরির জন্য স্ট্যান্ডার্ড পাইথন টাইপ ইঙ্গিত ভিত্তিক ওয়েব ফ্রেমওয়ার্ক। - -এর মূল বৈশিষ্ট্য গুলো হলঃ - -- **গতি**: এটি **NodeJS** এবং **Go** এর মত কার্যক্ষমতা সম্পন্ন (Starlette এবং Pydantic এর সাহায্যে)। [পাইথন এর দ্রুততম ফ্রেমওয়ার্ক গুলোর মধ্যে এটি একটি](#_11)। -- **দ্রুত কোড করা**:বৈশিষ্ট্য তৈরির গতি ২০০% থেকে ৩০০% বৃদ্ধি করে৷ \* -- **স্বল্প bugs**: মানুব (ডেভেলপার) সৃষ্ট ত্রুটির প্রায় ৪০% হ্রাস করে। \* -- **স্বজ্ঞাত**: দুর্দান্ত এডিটর সাহায্য Completion নামেও পরিচিত। দ্রুত ডিবাগ করা যায়। - -- **সহজ**: এটি এমন ভাবে সজানো হয়েছে যেন নির্দেশিকা নথি পড়ে সহজে শেখা এবং ব্যবহার করা যায়। -- **সংক্ষিপ্ত**: কোড পুনরাবৃত্তি কমানোর পাশাপাশি, bug কমায় এবং প্রতিটি প্যারামিটার ঘোষণা থেকে একাধিক ফিচার পাওয়া যায় । -- **জোরালো**: স্বয়ংক্রিয় ভাবে তৈরি ক্রিয়াশীল নির্দেশনা নথি (documentation) সহ উৎপাদন উপযোগি (Production-ready) কোড পাওয়া যায়। -- **মান-ভিত্তিক**: এর ভিত্তি OpenAPI (যা পুর্বে Swagger নামে পরিচিত ছিল) এবং JSON Schema এর আদর্শের মানের ওপর - -\* উৎপাদনমুখি এপ্লিকেশন বানানোর এক দল ডেভেলপার এর মতামত ভিত্তিক ফলাফল। - -## স্পনসর গণ - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-আপনি যদি CLI অ্যাপ বানাতে চান, যা কিনা ওয়েব API এর পরিবর্তে টার্মিনালে ব্যবহার হবে, তাহলে দেখুন**Typer**.
-
-**টাইপার** হল FastAPI এর ছোট ভাইয়ের মত। এবং এটির উদ্দেশ্য ছিল **CLIs এর FastAPI** হওয়া। ⌨️ 🚀
-
-## প্রয়োজনীয়তা গুলো
-
-Python 3.7+
-
-FastAPI কিছু দানবেদের কাঁধে দাঁড়িয়ে আছে:
-
-- Starlette ওয়েব অংশের জন্য.
-- Pydantic ডেটা অংশগুলির জন্য.
-
-## ইনস্টলেশন প্রক্রিয়া
-
-async def...uvicorn main:app --reload...email-validator - ইমেল যাচাইকরণের জন্য।
-
-স্টারলেট দ্বারা ব্যবহৃত:
-
-- httpx - আপনি যদি `TestClient` ব্যবহার করতে চান তাহলে আবশ্যক।
-- jinja2 - আপনি যদি প্রদত্ত টেমপ্লেট রূপরেখা ব্যবহার করতে চান তাহলে প্রয়োজন।
-- python-multipart - আপনি যদি ফর্ম সহায়তা করতে চান তাহলে প্রয়োজন "parsing", `request.form()` সহ।
-- itsdangerous - `SessionMiddleware` সহায়তার জন্য প্রয়োজন।
-- pyyaml - স্টারলেটের SchemaGenerator সাপোর্ট এর জন্য প্রয়োজন (আপনার সম্ভাবত FastAPI প্রয়োজন নেই)।
-- graphene - `GraphQLApp` সহায়তার জন্য প্রয়োজন।
-
-FastAPI / Starlette দ্বারা ব্যবহৃত:
-
-- uvicorn - সার্ভারের জন্য যা আপনার অ্যাপ্লিকেশন লোড করে এবং পরিবেশন করে।
-- orjson - আপনি `ORJSONResponse` ব্যবহার করতে চাইলে প্রয়োজন।
-- ujson - আপনি `UJSONResponse` ব্যবহার করতে চাইলে প্রয়োজন।
-
-আপনি এই সব ইনস্টল করতে পারেন `pip install fastapi[all]` দিয়ে.
-
-## লাইসেন্স
-
-এই প্রজেক্ট MIT লাইসেন্স নীতিমালার অধীনে শর্তায়িত।
diff --git a/docs/bn/docs/learn/index.md b/docs/bn/docs/learn/index.md
deleted file mode 100644
index 4e4c62038..000000000
--- a/docs/bn/docs/learn/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# শিখুন
-
-এখানে **FastAPI** শিখার জন্য প্রাথমিক বিভাগগুলি এবং টিউটোরিয়ালগুলি রয়েছে।
-
-আপনি এটিকে একটি **বই**, একটি **কোর্স**, এবং FastAPI শিখার **অফিসিয়াল** এবং প্রস্তাবিত উপায় বিবেচনা করতে পারেন। 😎
diff --git a/docs/bn/docs/python-types.md b/docs/bn/docs/python-types.md
deleted file mode 100644
index d98c2ec87..000000000
--- a/docs/bn/docs/python-types.md
+++ /dev/null
@@ -1,586 +0,0 @@
-# পাইথন এর টাইপ্স পরিচিতি
-
-Python-এ ঐচ্ছিক "টাইপ হিন্ট" (যা "টাইপ অ্যানোটেশন" নামেও পরিচিত) এর জন্য সাপোর্ট রয়েছে।
-
-এই **"টাইপ হিন্ট"** বা অ্যানোটেশনগুলি এক ধরণের বিশেষ সিনট্যাক্স যা একটি ভেরিয়েবলের টাইপ ঘোষণা করতে দেয়।
-
-ভেরিয়েবলগুলির জন্য টাইপ ঘোষণা করলে, এডিটর এবং টুলগুলি আপনাকে আরও ভালো সাপোর্ট দিতে পারে।
-
-এটি পাইথন টাইপ হিন্ট সম্পর্কে একটি দ্রুত **টিউটোরিয়াল / রিফ্রেশার** মাত্র। এটি **FastAPI** এর সাথে ব্যবহার করার জন্য শুধুমাত্র ন্যূনতম প্রয়োজনীয়তা কভার করে... যা আসলে খুব একটা বেশি না।
-
-**FastAPI** এই টাইপ হিন্টগুলির উপর ভিত্তি করে নির্মিত, যা এটিকে অনেক সুবিধা এবং লাভ প্রদান করে।
-
-তবে, আপনি যদি কখনো **FastAPI** ব্যবহার নাও করেন, তবুও এগুলি সম্পর্কে একটু শেখা আপনার উপকারে আসবে।
-
-/// note
-
-যদি আপনি একজন Python বিশেষজ্ঞ হন, এবং টাইপ হিন্ট সম্পর্কে সবকিছু জানেন, তাহলে পরবর্তী অধ্যায়ে চলে যান।
-
-///
-
-## প্রেরণা
-
-চলুন একটি সাধারণ উদাহরণ দিয়ে শুরু করি:
-
-{* ../../docs_src/python_types/tutorial001.py *}
-
-
-এই প্রোগ্রামটি কল করলে আউটপুট হয়:
-
-```
-John Doe
-```
-
-ফাংশনটি নিম্নলিখিত কাজ করে:
-
-* `first_name` এবং `last_name` নেয়।
-* প্রতিটির প্রথম অক্ষরকে `title()` ব্যবহার করে বড় হাতের অক্ষরে রূপান্তর করে।
-* তাদেরকে মাঝখানে একটি স্পেস দিয়ে concatenate করে।
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
-
-
-### এটি সম্পাদনা করুন
-
-এটি একটি খুব সাধারণ প্রোগ্রাম।
-
-কিন্তু এখন কল্পনা করুন যে আপনি এটি শুরু থেকে লিখছিলেন।
-
-এক পর্যায়ে আপনি ফাংশনের সংজ্ঞা শুরু করেছিলেন, আপনার প্যারামিটারগুলি প্রস্তুত ছিল...
-
-কিন্তু তারপর আপনাকে "সেই method কল করতে হবে যা প্রথম অক্ষরকে বড় হাতের অক্ষরে রূপান্তর করে"।
-
-এটা কি `upper` ছিল? নাকি `uppercase`? `first_uppercase`? `capitalize`?
-
-তারপর, আপনি পুরোনো প্রোগ্রামারের বন্ধু, এডিটর অটোকমপ্লিশনের সাহায্যে নেওয়ার চেষ্টা করেন।
-
-আপনি ফাংশনের প্রথম প্যারামিটার `first_name` টাইপ করেন, তারপর একটি ডট (`.`) টাইপ করেন এবং `Ctrl+Space` চাপেন অটোকমপ্লিশন ট্রিগার করার জন্য।
-
-কিন্তু, দুর্ভাগ্যবশত, আপনি কিছুই উপযোগী পান না:
-
-
-
-### টাইপ যোগ করুন
-
-আসুন আগের সংস্করণ থেকে একটি লাইন পরিবর্তন করি।
-
-আমরা ঠিক এই অংশটি পরিবর্তন করব অর্থাৎ ফাংশনের প্যারামিটারগুলি, এইগুলি:
-
-```Python
- first_name, last_name
-```
-
-থেকে এইগুলি:
-
-```Python
- first_name: str, last_name: str
-```
-
-ব্যাস।
-
-এগুলিই "টাইপ হিন্ট":
-
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
-
-
-এটি ডিফল্ট ভ্যালু ঘোষণা করার মত নয় যেমন:
-
-```Python
- first_name="john", last_name="doe"
-```
-
-এটি একটি ভিন্ন জিনিস।
-
-আমরা সমান (`=`) নয়, কোলন (`:`) ব্যবহার করছি।
-
-এবং টাইপ হিন্ট যোগ করা সাধারণত তেমন কিছু পরিবর্তন করে না যা টাইপ হিন্ট ছাড়াই ঘটত।
-
-কিন্তু এখন, কল্পনা করুন আপনি আবার সেই ফাংশন তৈরির মাঝখানে আছেন, কিন্তু টাইপ হিন্ট সহ।
-
-একই পর্যায়ে, আপনি অটোকমপ্লিট ট্রিগার করতে `Ctrl+Space` চাপেন এবং আপনি দেখতে পান:
-
-
-
-এর সাথে, আপনি অপশনগুলি দেখে, স্ক্রল করতে পারেন, যতক্ষণ না আপনি এমন একটি অপশন খুঁজে পান যা কিছু মনে পরিয়ে দেয়:
-
-
-
-## আরও প্রেরণা
-
-এই ফাংশনটি দেখুন, এটিতে ইতিমধ্যে টাইপ হিন্ট রয়েছে:
-
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
-
-
-এডিটর ভেরিয়েবলগুলির টাইপ জানার কারণে, আপনি শুধুমাত্র অটোকমপ্লিশনই পান না, আপনি এরর চেকও পান:
-
-
-
-এখন আপনি জানেন যে আপনাকে এটি ঠিক করতে হবে, `age`-কে একটি স্ট্রিং হিসেবে রূপান্তর করতে `str(age)` ব্যবহার করতে হবে:
-
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-
-
-## টাইপ ঘোষণা
-
-আপনি এতক্ষন টাইপ হিন্ট ঘোষণা করার মূল স্থানটি দেখে ফেলেছেন-- ফাংশন প্যারামিটার হিসেবে।
-
-সাধারণত এটি **FastAPI** এর ক্ষেত্রেও একই।
-
-### সিম্পল টাইপ
-
-আপনি `str` ছাড়াও সমস্ত স্ট্যান্ডার্ড পাইথন টাইপ ঘোষণা করতে পারেন।
-
-উদাহরণস্বরূপ, আপনি এগুলো ব্যবহার করতে পারেন:
-
-* `int`
-* `float`
-* `bool`
-* `bytes`
-
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
-
-
-### টাইপ প্যারামিটার সহ জেনেরিক টাইপ
-
-কিছু ডাটা স্ট্রাকচার অন্যান্য মান ধারণ করতে পারে, যেমন `dict`, `list`, `set` এবং `tuple`। এবং অভ্যন্তরীণ মানগুলোরও নিজেদের টাইপ থাকতে পারে।
-
-এই ধরনের টাইপগুলিকে বলা হয় "**জেনেরিক**" টাইপ এবং এগুলিকে তাদের অভ্যন্তরীণ টাইপগুলি সহ ঘোষণা করা সম্ভব।
-
-এই টাইপগুলি এবং অভ্যন্তরীণ টাইপগুলি ঘোষণা করতে, আপনি Python মডিউল `typing` ব্যবহার করতে পারেন। এটি বিশেষভাবে এই টাইপ হিন্টগুলি সমর্থন করার জন্য রয়েছে।
-
-#### Python এর নতুন সংস্করণ
-
-`typing` ব্যবহার করা সিনট্যাক্সটি Python 3.6 থেকে সর্বশেষ সংস্করণগুলি পর্যন্ত, অর্থাৎ Python 3.9, Python 3.10 ইত্যাদি সহ সকল সংস্করণের সাথে **সামঞ্জস্যপূর্ণ**।
-
-Python যত এগিয়ে যাচ্ছে, **নতুন সংস্করণগুলি** এই টাইপ অ্যানোটেশনগুলির জন্য তত উন্নত সাপোর্ট নিয়ে আসছে এবং অনেক ক্ষেত্রে আপনাকে টাইপ অ্যানোটেশন ঘোষণা করতে `typing` মডিউল ইম্পোর্ট এবং ব্যবহার করার প্রয়োজন হবে না।
-
-যদি আপনি আপনার প্রজেক্টের জন্য Python-এর আরও সাম্প্রতিক সংস্করণ নির্বাচন করতে পারেন, তাহলে আপনি সেই অতিরিক্ত সরলতা থেকে সুবিধা নিতে পারবেন।
-
-ডক্সে রয়েছে Python-এর প্রতিটি সংস্করণের সাথে সামঞ্জস্যপূর্ণ উদাহরণগুলি (যখন পার্থক্য আছে)।
-
-উদাহরণস্বরূপ, "**Python 3.6+**" মানে এটি Python 3.6 বা তার উপরে সামঞ্জস্যপূর্ণ (যার মধ্যে 3.7, 3.8, 3.9, 3.10, ইত্যাদি অন্তর্ভুক্ত)। এবং "**Python 3.9+**" মানে এটি Python 3.9 বা তার উপরে সামঞ্জস্যপূর্ণ (যার মধ্যে 3.10, ইত্যাদি অন্তর্ভুক্ত)।
-
-যদি আপনি Python-এর **সর্বশেষ সংস্করণগুলি ব্যবহার করতে পারেন**, তাহলে সর্বশেষ সংস্করণের জন্য উদাহরণগুলি ব্যবহার করুন, সেগুলি আপনাকে **সর্বোত্তম এবং সহজতম সিনট্যাক্স** প্রদান করবে, যেমন, "**Python 3.10+**"।
-
-#### লিস্ট
-
-উদাহরণস্বরূপ, একটি ভেরিয়েবলকে `str`-এর একটি `list` হিসেবে সংজ্ঞায়িত করা যাক।
-
-//// tab | Python 3.9+
-
-ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
-
-টাইপ হিসেবে, `list` ব্যবহার করুন।
-
-যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে ব্যবহার করুন:
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-`typing` থেকে `List` (বড় হাতের `L` দিয়ে) ইমপোর্ট করুন:
-
-``` Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-ভেরিয়েবলটি ঘোষণা করুন, একই কোলন (`:`) সিনট্যাক্স ব্যবহার করে।
-
-টাইপ হিসেবে, `typing` থেকে আপনার ইম্পোর্ট করা `List` ব্যবহার করুন।
-
-যেহেতু লিস্ট এমন একটি টাইপ যা অভ্যন্তরীণ টাইপগুলি ধারণ করে, আপনি তাদের স্কোয়ার ব্রাকেটের ভিতরে করুন:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
-
-/// info
-
-স্কোয়ার ব্রাকেট এর ভিতরে ব্যবহৃত এইসব অভন্তরীন টাইপগুলোকে "ইন্টারনাল টাইপ" বলে।
-
-এই উদাহরণে, এটি হচ্ছে `List`(অথবা পাইথন ৩.৯ বা তার উপরের সংস্করণের ক্ষেত্রে `list`) এ পাস করা টাইপ প্যারামিটার।
-
-///
-
-এর অর্থ হচ্ছে: "ভেরিয়েবল `items` একটি `list`, এবং এই লিস্টের প্রতিটি আইটেম একটি `str`।"
-
-/// tip
-
-যদি আপনি Python 3.9 বা তার উপরে ব্যবহার করেন, আপনার `typing` থেকে `List` আমদানি করতে হবে না, আপনি সাধারণ `list` ওই টাইপের পরিবর্তে ব্যবহার করতে পারেন।
-
-///
-
-এর মাধ্যমে, আপনার এডিটর লিস্ট থেকে আইটেম প্রসেস করার সময় সাপোর্ট প্রদান করতে পারবে:
-
-
-
-টাইপগুলি ছাড়া, এটি করা প্রায় অসম্ভব।
-
-লক্ষ্য করুন যে ভেরিয়েবল `item` হল `items` লিস্টের একটি এলিমেন্ট।
-
-তবুও, এডিটর জানে যে এটি একটি `str`, এবং তার জন্য সাপোর্ট প্রদান করে।
-
-#### টাপল এবং সেট
-
-আপনি `tuple` এবং `set` ঘোষণা করার জন্য একই প্রক্রিয়া অনুসরণ করবেন:
-
-//// 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!}
-```
-
-////
-
-এর মানে হল:
-
-* ভেরিয়েবল `items_t` হল একটি `tuple` যা ৩টি আইটেম ধারণ করে, একটি `int`, অন্য একটি `int`, এবং একটি `str`।
-* ভেরিয়েবল `items_s` হল একটি `set`, এবং এর প্রতিটি আইটেম হল `bytes` টাইপের।
-
-#### ডিক্ট
-
-একটি `dict` সংজ্ঞায়িত করতে, আপনি ২টি টাইপ প্যারামিটার কমা দ্বারা পৃথক করে দেবেন।
-
-প্রথম টাইপ প্যারামিটারটি হল `dict`-এর কীগুলির জন্য।
-
-দ্বিতীয় টাইপ প্যারামিটারটি হল `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!}
-```
-
-////
-
-এর মানে হল:
-
-* ভেরিয়েবল `prices` হল একটি `dict`:
- * এই `dict`-এর কীগুলি হল `str` টাইপের (ধরা যাক, প্রতিটি আইটেমের নাম)।
- * এই `dict`-এর মানগুলি হল `float` টাইপের (ধরা যাক, প্রতিটি আইটেমের দাম)।
-
-#### ইউনিয়ন
-
-আপনি একটি ভেরিয়েবলকে এমনভাবে ঘোষণা করতে পারেন যেন তা **একাধিক টাইপের** হয়, উদাহরণস্বরূপ, একটি `int` অথবা `str`।
-
-Python 3.6 এবং তার উপরের সংস্করণগুলিতে (Python 3.10 অন্তর্ভুক্ত) আপনি `typing` থেকে `Union` টাইপ ব্যবহার করতে পারেন এবং স্কোয়ার ব্র্যাকেটের মধ্যে গ্রহণযোগ্য টাইপগুলি রাখতে পারেন।
-
-Python 3.10-এ একটি **নতুন সিনট্যাক্স** আছে যেখানে আপনি সম্ভাব্য টাইপগুলিকে একটি ভার্টিকাল বার (`|`) দ্বারা পৃথক করতে পারেন।
-
-//// 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!}
-```
-
-////
-
-উভয় ক্ষেত্রেই এর মানে হল যে `item` হতে পারে একটি `int` অথবা `str`।
-
-#### সম্ভবত `None`
-
-আপনি এমনভাবে ঘোষণা করতে পারেন যে একটি মান হতে পারে এক টাইপের, যেমন `str`, আবার এটি `None`-ও হতে পারে।
-
-Python 3.6 এবং তার উপরের সংস্করণগুলিতে (Python 3.10 অনতর্ভুক্ত) আপনি `typing` মডিউল থেকে `Optional` ইমপোর্ট করে এটি ঘোষণা এবং ব্যবহার করতে পারেন।
-
-```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
-```
-
-`Optional[str]` ব্যবহার করা মানে হল শুধু `str` নয়, এটি হতে পারে `None`-ও, যা আপনার এডিটরকে সেই ত্রুটিগুলি শনাক্ত করতে সাহায্য করবে যেখানে আপনি ধরে নিচ্ছেন যে একটি মান সবসময় `str` হবে, অথচ এটি `None`-ও হতে পারেও।
-
-`Optional[Something]` মূলত `Union[Something, None]`-এর একটি শর্টকাট, এবং তারা সমতুল্য।
-
-এর মানে হল, Python 3.10-এ, আপনি টাইপগুলির ইউনিয়ন ঘোষণা করতে `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+ বিকল্প
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
-```
-
-////
-
-#### `Union` বা `Optional` ব্যবহার
-
-যদি আপনি Python 3.10-এর নীচের সংস্করণ ব্যবহার করেন, তবে এখানে আমার খুবই **ব্যক্তিগত** দৃষ্টিভঙ্গি থেকে একটি টিপস:
-
-* 🚨 `Optional[SomeType]` ব্যবহার এড়িয়ে চলুন।
-* এর পরিবর্তে ✨ **`Union[SomeType, None]` ব্যবহার করুন** ✨।
-
-উভয়ই সমতুল্য এবং মূলে একই, কিন্তু আমি `Union`-এর পক্ষে সুপারিশ করব কারণ "**অপশনাল**" শব্দটি মনে হতে পারে যে মানটি ঐচ্ছিক,অথচ এটি আসলে মানে "এটি হতে পারে `None`", এমনকি যদি এটি ঐচ্ছিক না হয়েও আবশ্যিক হয়।
-
-আমি মনে করি `Union[SomeType, None]` এর অর্থ আরও স্পষ্টভাবে প্রকাশ করে।
-
-এটি কেবল শব্দ এবং নামের ব্যাপার। কিন্তু সেই শব্দগুলি আপনি এবং আপনার সহকর্মীরা কোড সম্পর্কে কীভাবে চিন্তা করেন তা প্রভাবিত করতে পারে।
-
-একটি উদাহরণ হিসেবে, এই ফাংশনটি নিন:
-
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
-
-
-`name` প্যারামিটারটি `Optional[str]` হিসেবে সংজ্ঞায়িত হয়েছে, কিন্তু এটি **অপশনাল নয়**, আপনি প্যারামিটার ছাড়া ফাংশনটি কল করতে পারবেন না:
-
-```Python
-say_hi() # ওহ না, এটি একটি ত্রুটি নিক্ষেপ করবে! 😱
-```
-
-`name` প্যারামিটারটি **এখনও আবশ্যিক** (নন-অপশনাল) কারণ এটির কোনো ডিফল্ট মান নেই। তবুও, `name` এর মান হিসেবে `None` গ্রহণযোগ্য:
-
-```Python
-say_hi(name=None) # এটি কাজ করে, None বৈধ 🎉
-```
-
-সুখবর হল, একবার আপনি Python 3.10 ব্যবহার করা শুরু করলে, আপনাকে এগুলোর ব্যাপারে আর চিন্তা করতে হবে না, যেহুতু আপনি | ব্যবহার করেই ইউনিয়ন ঘোষণা করতে পারবেন:
-
-{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
-
-
-এবং তারপর আপনাকে নামগুলি যেমন `Optional` এবং `Union` নিয়ে আর চিন্তা করতে হবে না। 😎
-
-#### জেনেরিক টাইপস
-
-স্কোয়ার ব্র্যাকেটে টাইপ প্যারামিটার নেওয়া এই টাইপগুলিকে **জেনেরিক টাইপ** বা **জেনেরিকস** বলা হয়, যেমন:
-
-//// tab | Python 3.10+
-
-আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
-
-* `Union`
-* `Optional` (Python 3.8 এর মতোই)
-* ...এবং অন্যান্য।
-
-Python 3.10-এ, `Union` এবং `Optional` জেনেরিকস ব্যবহার করার বিকল্প হিসেবে, আপনি টাইপগুলির ইউনিয়ন ঘোষণা করতে ভার্টিকাল বার (`|`) ব্যবহার করতে পারেন, যা ওদের থেকে অনেক ভালো এবং সহজ।
-
-////
-
-//// tab | Python 3.9+
-
-আপনি সেই একই বিল্টইন টাইপ জেনেরিক্স হিসেবে ব্যবহার করতে পারবেন(ভিতরে টাইপ সহ স্কয়ারে ব্রাকেট দিয়ে):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-এবং Python 3.8 এর মতোই, `typing` মডিউল থেকে:
-
-* `Union`
-* `Optional`
-* ...এবং অন্যান্য।
-
-////
-
-//// tab | Python 3.8+
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...এবং অন্যান্য।
-
-////
-
-### ক্লাস হিসেবে টাইপস
-
-আপনি একটি ভেরিয়েবলের টাইপ হিসেবে একটি ক্লাস ঘোষণা করতে পারেন।
-
-ধরুন আপনার কাছে `Person` নামে একটি ক্লাস আছে, যার একটি নাম আছে:
-
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
-
-
-তারপর আপনি একটি ভেরিয়েবলকে `Person` টাইপের হিসেবে ঘোষণা করতে পারেন:
-
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
-
-
-এবং তারপর, আবার, আপনি এডিটর সাপোর্ট পেয়ে যাবেন:
-
-
-
-লক্ষ্য করুন যে এর মানে হল "`one_person` হল ক্লাস `Person`-এর একটি **ইন্সট্যান্স**।"
-
-এর মানে এটি নয় যে "`one_person` হল **ক্লাস** যাকে বলা হয় `Person`।"
-
-## Pydantic মডেল
-
-[Pydantic](https://docs.pydantic.dev/) হল একটি Python লাইব্রেরি যা ডাটা ভ্যালিডেশন সম্পাদন করে।
-
-আপনি ডাটার "আকার" এট্রিবিউট সহ ক্লাস হিসেবে ঘোষণা করেন।
-
-এবং প্রতিটি এট্রিবিউট এর একটি টাইপ থাকে।
-
-তারপর আপনি যদি কিছু মান দিয়ে সেই ক্লাসের একটি ইন্সট্যান্স তৈরি করেন-- এটি মানগুলিকে ভ্যালিডেট করবে, প্রয়োজন অনুযায়ী তাদেরকে উপযুক্ত টাইপে রূপান্তর করবে এবং আপনাকে সমস্ত ডাটা সহ একটি অবজেক্ট প্রদান করবে।
-
-এবং আপনি সেই ফলাফল অবজেক্টের সাথে এডিটর সাপোর্ট পাবেন।
-
-অফিসিয়াল Pydantic ডক্স থেকে একটি উদাহরণ:
-
-//// 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
-
-[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) সম্পর্কে আরও পড়তে পারেন।
-
-///
-
-## মেটাডাটা অ্যানোটেশন সহ টাইপ হিন্টস
-
-Python-এ এমন একটি ফিচার আছে যা `Annotated` ব্যবহার করে এই টাইপ হিন্টগুলিতে **অতিরিক্ত মেটাডাটা** রাখতে দেয়।
-
-//// tab | Python 3.9+
-
-Python 3.9-এ, `Annotated` স্ট্যান্ডার্ড লাইব্রেরিতে অন্তর্ভুক্ত, তাই আপনি এটি `typing` থেকে ইমপোর্ট করতে পারেন।
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-Python 3.9-এর নীচের সংস্করণগুলিতে, আপনি `Annotated`-কে `typing_extensions` থেকে ইমপোর্ট করেন।
-
-এটি **FastAPI** এর সাথে ইতিমদ্ধে ইনস্টল হয়ে থাকবে।
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013.py!}
-```
-
-////
-
-Python নিজে এই `Annotated` দিয়ে কিছুই করে না। এবং এডিটর এবং অন্যান্য টুলগুলির জন্য, টাইপটি এখনও `str`।
-
-কিন্তু আপনি এই `Annotated` এর মধ্যকার জায়গাটির মধ্যে **FastAPI**-এ কীভাবে আপনার অ্যাপ্লিকেশন আচরণ করুক তা সম্পর্কে অতিরিক্ত মেটাডাটা প্রদান করার জন্য ব্যবহার করতে পারেন।
-
-মনে রাখার গুরুত্বপূর্ণ বিষয় হল যে **প্রথম *টাইপ প্যারামিটার*** আপনি `Annotated`-এ পাস করেন সেটি হল **আসল টাইপ**। বাকি শুধুমাত্র অন্যান্য টুলগুলির জন্য মেটাডাটা।
-
-এখন আপনার কেবল জানা প্রয়োজন যে `Annotated` বিদ্যমান, এবং এটি স্ট্যান্ডার্ড Python। 😎
-
-পরবর্তীতে আপনি দেখবেন এটি কতটা **শক্তিশালী** হতে পারে।
-
-/// tip
-
-এটি **স্ট্যান্ডার্ড Python** হওয়ার মানে হল আপনি আপনার এডিটরে, আপনি যে টুলগুলি কোড বিশ্লেষণ এবং রিফ্যাক্টর করার জন্য ব্যবহার করেন তাতে **সেরা সম্ভাব্য ডেভেলপার এক্সপেরিয়েন্স** পাবেন। ✨
-
-এবং এছাড়াও আপনার কোড অন্যান্য অনেক Python টুল এবং লাইব্রেরিগুলির সাথে খুব সামঞ্জস্যপূর্ণ হবে। 🚀
-
-///
-
-## **FastAPI**-এ টাইপ হিন্টস
-
-**FastAPI** এই টাইপ হিন্টগুলি ব্যবহার করে বেশ কিছু জিনিস করে।
-
-**FastAPI**-এ আপনি টাইপ হিন্টগুলি সহ প্যারামিটার ঘোষণা করেন এবং আপনি পান:
-
-* **এডিটর সাপোর্ট**।
-* **টাইপচেক**।
-
-...এবং **FastAPI** একই ঘোষণাগুলি ব্যবহার করে:
-
-* **রিকুইরেমেন্টস সংজ্ঞায়িত করে**: রিকোয়েস্ট পাথ প্যারামিটার, কুয়েরি প্যারামিটার, হেডার, বডি, ডিপেন্ডেন্সিস, ইত্যাদি থেকে।
-* **ডেটা রূপান্তর করে**: রিকোয়েস্ট থেকে প্রয়োজনীয় টাইপে ডেটা।
-* **ডেটা যাচাই করে**: প্রতিটি রিকোয়েস্ট থেকে আসা ডেটা:
- * যখন ডেটা অবৈধ হয় তখন **স্বয়ংক্রিয় ত্রুটি** গ্রাহকের কাছে ফেরত পাঠানো।
-* **API ডকুমেন্টেশন তৈরি করে**: OpenAPI ব্যবহার করে:
- * যা স্বয়ংক্রিয় ইন্টার্যাক্টিভ ডকুমেন্টেশন ইউজার ইন্টারফেস দ্বারা ব্যবহৃত হয়।
-
-এই সব কিছু আপনার কাছে অস্পষ্ট মনে হতে পারে। চিন্তা করবেন না। আপনি [টিউটোরিয়াল - ইউজার গাইড](https://fastapi.tiangolo.com/tutorial/) এ এই সব কিছু প্র্যাকটিসে দেখতে পাবেন।
-
-গুরুত্বপূর্ণ বিষয় হল, আপনি যদি স্ট্যান্ডার্ড Python টাইপগুলি ব্যবহার করেন, তবে আরও বেশি ক্লাস, ডেকোরেটর ইত্যাদি যোগ না করেই একই স্থানে **FastAPI** আপনার অনেক কাজ করে দিবে।
-
-/// info
-
-যদি আপনি টিউটোরিয়ালের সমস্ত বিষয় পড়ে ফেলে থাকেন এবং টাইপ সম্পর্কে আরও জানতে চান, তবে একটি ভালো রিসোর্স হল [mypy এর "cheat sheet"](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html)। এই "cheat sheet" এ আপনি Python টাইপ হিন্ট সম্পর্কে বেসিক থেকে উন্নত লেভেলের ধারণা পেতে পারেন, যা আপনার কোডে টাইপ সেফটি এবং স্পষ্টতা বাড়াতে সাহায্য করবে।
-
-///
diff --git a/docs/bn/mkdocs.yml b/docs/bn/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/bn/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/de/docs/_llm-test.md b/docs/de/docs/_llm-test.md
index 4a5e5392c..0b95fe3a8 100644
--- a/docs/de/docs/_llm-test.md
+++ b/docs/de/docs/_llm-test.md
@@ -15,7 +15,7 @@ So verwenden:
Die Tests:
-## Codeschnipsel { #code-snippets}
+## Codeschnipsel { #code-snippets }
//// tab | Test
@@ -47,13 +47,13 @@ Das LLM wird dies wahrscheinlich falsch übersetzen. Interessant ist nur, ob es
//// tab | Info
-Der Prompt-Designer kann entscheiden, ob neutrale Anführungszeichen in typografische Anführungszeichen umgewandelt werden sollen. Es ist in Ordnung, sie unverändert zu lassen.
+Der Promptdesigner kann entscheiden, ob neutrale Anführungszeichen in typografische Anführungszeichen umgewandelt werden sollen. Es ist in Ordnung, sie unverändert zu lassen.
Siehe zum Beispiel den Abschnitt `### Quotes` in `docs/de/llm-prompt.md`.
////
-## Anführungszeichen in Codeschnipseln { #quotes-in-code-snippets}
+## Anführungszeichen in Codeschnipseln { #quotes-in-code-snippets }
//// tab | Test
@@ -189,7 +189,7 @@ Siehe Abschnitt `### Links` im allgemeinen Prompt in `scripts/translate.py`.
////
-## HTML „abbr“-Elemente { #html-abbr-elements }
+## HTML-„abbr“-Elemente { #html-abbr-elements }
//// tab | Test
@@ -443,7 +443,7 @@ Für einige sprachspezifische Anweisungen, siehe z. B. den Abschnitt `### Headin
* die Workload
* das Deployment
-* bereitstellen
+* deployen
* das SDK
* das Software Development Kit
@@ -459,7 +459,7 @@ Für einige sprachspezifische Anweisungen, siehe z. B. den Abschnitt `### Headin
* der Commit
* der Contextmanager
* die Coroutine
-* die Datenbank-Session
+* die Datenbanksession
* die Festplatte
* die Domain
* die Engine
@@ -496,7 +496,7 @@ Für einige sprachspezifische Anweisungen, siehe z. B. den Abschnitt `### Headin
//// tab | Info
-Dies ist eine nicht vollständige und nicht normative Liste von (meist) technischen Begriffen, die in der Dokumentation vorkommen. Sie kann dem Prompt-Designer helfen herauszufinden, bei welchen Begriffen das LLM Unterstützung braucht. Zum Beispiel, wenn es eine gute Übersetzung immer wieder auf eine suboptimale Übersetzung zurücksetzt. Oder wenn es Probleme hat, einen Begriff in Ihrer Sprache zu konjugieren/deklinieren.
+Dies ist eine nicht vollständige und nicht normative Liste von (meist) technischen Begriffen, die in der Dokumentation vorkommen. Sie kann dem Promptdesigner helfen herauszufinden, bei welchen Begriffen das LLM Unterstützung braucht. Zum Beispiel, wenn es eine gute Übersetzung immer wieder auf eine suboptimale Übersetzung zurücksetzt. Oder wenn es Probleme hat, einen Begriff in Ihrer Sprache zu konjugieren/deklinieren.
Siehe z. B. den Abschnitt `### List of English terms and their preferred German translations` in `docs/de/llm-prompt.md`.
diff --git a/docs/de/docs/advanced/additional-responses.md b/docs/de/docs/advanced/additional-responses.md
index 218dd6c4f..0f9b12251 100644
--- a/docs/de/docs/advanced/additional-responses.md
+++ b/docs/de/docs/advanced/additional-responses.md
@@ -26,7 +26,7 @@ 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:
-{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
+{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
/// note | Hinweis
@@ -175,7 +175,7 @@ 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:
-{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
+{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
/// note | Hinweis
@@ -203,7 +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:
-{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
+{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
Es wird alles kombiniert und in Ihre OpenAPI eingebunden und in der API-Dokumentation angezeigt:
@@ -237,7 +237,7 @@ Mit dieser Technik können Sie einige vordefinierte Responses in Ihren *Pfadoper
Zum Beispiel:
-{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
## Weitere Informationen zu OpenAPI-Responses { #more-information-about-openapi-responses }
diff --git a/docs/de/docs/advanced/advanced-dependencies.md b/docs/de/docs/advanced/advanced-dependencies.md
index a153665cc..e60df2883 100644
--- a/docs/de/docs/advanced/advanced-dependencies.md
+++ b/docs/de/docs/advanced/advanced-dependencies.md
@@ -63,3 +63,101 @@ In den Kapiteln zum Thema Sicherheit gibt es Hilfsfunktionen, die auf die gleich
Wenn Sie das hier alles verstanden haben, wissen Sie bereits, wie diese Sicherheits-Hilfswerkzeuge unter der Haube funktionieren.
///
+
+## Abhängigkeiten mit `yield`, `HTTPException`, `except` und Hintergrundtasks { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | Achtung
+
+Sie benötigen diese technischen Details höchstwahrscheinlich nicht.
+
+Diese Details sind hauptsächlich nützlich, wenn Sie eine FastAPI-Anwendung haben, die älter als 0.121.0 ist, und Sie auf Probleme mit Abhängigkeiten mit `yield` stoßen.
+
+///
+
+Abhängigkeiten mit `yield` haben sich im Laufe der Zeit weiterentwickelt, um verschiedene Anwendungsfälle abzudecken und einige Probleme zu beheben, hier ist eine Zusammenfassung der Änderungen.
+
+### Abhängigkeiten mit `yield` und `scope` { #dependencies-with-yield-and-scope }
+
+In Version 0.121.0 hat FastAPI Unterstützung für `Depends(scope="function")` für Abhängigkeiten mit `yield` hinzugefügt.
+
+Mit `Depends(scope="function")` wird der Exit-Code nach `yield` direkt nach dem Ende der *Pfadoperation-Funktion* ausgeführt, bevor die Response an den Client gesendet wird.
+
+Und bei Verwendung von `Depends(scope="request")` (dem Default) wird der Exit-Code nach `yield` ausgeführt, nachdem die Response gesendet wurde.
+
+Mehr dazu finden Sie in der Dokumentation zu [Abhängigkeiten mit `yield` – Frühes Beenden und `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).
+
+### Abhängigkeiten mit `yield` und `StreamingResponse`, Technische Details { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+Vor FastAPI 0.118.0 wurde bei Verwendung einer Abhängigkeit mit `yield` der Exit-Code nach der *Pfadoperation-Funktion* ausgeführt, aber unmittelbar bevor die Response gesendet wurde.
+
+Die Absicht war, Ressourcen nicht länger als nötig zu halten, während darauf gewartet wird, dass die Response durchs Netzwerk reist.
+
+Diese Änderung bedeutete auch, dass bei Rückgabe einer `StreamingResponse` der Exit-Code der Abhängigkeit mit `yield` bereits ausgeführt worden wäre.
+
+Wenn Sie beispielsweise eine Datenbanksession in einer Abhängigkeit mit `yield` hatten, konnte die `StreamingResponse` diese Session während des Streamens von Daten nicht verwenden, weil die Session im Exit-Code nach `yield` bereits geschlossen worden wäre.
+
+Dieses Verhalten wurde in 0.118.0 zurückgenommen, sodass der Exit-Code nach `yield` ausgeführt wird, nachdem die Response gesendet wurde.
+
+/// info | Info
+
+Wie Sie unten sehen werden, ähnelt dies sehr dem Verhalten vor Version 0.106.0, jedoch mit mehreren Verbesserungen und Bugfixes für Sonderfälle.
+
+///
+
+#### Anwendungsfälle mit frühem Exit-Code { #use-cases-with-early-exit-code }
+
+Es gibt einige Anwendungsfälle mit spezifischen Bedingungen, die vom alten Verhalten profitieren könnten, den Exit-Code von Abhängigkeiten mit `yield` vor dem Senden der Response auszuführen.
+
+Stellen Sie sich zum Beispiel vor, Sie haben Code, der in einer Abhängigkeit mit `yield` eine Datenbanksession verwendet, nur um einen Benutzer zu verifizieren, die Datenbanksession wird aber in der *Pfadoperation-Funktion* nie wieder verwendet, sondern nur in der Abhängigkeit, und die Response benötigt lange, um gesendet zu werden, wie eine `StreamingResponse`, die Daten langsam sendet, aus irgendeinem Grund aber die Datenbank nicht verwendet.
+
+In diesem Fall würde die Datenbanksession gehalten, bis das Senden der Response abgeschlossen ist, aber wenn Sie sie nicht verwenden, wäre es nicht notwendig, sie zu halten.
+
+So könnte es aussehen:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+Der Exit-Code, das automatische Schließen der `Session` in:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+... würde ausgeführt, nachdem die Response das langsame Senden der Daten beendet:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+Da `generate_stream()` die Datenbanksession jedoch nicht verwendet, ist es nicht wirklich notwendig, die Session während des Sendens der Response offen zu halten.
+
+Wenn Sie diesen spezifischen Anwendungsfall mit SQLModel (oder SQLAlchemy) haben, könnten Sie die Session explizit schließen, nachdem Sie sie nicht mehr benötigen:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+Auf diese Weise würde die Session die Datenbankverbindung freigeben, sodass andere Requests sie verwenden könnten.
+
+Wenn Sie einen anderen Anwendungsfall haben, der ein frühes Beenden aus einer Abhängigkeit mit `yield` benötigt, erstellen Sie bitte eine GitHub-Diskussion-Frage mit Ihrem spezifischen Anwendungsfall und warum Sie von einem frühen Schließen für Abhängigkeiten mit `yield` profitieren würden.
+
+Wenn es überzeugende Anwendungsfälle für ein frühes Schließen bei Abhängigkeiten mit `yield` gibt, würde ich erwägen, eine neue Möglichkeit hinzuzufügen, um ein frühes Schließen optional zu aktivieren.
+
+### Abhängigkeiten mit `yield` und `except`, Technische Details { #dependencies-with-yield-and-except-technical-details }
+
+Vor FastAPI 0.110.0 war es so, dass wenn Sie eine Abhängigkeit mit `yield` verwendet und dann in dieser Abhängigkeit mit `except` eine Exception abgefangen haben und die Exception nicht erneut geworfen haben, die Exception automatisch an beliebige Exceptionhandler oder den Handler für interne Serverfehler weitergereicht/weitergeworfen wurde.
+
+Dies wurde in Version 0.110.0 geändert, um unbehandelten Speicherverbrauch durch weitergeleitete Exceptions ohne Handler (interne Serverfehler) zu beheben und um es mit dem Verhalten von normalem Python-Code konsistent zu machen.
+
+### Hintergrundtasks und Abhängigkeiten mit `yield`, Technische Details { #background-tasks-and-dependencies-with-yield-technical-details }
+
+Vor FastAPI 0.106.0 war das Werfen von Exceptions nach `yield` nicht möglich, der Exit-Code in Abhängigkeiten mit `yield` wurde ausgeführt, nachdem die Response gesendet wurde, sodass [Exceptionhandler](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} bereits ausgeführt worden wären.
+
+Dies war so designt, hauptsächlich um die Verwendung derselben von Abhängigkeiten „geyieldeten“ Objekte in Hintergrundtasks zu ermöglichen, da der Exit-Code erst ausgeführt wurde, nachdem die Hintergrundtasks abgeschlossen waren.
+
+Dies wurde in FastAPI 0.106.0 geändert mit der Absicht, keine Ressourcen zu halten, während darauf gewartet wird, dass die Response durchs Netzwerk reist.
+
+/// tip | Tipp
+
+Zusätzlich ist ein Hintergrundtask normalerweise ein unabhängiger Logikblock, der separat gehandhabt werden sollte, mit eigenen Ressourcen (z. B. eigener Datenbankverbindung).
+
+So haben Sie wahrscheinlich saubereren Code.
+
+///
+
+Wenn Sie sich bisher auf dieses Verhalten verlassen haben, sollten Sie jetzt die Ressourcen für Hintergrundtasks innerhalb des Hintergrundtasks selbst erstellen und intern nur Daten verwenden, die nicht von den Ressourcen von Abhängigkeiten mit `yield` abhängen.
+
+Anstatt beispielsweise dieselbe Datenbanksession zu verwenden, würden Sie innerhalb des Hintergrundtasks eine neue Datenbanksession erstellen und die Objekte aus der Datenbank mithilfe dieser neuen Session beziehen. Und anstatt das Objekt aus der Datenbank als Parameter an die Hintergrundtask-Funktion zu übergeben, würden Sie die ID dieses Objekts übergeben und das Objekt dann innerhalb der Hintergrundtask-Funktion erneut beziehen.
diff --git a/docs/de/docs/advanced/async-tests.md b/docs/de/docs/advanced/async-tests.md
index ad8245205..7206f136f 100644
--- a/docs/de/docs/advanced/async-tests.md
+++ b/docs/de/docs/advanced/async-tests.md
@@ -32,11 +32,11 @@ Betrachten wir als einfaches Beispiel eine Dateistruktur ähnlich der in [Größ
Die Datei `main.py` hätte als Inhalt:
-{* ../../docs_src/async_tests/main.py *}
+{* ../../docs_src/async_tests/app_a_py39/main.py *}
Die Datei `test_main.py` hätte die Tests für `main.py`, das könnte jetzt so aussehen:
-{* ../../docs_src/async_tests/test_main.py *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py *}
## Es ausführen { #run-it }
@@ -56,7 +56,7 @@ $ pytest
Der Marker `@pytest.mark.anyio` teilt pytest mit, dass diese Testfunktion asynchron aufgerufen werden soll:
-{* ../../docs_src/async_tests/test_main.py hl[7] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[7] *}
/// tip | Tipp
@@ -66,7 +66,7 @@ Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wi
Dann können wir einen `AsyncClient` mit der App erstellen und mit `await` asynchrone Requests an ihn senden.
-{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[9:12] *}
Das ist das Äquivalent zu:
diff --git a/docs/de/docs/advanced/behind-a-proxy.md b/docs/de/docs/advanced/behind-a-proxy.md
index 036916cbe..1c7459050 100644
--- a/docs/de/docs/advanced/behind-a-proxy.md
+++ b/docs/de/docs/advanced/behind-a-proxy.md
@@ -44,7 +44,7 @@ $ fastapi run --forwarded-allow-ips="*"
Angenommen, Sie definieren eine *Pfadoperation* `/items/`:
-{* ../../docs_src/behind_a_proxy/tutorial001_01.py hl[6] *}
+{* ../../docs_src/behind_a_proxy/tutorial001_01_py39.py hl[6] *}
Wenn der Client versucht, zu `/items` zu gehen, würde er standardmäßig zu `/items/` umgeleitet.
@@ -64,7 +64,7 @@ Wenn Sie mehr über HTTPS erfahren möchten, lesen Sie den Leitfaden [Über HTTP
///
-### Wie Proxy-Forwarded-Header funktionieren
+### Wie Proxy-Forwarded-Header funktionieren { #how-proxy-forwarded-headers-work }
Hier ist eine visuelle Darstellung, wie der **Proxy** weitergeleitete Header zwischen dem Client und dem **Anwendungsserver** hinzufügt:
@@ -115,7 +115,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.
-{* ../../docs_src/behind_a_proxy/tutorial001.py hl[6] *}
+{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[6] *}
Und der Proxy würde das **Pfadpräfix** on-the-fly **„entfernen“**, bevor er den Request an den Anwendungsserver (wahrscheinlich Uvicorn via FastAPI CLI) ü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.
@@ -193,7 +193,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.
-{* ../../docs_src/behind_a_proxy/tutorial001.py hl[8] *}
+{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[8] *}
Wenn Sie Uvicorn dann starten mit:
@@ -220,7 +220,7 @@ wäre die http://127.0.0.1:8000/app gehen, sehen Sie die normale Response:
+Aber wenn Sie mit Ihrem Browser auf http://127.0.0.1:8000/app gehen, sehen Sie die normale Response:
```JSON
{
@@ -400,7 +400,7 @@ Wenn Sie eine benutzerdefinierte Liste von Servern (`servers`) übergeben und es
Zum Beispiel:
-{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
+{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *}
Erzeugt ein OpenAPI-Schema, wie:
@@ -443,11 +443,19 @@ Die Dokumentationsoberfläche interagiert mit dem von Ihnen ausgewählten Server
///
+/// note | Technische Details
+
+Die Eigenschaft `servers` in der OpenAPI-Spezifikation ist optional.
+
+Wenn Sie den Parameter `servers` nicht angeben und `root_path` den Wert `/` hat, wird die Eigenschaft `servers` im generierten OpenAPI-Schema standardmäßig vollständig weggelassen, was dem Äquivalent eines einzelnen Servers mit einem `url`-Wert von `/` entspricht.
+
+///
+
### Den automatischen Server von `root_path` deaktivieren { #disable-automatic-server-from-root-path }
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:
-{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
+{* ../../docs_src/behind_a_proxy/tutorial004_py39.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 8714086e5..1226fcb20 100644
--- a/docs/de/docs/advanced/custom-response.md
+++ b/docs/de/docs/advanced/custom-response.md
@@ -30,7 +30,7 @@ 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.
-{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial001b_py39.py hl[2,7] *}
/// info | Info
@@ -55,7 +55,7 @@ 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*.
-{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *}
/// info | Info
@@ -73,7 +73,7 @@ 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:
-{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
+{* ../../docs_src/custom_response/tutorial003_py39.py hl[2,7,19] *}
/// warning | Achtung
@@ -97,7 +97,7 @@ Die `response_class` wird dann nur zur Dokumentation der OpenAPI-*Pfadoperation*
Es könnte zum Beispiel so etwas sein:
-{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
+{* ../../docs_src/custom_response/tutorial004_py39.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.
@@ -136,7 +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.
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
### `HTMLResponse` { #htmlresponse }
@@ -146,7 +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.
-{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
### `JSONResponse` { #jsonresponse }
@@ -180,7 +180,7 @@ Dazu muss `ujson` installiert werden, z. B. mit `pip install ujson`.
///
-{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *}
/// tip | Tipp
@@ -194,13 +194,13 @@ Gibt eine HTTP-Weiterleitung (HTTP-Redirect) zurück. Verwendet standardmäßig
Sie können eine `RedirectResponse` direkt zurückgeben:
-{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *}
---
Oder Sie können sie im Parameter `response_class` verwenden:
-{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006b_py39.py hl[2,7,9] *}
Wenn Sie das tun, können Sie die URL direkt von Ihrer *Pfadoperation*-Funktion zurückgeben.
@@ -210,13 +210,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:
-{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *}
### `StreamingResponse` { #streamingresponse }
Nimmt einen asynchronen Generator oder einen normalen Generator/Iterator und streamt den Responsebody.
-{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *}
#### Verwendung von `StreamingResponse` mit dateiartigen Objekten { #using-streamingresponse-with-file-like-objects }
@@ -226,7 +226,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.
-{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
+{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *}
1. Das ist die Generatorfunktion. Es handelt sich um eine „Generatorfunktion“, da sie `yield`-Anweisungen enthält.
2. Durch die Verwendung eines `with`-Blocks stellen wir sicher, dass das dateiartige Objekt geschlossen wird, nachdem die Generatorfunktion fertig ist. Also, nachdem sie mit dem Senden der Response fertig ist.
@@ -255,11 +255,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.
-{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *}
Sie können auch den Parameter `response_class` verwenden:
-{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *}
In diesem Fall können Sie den Dateipfad direkt von Ihrer *Pfadoperation*-Funktion zurückgeben.
@@ -273,7 +273,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:
-{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *}
Statt:
@@ -299,7 +299,7 @@ Der Parameter, der das definiert, ist `default_response_class`.
Im folgenden Beispiel verwendet **FastAPI** standardmäßig `ORJSONResponse` in allen *Pfadoperationen*, anstelle von `JSONResponse`.
-{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *}
/// tip | Tipp
diff --git a/docs/de/docs/advanced/dataclasses.md b/docs/de/docs/advanced/dataclasses.md
index 12ea8e9ec..52b9634ae 100644
--- a/docs/de/docs/advanced/dataclasses.md
+++ b/docs/de/docs/advanced/dataclasses.md
@@ -4,7 +4,7 @@ FastAPI basiert auf **Pydantic**, und ich habe Ihnen gezeigt, wie Sie Pydantic-M
Aber FastAPI unterstützt auf die gleiche Weise auch die Verwendung von `dataclasses`:
-{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
Das ist dank **Pydantic** ebenfalls möglich, da es `dataclasses` intern unterstützt.
@@ -32,7 +32,7 @@ Wenn Sie jedoch eine Menge Datenklassen herumliegen haben, ist dies ein guter Tr
Sie können `dataclasses` auch im Parameter `response_model` verwenden:
-{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}
Die Datenklasse wird automatisch in eine Pydantic-Datenklasse konvertiert.
@@ -48,7 +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:
-{* ../../docs_src/dataclasses/tutorial003.py hl[1,5,8:11,14:17,23:25,28] *}
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
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 2ceef1190..7e1191b55 100644
--- a/docs/de/docs/advanced/events.md
+++ b/docs/de/docs/advanced/events.md
@@ -30,7 +30,7 @@ Beginnen wir mit einem Beispiel und sehen es uns dann im Detail an.
Wir erstellen eine asynchrone Funktion `lifespan()` mit `yield` wie folgt:
-{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[16,19] *}
Hier simulieren wir den langsamen *Startup*, 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 *Startups*.
@@ -48,7 +48,7 @@ Möglicherweise müssen Sie eine neue Version starten, oder Sie haben es einfach
Das Erste, was auffällt, ist, dass wir eine asynchrone Funktion mit `yield` definieren. Das ist sehr ähnlich zu Abhängigkeiten mit `yield`.
-{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[14:19] *}
Der erste Teil der Funktion, vor dem `yield`, wird ausgeführt **bevor** die Anwendung startet.
@@ -60,7 +60,7 @@ Wie Sie sehen, ist die Funktion mit einem `@asynccontextmanager` versehen.
Dadurch wird die Funktion in einen sogenannten „**asynchronen Kontextmanager**“ umgewandelt.
-{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+{* ../../docs_src/events/tutorial003_py39.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:
@@ -82,7 +82,7 @@ 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.
-{* ../../docs_src/events/tutorial003.py hl[22] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[22] *}
## Alternative Events (deprecatet) { #alternative-events-deprecated }
@@ -104,7 +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`:
-{* ../../docs_src/events/tutorial001.py hl[8] *}
+{* ../../docs_src/events/tutorial001_py39.py hl[8] *}
In diesem Fall initialisiert die Eventhandler-Funktion `startup` die „Datenbank“ der Items (nur ein `dict`) mit einigen Werten.
@@ -116,7 +116,7 @@ Und Ihre Anwendung empfängt erst dann Requests, wenn alle `startup`-Eventhandle
Um eine Funktion hinzuzufügen, die beim Shutdown der Anwendung ausgeführt werden soll, deklarieren Sie sie mit dem Event `shutdown`:
-{* ../../docs_src/events/tutorial002.py hl[6] *}
+{* ../../docs_src/events/tutorial002_py39.py hl[6] *}
Hier schreibt die `shutdown`-Eventhandler-Funktion eine Textzeile `"Application shutdown"` in eine Datei `log.txt`.
@@ -154,7 +154,7 @@ In der technischen ASGI-Spezifikation ist dies Teil des Starlettes Lifespan-Dokumentation.
+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.
diff --git a/docs/de/docs/advanced/generate-clients.md b/docs/de/docs/advanced/generate-clients.md
index d8836295b..659343f5b 100644
--- a/docs/de/docs/advanced/generate-clients.md
+++ b/docs/de/docs/advanced/generate-clients.md
@@ -167,7 +167,7 @@ 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 präfixierten Tag entfernen**:
-{* ../../docs_src/generate_clients/tutorial004.py *}
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
//// tab | Node.js
diff --git a/docs/de/docs/advanced/middleware.md b/docs/de/docs/advanced/middleware.md
index 0a2a39699..ccc6a64c3 100644
--- a/docs/de/docs/advanced/middleware.md
+++ b/docs/de/docs/advanced/middleware.md
@@ -57,13 +57,13 @@ Erzwingt, dass alle eingehenden Uvicorns `ProxyHeadersMiddleware`
* MessagePack
-Um mehr über weitere verfügbare Middlewares herauszufinden, besuchen Sie Starlettes Middleware-Dokumentation und die ASGI Awesome List.
+Um mehr über weitere verfügbare Middlewares herauszufinden, besuchen Sie Starlettes Middleware-Dokumentation und die ASGI Awesome List.
diff --git a/docs/de/docs/advanced/openapi-callbacks.md b/docs/de/docs/advanced/openapi-callbacks.md
index afc48bbb8..fd68ab8dc 100644
--- a/docs/de/docs/advanced/openapi-callbacks.md
+++ b/docs/de/docs/advanced/openapi-callbacks.md
@@ -31,7 +31,7 @@ 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:
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *}
/// tip | Tipp
@@ -90,7 +90,7 @@ Wenn Sie diese Sichtweise (des *externen Entwicklers*) vorübergehend übernehme
Erstellen Sie zunächst einen neuen `APIRouter`, der einen oder mehrere Callbacks enthält.
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *}
### Die Callback-*Pfadoperation* erstellen { #create-the-callback-path-operation }
@@ -101,7 +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`.
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *}
Es gibt zwei Hauptunterschiede zu einer normalen *Pfadoperation*:
@@ -169,7 +169,7 @@ 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:
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Tipp
diff --git a/docs/de/docs/advanced/openapi-webhooks.md b/docs/de/docs/advanced/openapi-webhooks.md
index a09a675ed..ca9c63960 100644
--- a/docs/de/docs/advanced/openapi-webhooks.md
+++ b/docs/de/docs/advanced/openapi-webhooks.md
@@ -32,7 +32,7 @@ Webhooks sind in OpenAPI 3.1.0 und höher verfügbar und werden von FastAPI `0.9
Wenn Sie eine **FastAPI**-Anwendung erstellen, gibt es ein `webhooks`-Attribut, das Sie verwenden können, um *Webhooks* zu definieren, genauso wie Sie *Pfadoperationen* definieren würden, zum Beispiel mit `@app.webhooks.post()`.
-{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *}
Die von Ihnen definierten Webhooks landen im **OpenAPI**-Schema und der automatischen **Dokumentations-Oberfläche**.
diff --git a/docs/de/docs/advanced/path-operation-advanced-configuration.md b/docs/de/docs/advanced/path-operation-advanced-configuration.md
index f5ec7c49e..c7ac1cf61 100644
--- a/docs/de/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/de/docs/advanced/path-operation-advanced-configuration.md
@@ -12,7 +12,7 @@ Mit dem Parameter `operation_id` können Sie die OpenAPI `operationId` festlegen
Sie müssten sicherstellen, dass sie für jede Operation eindeutig ist.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *}
### Verwendung des Namens der *Pfadoperation-Funktion* als operationId { #using-the-path-operation-function-name-as-the-operationid }
@@ -20,7 +20,7 @@ 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.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *}
/// tip | Tipp
@@ -40,7 +40,7 @@ Auch wenn diese sich in unterschiedlichen Modulen (Python-Dateien) befinden.
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`:
-{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *}
## Fortgeschrittene Beschreibung mittels Docstring { #advanced-description-from-docstring }
@@ -48,9 +48,9 @@ Sie können die verwendeten Zeilen aus dem Docstring einer *Pfadoperation-Funkti
Das Hinzufügen eines `\f` (ein maskiertes „Form Feed“-Zeichen) führt dazu, dass **FastAPI** die für OpenAPI verwendete Ausgabe an dieser Stelle abschneidet.
-Sie wird nicht in der Dokumentation angezeigt, aber andere Tools (z. B. Sphinx) können den Rest verwenden.
+Sie wird nicht in der Dokumentation angezeigt, aber andere Tools (wie z. B. Sphinx) können den Rest verwenden.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
## Zusätzliche Responses { #additional-responses }
@@ -92,7 +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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions) zu deklarieren:
-{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *}
Wenn Sie die automatische API-Dokumentation öffnen, wird Ihre Erweiterung am Ende der spezifischen *Pfadoperation* angezeigt.
@@ -139,7 +139,7 @@ Sie könnten sich beispielsweise dafür entscheiden, den geparst, sondern direkt als `bytes` gelesen und die Funktion `magic_data_reader()` wäre dafür verantwortlich, ihn in irgendeiner Weise zu parsen.
@@ -153,47 +153,15 @@ Und Sie könnten dies auch tun, wenn der Datentyp im Request 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:
-//// 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 | 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_py39.py hl[15:20, 22] *}
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.
-Dann verwenden wir den Request direkt und extrahieren den Body als `bytes`. Das bedeutet, dass FastAPI nicht einmal versucht, den Request-Payload als JSON zu parsen.
+Dann verwenden wir den Request direkt und extrahieren den Body als `bytes`. Das bedeutet, dass FastAPI nicht einmal versucht, die Request-Payload als JSON zu parsen.
Und dann parsen wir in unserem Code diesen YAML-Inhalt direkt und verwenden dann wieder dasselbe Pydantic-Modell, um den YAML-Inhalt zu validieren:
-//// 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 | 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_py39.py hl[24:31] *}
/// tip | Tipp
diff --git a/docs/de/docs/advanced/response-change-status-code.md b/docs/de/docs/advanced/response-change-status-code.md
index b079e241d..b209c2d67 100644
--- a/docs/de/docs/advanced/response-change-status-code.md
+++ b/docs/de/docs/advanced/response-change-status-code.md
@@ -20,7 +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.
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *}
Und dann können Sie jedes benötigte Objekt zurückgeben, wie Sie es normalerweise tun würden (ein `dict`, ein Datenbankmodell usw.).
diff --git a/docs/de/docs/advanced/response-cookies.md b/docs/de/docs/advanced/response-cookies.md
index 0dd4175dd..87e636cfa 100644
--- a/docs/de/docs/advanced/response-cookies.md
+++ b/docs/de/docs/advanced/response-cookies.md
@@ -6,7 +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.
-{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *}
Anschließend können Sie wie gewohnt jedes gewünschte Objekt zurückgeben (ein `dict`, ein Datenbankmodell, usw.).
@@ -24,7 +24,7 @@ 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:
-{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
/// tip | Tipp
@@ -48,4 +48,4 @@ Und da die `Response` häufig zum Setzen von Headern und Cookies verwendet wird,
///
-Um alle verfügbaren Parameter und Optionen anzuzeigen, sehen Sie sich deren Dokumentation in Starlette an.
+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 d99517373..0a28a6d0e 100644
--- a/docs/de/docs/advanced/response-directly.md
+++ b/docs/de/docs/advanced/response-directly.md
@@ -34,7 +34,7 @@ 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:
-{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
/// note | Technische Details
@@ -54,7 +54,7 @@ Nehmen wir an, Sie möchten eine Response-Objekt festlegen.
-{* ../../docs_src/response_headers/tutorial002.py hl[1, 7:8] *}
+{* ../../docs_src/response_headers/tutorial002_py39.py hl[1, 7:8] *}
Anschließend können Sie wie gewohnt jedes gewünschte Objekt zurückgeben (ein `dict`, ein Datenbankmodell, usw.).
@@ -22,7 +22,7 @@ Sie können auch Header hinzufügen, wenn Sie eine `Response` direkt zurückgebe
Erstellen Sie eine Response wie in [Eine Response direkt zurückgeben](response-directly.md){.internal-link target=_blank} beschrieben und übergeben Sie die Header als zusätzlichen Parameter:
-{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_headers/tutorial001_py39.py hl[10:12] *}
/// note | Technische Details
@@ -38,4 +38,4 @@ Und da die `Response` häufig zum Setzen von Headern und Cookies verwendet wird,
Beachten Sie, dass benutzerdefinierte proprietäre Header mittels des Präfix `X-` hinzugefügt werden können.
-Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen können soll, müssen Sie diese zu Ihrer CORS-Konfiguration hinzufügen (weitere Informationen finden Sie unter [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), unter Verwendung des Parameters `expose_headers`, dokumentiert in Starlettes CORS-Dokumentation.
+Wenn Sie jedoch benutzerdefinierte Header haben, die ein Client in einem Browser sehen können soll, müssen Sie diese zu Ihrer CORS-Konfiguration hinzufügen (weitere Informationen finden Sie unter [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), unter Verwendung des Parameters `expose_headers`, dokumentiert in Starlettes CORS-Dokumentation.
diff --git a/docs/de/docs/advanced/settings.md b/docs/de/docs/advanced/settings.md
index ccd7f373d..ea4540e10 100644
--- a/docs/de/docs/advanced/settings.md
+++ b/docs/de/docs/advanced/settings.md
@@ -60,23 +60,7 @@ Auf die gleiche Weise wie bei Pydantic-Modellen deklarieren Sie Klassenattribute
Sie können dieselben Validierungs-Funktionen und -Tools verwenden, die Sie für Pydantic-Modelle verwenden, z. B. verschiedene Datentypen und zusätzliche Validierungen mit `Field()`.
-//// tab | Pydantic v2
-
-{* ../../docs_src/settings/tutorial001.py hl[2,5:8,11] *}
-
-////
-
-//// tab | Pydantic v1
-
-/// info | Info
-
-In Pydantic v1 würden Sie `BaseSettings` direkt von `pydantic` statt von `pydantic_settings` importieren.
-
-///
-
-{* ../../docs_src/settings/tutorial001_pv1.py hl[2,5:8,11] *}
-
-////
+{* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *}
/// tip | Tipp
@@ -92,7 +76,7 @@ Als Nächstes werden die Daten konvertiert und validiert. Wenn Sie also dieses `
Dann können Sie das neue `settings`-Objekt in Ihrer Anwendung verwenden:
-{* ../../docs_src/settings/tutorial001.py hl[18:20] *}
+{* ../../docs_src/settings/tutorial001_py39.py hl[18:20] *}
### Den Server ausführen { #run-the-server }
@@ -126,11 +110,11 @@ Sie könnten diese Einstellungen in eine andere Moduldatei einfügen, wie Sie in
Sie könnten beispielsweise eine Datei `config.py` haben mit:
-{* ../../docs_src/settings/app01/config.py *}
+{* ../../docs_src/settings/app01_py39/config.py *}
Und dann verwenden Sie diese in einer Datei `main.py`:
-{* ../../docs_src/settings/app01/main.py hl[3,11:13] *}
+{* ../../docs_src/settings/app01_py39/main.py hl[3,11:13] *}
/// tip | Tipp
@@ -148,7 +132,7 @@ Dies könnte besonders beim Testen nützlich sein, da es sehr einfach ist, eine
Ausgehend vom vorherigen Beispiel könnte Ihre Datei `config.py` so aussehen:
-{* ../../docs_src/settings/app02/config.py hl[10] *}
+{* ../../docs_src/settings/app02_an_py39/config.py hl[10] *}
Beachten Sie, dass wir jetzt keine Standardinstanz `settings = Settings()` erstellen.
@@ -174,7 +158,7 @@ Und dann können wir das von der *Pfadoperation-Funktion* als Abhängigkeit einf
Dann wäre es sehr einfach, beim Testen ein anderes Einstellungsobjekt bereitzustellen, indem man eine Abhängigkeitsüberschreibung für `get_settings` erstellt:
-{* ../../docs_src/settings/app02/test_main.py hl[9:10,13,21] *}
+{* ../../docs_src/settings/app02_an_py39/test_main.py hl[9:10,13,21] *}
Bei der Abhängigkeitsüberschreibung legen wir einen neuen Wert für `admin_email` fest, wenn wir das neue `Settings`-Objekt erstellen, und geben dann dieses neue Objekt zurück.
@@ -215,9 +199,7 @@ APP_NAME="ChimichangApp"
Und dann aktualisieren Sie Ihre `config.py` mit:
-//// tab | Pydantic v2
-
-{* ../../docs_src/settings/app03_an/config.py hl[9] *}
+{* ../../docs_src/settings/app03_an_py39/config.py hl[9] *}
/// tip | Tipp
@@ -225,26 +207,6 @@ Das Attribut `model_config` wird nur für die Pydantic-Konfiguration verwendet.
///
-////
-
-//// tab | Pydantic v1
-
-{* ../../docs_src/settings/app03_an/config_pv1.py hl[9:10] *}
-
-/// tip | Tipp
-
-Die Klasse `Config` wird nur für die Pydantic-Konfiguration verwendet. Weitere Informationen finden Sie unter Pydantic Model Config.
-
-///
-
-////
-
-/// info | Info
-
-In Pydantic Version 1 erfolgte die Konfiguration in einer internen Klasse `Config`, in Pydantic Version 2 erfolgt sie in einem Attribut `model_config`. Dieses Attribut akzeptiert ein `dict`. Um automatische Codevervollständigung und Inline-Fehlerberichte zu erhalten, können Sie `SettingsConfigDict` importieren und verwenden, um dieses `dict` zu definieren.
-
-///
-
Hier definieren wir die Konfiguration `env_file` innerhalb Ihrer Pydantic-`Settings`-Klasse und setzen den Wert auf den Dateinamen mit der dotenv-Datei, die wir verwenden möchten.
### Die `Settings` nur einmal laden mittels `lru_cache` { #creating-the-settings-only-once-with-lru-cache }
diff --git a/docs/de/docs/advanced/sub-applications.md b/docs/de/docs/advanced/sub-applications.md
index d634aac23..081574d0a 100644
--- a/docs/de/docs/advanced/sub-applications.md
+++ b/docs/de/docs/advanced/sub-applications.md
@@ -10,7 +10,7 @@ Wenn Sie zwei unabhängige FastAPI-Anwendungen mit deren eigenen unabhängigen O
Erstellen Sie zunächst die Hauptanwendung **FastAPI** und deren *Pfadoperationen*:
-{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[3, 6:8] *}
### Unteranwendung { #sub-application }
@@ -18,7 +18,7 @@ Erstellen Sie dann Ihre Unteranwendung und deren *Pfadoperationen*.
Diese Unteranwendung ist nur eine weitere Standard-FastAPI-Anwendung, aber diese wird „gemountet“:
-{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 14:16] *}
### Die Unteranwendung mounten { #mount-the-sub-application }
@@ -26,7 +26,7 @@ Mounten Sie in Ihrer Top-Level-Anwendung `app` die Unteranwendung `subapi`.
In diesem Fall wird sie im Pfad `/subapi` gemountet:
-{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *}
+{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 19] *}
### Die automatische API-Dokumentation testen { #check-the-automatic-api-docs }
diff --git a/docs/de/docs/advanced/templates.md b/docs/de/docs/advanced/templates.md
index fdaeb3413..97a45e612 100644
--- a/docs/de/docs/advanced/templates.md
+++ b/docs/de/docs/advanced/templates.md
@@ -27,7 +27,7 @@ $ pip install jinja2
* Deklarieren Sie einen `Request`-Parameter in der *Pfadoperation*, welcher ein Template zurückgibt.
* Verwenden Sie die von Ihnen erstellten `templates`, um eine `TemplateResponse` zu rendern und zurückzugeben, übergeben Sie den Namen des Templates, das Requestobjekt und ein „Kontext“-Dictionary mit Schlüssel-Wert-Paaren, die innerhalb des Jinja2-Templates verwendet werden sollen.
-{* ../../docs_src/templates/tutorial001.py hl[4,11,15:18] *}
+{* ../../docs_src/templates/tutorial001_py39.py hl[4,11,15:18] *}
/// note | Hinweis
@@ -123,4 +123,4 @@ Und da Sie `StaticFiles` verwenden, wird diese CSS-Datei automatisch von Ihrer *
## Mehr Details { #more-details }
-Weitere Informationen, einschließlich, wie man Templates testet, finden Sie in Starlettes Dokumentation zu Templates.
+Weitere Informationen, einschließlich, wie man Templates testet, finden Sie in Starlettes Dokumentation zu Templates.
diff --git a/docs/de/docs/advanced/testing-events.md b/docs/de/docs/advanced/testing-events.md
index 1a68b7714..5b12f3f18 100644
--- a/docs/de/docs/advanced/testing-events.md
+++ b/docs/de/docs/advanced/testing-events.md
@@ -2,11 +2,11 @@
Wenn Sie `lifespan` in Ihren Tests ausführen müssen, können Sie den `TestClient` mit einer `with`-Anweisung verwenden:
-{* ../../docs_src/app_testing/tutorial004.py hl[9:15,18,27:28,30:32,41:43] *}
+{* ../../docs_src/app_testing/tutorial004_py39.py hl[9:15,18,27:28,30:32,41:43] *}
-Sie können mehr Details unter [„Lifespan in Tests ausführen in der offiziellen Starlette-Dokumentation.“](https://www.starlette.io/lifespan/#running-lifespan-in-tests) nachlesen.
+Sie können mehr Details unter [„Lifespan in Tests ausführen in der offiziellen Starlette-Dokumentation.“](https://www.starlette.dev/lifespan/#running-lifespan-in-tests) nachlesen.
Für die deprecateten Events `startup` und `shutdown` können Sie den `TestClient` wie folgt verwenden:
-{* ../../docs_src/app_testing/tutorial003.py hl[9:12,20:24] *}
+{* ../../docs_src/app_testing/tutorial003_py39.py hl[9:12,20:24] *}
diff --git a/docs/de/docs/advanced/testing-websockets.md b/docs/de/docs/advanced/testing-websockets.md
index a71310cbf..9ecca7a4f 100644
--- a/docs/de/docs/advanced/testing-websockets.md
+++ b/docs/de/docs/advanced/testing-websockets.md
@@ -4,10 +4,10 @@ Sie können den schon bekannten `TestClient` zum Testen von WebSockets verwenden
Dazu verwenden Sie den `TestClient` in einer `with`-Anweisung, eine Verbindung zum WebSocket herstellend:
-{* ../../docs_src/app_testing/tutorial002.py hl[27:31] *}
+{* ../../docs_src/app_testing/tutorial002_py39.py hl[27:31] *}
/// note | Hinweis
-Weitere Informationen finden Sie in Starlettes Dokumentation zum Testen von WebSockets.
+Weitere Informationen finden Sie in Starlettes Dokumentation zum Testen von WebSockets.
///
diff --git a/docs/de/docs/advanced/using-request-directly.md b/docs/de/docs/advanced/using-request-directly.md
index 7782237ec..36d73b806 100644
--- a/docs/de/docs/advanced/using-request-directly.md
+++ b/docs/de/docs/advanced/using-request-directly.md
@@ -15,7 +15,7 @@ Es gibt jedoch Situationen, in denen Sie möglicherweise direkt auf das `Request
## Details zum `Request`-Objekt { #details-about-the-request-object }
-Da **FastAPI** unter der Haube eigentlich **Starlette** ist, mit einer Ebene von mehreren Tools darüber, können Sie Starlettes `Request`-Objekt direkt verwenden, wenn Sie es benötigen.
+Da **FastAPI** unter der Haube eigentlich **Starlette** ist, mit einer Ebene von mehreren Tools darüber, können Sie Starlettes `Request`-Objekt direkt verwenden, wenn Sie es benötigen.
Das bedeutet allerdings auch, dass, wenn Sie Daten direkt vom `Request`-Objekt nehmen (z. B. dessen Body lesen), diese von FastAPI nicht validiert, konvertiert oder dokumentiert werden (mit OpenAPI, für die automatische API-Benutzeroberfläche).
@@ -29,7 +29,7 @@ Angenommen, Sie möchten auf die IP-Adresse/den Host des Clients in Ihrer *Pfado
Dazu müssen Sie direkt auf den Request zugreifen.
-{* ../../docs_src/using_request_directly/tutorial001.py hl[1,7:8] *}
+{* ../../docs_src/using_request_directly/tutorial001_py39.py hl[1,7:8] *}
Durch die Deklaration eines *Pfadoperation-Funktionsparameters*, dessen Typ der `Request` ist, weiß **FastAPI**, dass es den `Request` diesem Parameter übergeben soll.
@@ -45,7 +45,7 @@ Auf die gleiche Weise können Sie wie gewohnt jeden anderen Parameter deklariere
## `Request`-Dokumentation { #request-documentation }
-Weitere Details zum `Request`-Objekt finden Sie in der offiziellen Starlette-Dokumentation.
+Weitere Details zum `Request`-Objekt finden Sie in der offiziellen Starlette-Dokumentation.
/// note | Technische Details
diff --git a/docs/de/docs/advanced/websockets.md b/docs/de/docs/advanced/websockets.md
index ad1f6f5b1..05ae5a4b3 100644
--- a/docs/de/docs/advanced/websockets.md
+++ b/docs/de/docs/advanced/websockets.md
@@ -38,13 +38,13 @@ In der Produktion hätten Sie eine der oben genannten Optionen.
Aber es ist der einfachste Weg, sich auf die Serverseite von WebSockets zu konzentrieren und ein funktionierendes Beispiel zu haben:
-{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *}
+{* ../../docs_src/websockets/tutorial001_py39.py hl[2,6:38,41:43] *}
## Einen `websocket` erstellen { #create-a-websocket }
Erstellen Sie in Ihrer **FastAPI**-Anwendung einen `websocket`:
-{* ../../docs_src/websockets/tutorial001.py hl[1,46:47] *}
+{* ../../docs_src/websockets/tutorial001_py39.py hl[1,46:47] *}
/// note | Technische Details
@@ -58,7 +58,7 @@ Sie könnten auch `from starlette.websockets import WebSocket` verwenden.
In Ihrer WebSocket-Route können Sie Nachrichten `await`en und Nachrichten senden.
-{* ../../docs_src/websockets/tutorial001.py hl[48:52] *}
+{* ../../docs_src/websockets/tutorial001_py39.py hl[48:52] *}
Sie können Binär-, Text- und JSON-Daten empfangen und senden.
@@ -182,5 +182,5 @@ Wenn Sie etwas benötigen, das sich leicht in FastAPI integrieren lässt, aber r
Weitere Informationen zu Optionen finden Sie in der Dokumentation von Starlette:
-* Die `WebSocket`-Klasse.
-* Klassen-basierte Handhabung von WebSockets.
+* Die `WebSocket`-Klasse.
+* Klassen-basierte Handhabung von WebSockets.
diff --git a/docs/de/docs/advanced/wsgi.md b/docs/de/docs/advanced/wsgi.md
index 1de9739dd..3cd776a6a 100644
--- a/docs/de/docs/advanced/wsgi.md
+++ b/docs/de/docs/advanced/wsgi.md
@@ -12,7 +12,7 @@ Wrappen Sie dann die WSGI-Anwendung (z. B. Flask) mit der Middleware.
Und dann mounten Sie das auf einem Pfad.
-{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *}
+{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *}
## Es testen { #check-it }
diff --git a/docs/de/docs/alternatives.md b/docs/de/docs/alternatives.md
index 15c0719fb..4dd127dba 100644
--- a/docs/de/docs/alternatives.md
+++ b/docs/de/docs/alternatives.md
@@ -417,7 +417,7 @@ Die gesamte Datenvalidierung, Datenserialisierung und automatische Modelldokumen
///
-### Starlette { #starlette }
+### Starlette { #starlette }
Starlette ist ein leichtgewichtiges ASGI-Framework/Toolkit, welches sich ideal für die Erstellung hochperformanter asynchroner Dienste eignet.
@@ -462,7 +462,7 @@ Alles, was Sie also mit Starlette machen können, können Sie direkt mit **FastA
///
-### Uvicorn { #uvicorn }
+### Uvicorn { #uvicorn }
Uvicorn ist ein blitzschneller ASGI-Server, der auf uvloop und httptools basiert.
diff --git a/docs/de/docs/deployment/cloud.md b/docs/de/docs/deployment/cloud.md
index ca1ba3b3b..ad3ff76db 100644
--- a/docs/de/docs/deployment/cloud.md
+++ b/docs/de/docs/deployment/cloud.md
@@ -1,16 +1,24 @@
-# FastAPI bei Cloudanbietern bereitstellen { #deploy-fastapi-on-cloud-providers }
+# FastAPI bei Cloudanbietern deployen { #deploy-fastapi-on-cloud-providers }
Sie können praktisch **jeden Cloudanbieter** verwenden, um Ihre FastAPI-Anwendung bereitzustellen.
-In den meisten Fällen bieten die großen Cloudanbieter Anleitungen zum Bereitstellen von FastAPI an.
+In den meisten Fällen bieten die großen Cloudanbieter Anleitungen zum Deployment von FastAPI an.
-## Cloudanbieter – Sponsoren { #cloud-providers-sponsors }
+## FastAPI Cloud { #fastapi-cloud }
+
+**FastAPI Cloud** wurde vom selben Autor und Team hinter **FastAPI** entwickelt.
+
+Es vereinfacht den Prozess des **Erstellens**, **Deployens** und **Zugreifens** auf eine API mit minimalem Aufwand.
-Einige Cloudanbieter ✨ [**sponsern FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, dies stellt die kontinuierliche und gesunde **Entwicklung** von FastAPI und seinem **Ökosystem** sicher.
+Es bringt die gleiche **Developer-Experience** beim Erstellen von Apps mit FastAPI auch zum **Deployment** in der Cloud. 🎉
+
+FastAPI Cloud ist der Hauptsponsor und Finanzierungsgeber für die *FastAPI and friends* Open-Source-Projekte. ✨
+
+## Cloudanbieter – Sponsoren { #cloud-providers-sponsors }
-Und es zeigt ihr wahres Engagement für FastAPI und seine **Community** (Sie), da sie Ihnen nicht nur einen **guten Service** bieten möchten, sondern auch sicherstellen möchten, dass Sie ein **gutes und gesundes Framework**, FastAPI, haben. 🙇
+Einige andere Cloudanbieter ✨ [**sponsern FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ ebenfalls. 🙇
-Vielleicht möchten Sie deren Dienste ausprobieren und deren Anleitungen folgen:
+Sie könnten diese ebenfalls in Betracht ziehen, deren Anleitungen folgen und ihre Dienste ausprobieren:
* Render
* Railway
diff --git a/docs/de/docs/deployment/concepts.md b/docs/de/docs/deployment/concepts.md
index ef0f458a7..dde922805 100644
--- a/docs/de/docs/deployment/concepts.md
+++ b/docs/de/docs/deployment/concepts.md
@@ -1,6 +1,6 @@
# Deployment-Konzepte { #deployments-concepts }
-Bei dem Deployment – der Bereitstellung – einer **FastAPI**-Anwendung, oder eigentlich jeder Art von Web-API, gibt es mehrere Konzepte, die Sie wahrscheinlich interessieren, und mithilfe der Sie die **am besten geeignete** Methode zur **Bereitstellung Ihrer Anwendung** finden können.
+Bei dem Deployment – der Bereitstellung – einer **FastAPI**-Anwendung, oder eigentlich jeder Art von Web-API, gibt es mehrere Konzepte, die Sie wahrscheinlich interessieren, und mithilfe der Sie die **am besten geeignete** Methode zum **Deployment Ihrer Anwendung** finden können.
Einige wichtige Konzepte sind:
@@ -15,11 +15,11 @@ Wir werden sehen, wie diese sich auf das **Deployment** auswirken.
Letztendlich besteht das ultimative Ziel darin, **Ihre API-Clients** auf **sichere** Weise zu versorgen, um **Unterbrechungen** zu vermeiden und die **Rechenressourcen** (z. B. entfernte Server/virtuelle Maschinen) so effizient wie möglich zu nutzen. 🚀
-Ich erzähle Ihnen hier etwas mehr über diese **Konzepte**, was Ihnen hoffentlich die **Intuition** gibt, die Sie benötigen, um zu entscheiden, wie Sie Ihre API in sehr unterschiedlichen Umgebungen bereitstellen, möglicherweise sogar in **zukünftigen**, die jetzt noch nicht existieren.
+Ich erzähle Ihnen hier etwas mehr über diese **Konzepte**, was Ihnen hoffentlich die **Intuition** gibt, die Sie benötigen, um zu entscheiden, wie Sie Ihre API in sehr unterschiedlichen Umgebungen deployen, möglicherweise sogar in **zukünftigen**, die jetzt noch nicht existieren.
-Durch die Berücksichtigung dieser Konzepte können Sie die beste Variante der Bereitstellung **Ihrer eigenen APIs** **evaluieren und konzipieren**.
+Durch die Berücksichtigung dieser Konzepte können Sie die beste Variante des Deployments **Ihrer eigenen APIs** **evaluieren und konzipieren**.
-In den nächsten Kapiteln werde ich Ihnen mehr **konkrete Rezepte** für die Bereitstellung von FastAPI-Anwendungen geben.
+In den nächsten Kapiteln werde ich Ihnen mehr **konkrete Rezepte** für das Deployment von FastAPI-Anwendungen geben.
Aber schauen wir uns zunächst einmal diese grundlegenden **konzeptionellen Ideen** an. Diese Konzepte gelten auch für jede andere Art von Web-API. 💡
@@ -271,7 +271,7 @@ In diesem Fall müssen Sie sich darüber keine Sorgen machen. 🤷
### Beispiele für Strategien für Vorab-Schritte { #examples-of-previous-steps-strategies }
-Es hängt **stark** davon ab, wie Sie **Ihr System bereitstellen**, und hängt wahrscheinlich mit der Art und Weise zusammen, wie Sie Programme starten, Neustarts durchführen, usw.
+Es hängt **stark** davon ab, wie Sie **Ihr System deployen**, und hängt wahrscheinlich mit der Art und Weise zusammen, wie Sie Programme starten, Neustarts durchführen, usw.
Hier sind einige mögliche Ideen:
@@ -307,7 +307,7 @@ Sie können einfache Tools wie `htop` verwenden, um die in Ihrem Server verwende
## Zusammenfassung { #recap }
-Sie haben hier einige der wichtigsten Konzepte gelesen, die Sie wahrscheinlich berücksichtigen müssen, wenn Sie entscheiden, wie Sie Ihre Anwendung bereitstellen:
+Sie haben hier einige der wichtigsten Konzepte gelesen, die Sie wahrscheinlich berücksichtigen müssen, wenn Sie entscheiden, wie Sie Ihre Anwendung deployen:
* Sicherheit – HTTPS
* Beim Hochfahren ausführen
diff --git a/docs/de/docs/deployment/docker.md b/docs/de/docs/deployment/docker.md
index 52ac99913..d4b74635d 100644
--- a/docs/de/docs/deployment/docker.md
+++ b/docs/de/docs/deployment/docker.md
@@ -1,6 +1,6 @@
# FastAPI in Containern – Docker { #fastapi-in-containers-docker }
-Beim Deployment von FastAPI-Anwendungen besteht ein gängiger Ansatz darin, ein **Linux-Containerimage** zu erstellen. Normalerweise erfolgt dies mit **Docker**. Sie können dieses Containerimage dann auf eine von mehreren möglichen Arten bereitstellen.
+Beim Deployment von FastAPI-Anwendungen besteht ein gängiger Ansatz darin, ein **Linux-Containerimage** zu erstellen. Normalerweise erfolgt dies mit **Docker**. Sie können dieses Containerimage dann auf eine von mehreren möglichen Arten deployen.
Die Verwendung von Linux-Containern bietet mehrere Vorteile, darunter **Sicherheit**, **Replizierbarkeit**, **Einfachheit** und andere.
@@ -40,7 +40,7 @@ Linux-Container werden mit demselben Linux-Kernel des Hosts (Maschine, virtuelle
Auf diese Weise verbrauchen Container **wenig Ressourcen**, eine Menge vergleichbar mit der direkten Ausführung der Prozesse (eine virtuelle Maschine würde viel mehr verbrauchen).
-Container verfügen außerdem über ihre eigenen **isoliert** laufenden Prozesse (üblicherweise nur einen Prozess), über ihr eigenes Dateisystem und ihr eigenes Netzwerk, was die Bereitstellung, Sicherheit, Entwicklung usw. vereinfacht.
+Container verfügen außerdem über ihre eigenen **isoliert** laufenden Prozesse (üblicherweise nur einen Prozess), über ihr eigenes Dateisystem und ihr eigenes Netzwerk, was Deployment, Sicherheit, Entwicklung usw. vereinfacht.
## Was ist ein Containerimage { #what-is-a-container-image }
@@ -598,7 +598,7 @@ Zum Beispiel:
* Mit einem **Kubernetes**-Cluster
* Mit einem Docker Swarm Mode-Cluster
* Mit einem anderen Tool wie Nomad
-* Mit einem Cloud-Dienst, der Ihr Containerimage nimmt und es bereitstellt
+* Mit einem Cloud-Dienst, der Ihr Containerimage nimmt und es deployt
## Docker-Image mit `uv` { #docker-image-with-uv }
diff --git a/docs/de/docs/deployment/fastapicloud.md b/docs/de/docs/deployment/fastapicloud.md
new file mode 100644
index 000000000..18c3bb8a4
--- /dev/null
+++ b/docs/de/docs/deployment/fastapicloud.md
@@ -0,0 +1,65 @@
+# FastAPI Cloud { #fastapi-cloud }
+
+Sie können Ihre FastAPI-App in der FastAPI Cloud mit **einem einzigen Befehl** deployen – tragen Sie sich in die Warteliste ein, falls noch nicht geschehen. 🚀
+
+## Anmelden { #login }
+
+Stellen Sie sicher, dass Sie bereits ein **FastAPI-Cloud-Konto** haben (wir haben Sie von der Warteliste eingeladen 😉).
+
+Melden Sie sich dann an:
+
+
+
## **Typer**, das FastAPI der CLIs { #typer-the-fastapi-of-clis }
@@ -123,7 +135,7 @@ Wenn Sie eine Starlette für die Webanteile.
+* Starlette für die Webanteile.
* Pydantic für die Datenanteile.
## Installation { #installation }
@@ -227,9 +239,9 @@ INFO: Application startup complete.
fastapi dev main.py macht ...fastapi dev main.py ...uvicorn – für den Server, der Ihre Anwendung lädt und bereitstellt. Dies umfasst `uvicorn[standard]`, das einige Abhängigkeiten (z. B. `uvloop`) beinhaltet, die für eine Bereitstellung mit hoher Performanz benötigt werden.
+* uvicorn – für den Server, der Ihre Anwendung lädt und bereitstellt. Dies umfasst `uvicorn[standard]`, das einige Abhängigkeiten (z. B. `uvloop`) beinhaltet, die für eine Bereitstellung mit hoher Performanz benötigt werden.
* `fastapi-cli[standard]` – um den `fastapi`-Befehl bereitzustellen.
* Dies beinhaltet `fastapi-cloud-cli`, das es Ihnen ermöglicht, Ihre FastAPI-Anwendung auf FastAPI Cloud bereitzustellen.
diff --git a/docs/de/docs/project-generation.md b/docs/de/docs/project-generation.md
index e6da4949c..62702d852 100644
--- a/docs/de/docs/project-generation.md
+++ b/docs/de/docs/project-generation.md
@@ -9,20 +9,20 @@ GitHub-Repository: Verkettet sie mit einem Leerzeichen in der Mitte.
+* Verkettet sie mit einem Leerzeichen in der Mitte.
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
### Es bearbeiten { #edit-it }
@@ -78,7 +78,7 @@ Das war's.
Das sind die „Typhinweise“:
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
Das ist nicht das gleiche wie das Deklarieren von Defaultwerten, wie es hier der Fall ist:
@@ -106,7 +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:
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
Da der Editor die Typen der Variablen kennt, erhalten Sie nicht nur Code-Vervollständigung, sondern auch eine Fehlerprüfung:
@@ -114,7 +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:
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
## Deklarieren von Typen { #declaring-types }
@@ -133,7 +133,7 @@ Zum Beispiel diese:
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
### Generische Typen mit Typ-Parametern { #generic-types-with-type-parameters }
@@ -161,56 +161,24 @@ 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.
-//// tab | Python 3.9+
-
Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
Als Typ nehmen Sie `list`.
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!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-Von `typing` importieren Sie `List` (mit Großbuchstaben `L`):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-Deklarieren Sie die Variable mit der gleichen Doppelpunkt-Syntax (`:`).
-
-Als Typ nehmen Sie das `List`, das Sie von `typing` importiert haben.
-
-Da die Liste ein Typ ist, welcher innere Typen enthält, werden diese von eckigen Klammern umfasst:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
/// info | Info
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).
+In diesem Fall ist `str` der Typ-Parameter, der an `list` übergeben wird.
///
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.
-
-///
-
Auf diese Weise kann Ihr Editor Sie auch bei der Bearbeitung von Einträgen aus der Liste unterstützen:
@@ -225,21 +193,7 @@ 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`:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
Das bedeutet:
@@ -254,21 +208,7 @@ Der erste Typ-Parameter ist für die Schlüssel des `dict`.
Der zweite Typ-Parameter ist für die Werte des `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_py39.py hl[1] *}
Das bedeutet:
@@ -282,7 +222,7 @@ Sie können deklarieren, dass eine Variable einer von **verschiedenen Typen** se
In Python 3.6 und höher (inklusive Python 3.10) können Sie den `Union`-Typ von `typing` verwenden und die möglichen Typen innerhalb der eckigen Klammern auflisten.
-In Python 3.10 gibt es zusätzlich eine **neue Syntax**, die es erlaubt, die möglichen Typen getrennt von einem vertikalen Balken (`|`) aufzulisten.
+In Python 3.10 gibt es zusätzlich eine **neue Syntax**, die es erlaubt, die möglichen Typen getrennt von einem vertikalen Balken (`|`) aufzulisten.
//// tab | Python 3.10+
@@ -292,10 +232,10 @@ In Python 3.10 gibt es zusätzlich eine **neue Syntax**, die es erlaubt, die mö
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
```
////
@@ -309,7 +249,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_py39.py!}
```
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.
@@ -326,18 +266,18 @@ Das bedeutet auch, dass Sie in Python 3.10 `Something | None` verwenden können:
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
////
-//// tab | Python 3.8+ Alternative
+//// tab | Python 3.9+ Alternative
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
```
////
@@ -353,11 +293,11 @@ Beide sind äquivalent und im Hintergrund dasselbe, aber ich empfehle `Union` st
Ich denke, `Union[SomeType, None]` ist expliziter bezüglich seiner Bedeutung.
-Es geht nur um Wörter und Namen. Aber diese Worte können beeinflussen, wie Sie und Ihre Teamkollegen über den Code denken.
+Es geht nur um Worte und Namen. Aber diese Worte können beeinflussen, wie Sie und Ihre Teamkollegen über den Code denken.
Nehmen wir zum Beispiel diese Funktion:
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+{* ../../docs_src/python_types/tutorial009c_py39.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:
@@ -390,13 +330,13 @@ Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern u
* `set`
* `dict`
-Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
+Und ebenso wie bei früheren Python-Versionen, aus dem `typing`-Modul:
* `Union`
-* `Optional` (so wie unter Python 3.8)
+* `Optional`
* ... 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.
////
@@ -409,7 +349,7 @@ Sie können die eingebauten Typen als Generics verwenden (mit eckigen Klammern u
* `set`
* `dict`
-Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
+Und Generics aus dem `typing`-Modul:
* `Union`
* `Optional`
@@ -417,29 +357,17 @@ Verwenden Sie für den Rest, wie unter Python 3.8, das `typing`-Modul:
////
-//// tab | Python 3.8+
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ... und andere.
-
-////
-
### Klassen als Typen { #classes-as-types }
Sie können auch eine Klasse als Typ einer Variablen deklarieren.
Nehmen wir an, Sie haben eine Klasse `Person`, mit einem Namen:
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
Dann können Sie eine Variable vom Typ `Person` deklarieren:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
Und wiederum bekommen Sie die volle Editor-Unterstützung:
@@ -463,29 +391,7 @@ Und Sie erhalten volle Editor-Unterstützung für dieses Objekt.
Ein Beispiel aus der offiziellen Pydantic Dokumentation:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial011_py310.py *}
/// info | Info
@@ -507,27 +413,9 @@ Pydantic verhält sich speziell, wenn Sie `Optional` oder `Union[Something, None
Python bietet auch die Möglichkeit, **zusätzliche Metadaten** in Typhinweisen unterzubringen, mittels `Annotated`.
-//// tab | Python 3.9+
-
-In Python 3.9 ist `Annotated` ein Teil der Standardbibliothek, Sie können es von `typing` importieren.
+Seit 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!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-In Versionen niedriger als Python 3.9 importieren Sie `Annotated` von `typing_extensions`.
-
-Es wird bereits mit **FastAPI** installiert sein.
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013.py!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
Python selbst macht nichts mit `Annotated`. Für Editoren und andere Tools ist der Typ immer noch `str`.
diff --git a/docs/de/docs/resources/index.md b/docs/de/docs/resources/index.md
index 2c5046c73..52b32b148 100644
--- a/docs/de/docs/resources/index.md
+++ b/docs/de/docs/resources/index.md
@@ -1,3 +1,3 @@
# Ressourcen { #resources }
-Zusätzliche Ressourcen, externe Links, Artikel und mehr. ✈️
+Zusätzliche Ressourcen, externe Links und mehr. ✈️
diff --git a/docs/de/docs/tutorial/background-tasks.md b/docs/de/docs/tutorial/background-tasks.md
index ea85207ce..1d34430dc 100644
--- a/docs/de/docs/tutorial/background-tasks.md
+++ b/docs/de/docs/tutorial/background-tasks.md
@@ -15,7 +15,7 @@ Hierzu zählen beispielsweise:
Importieren Sie zunächst `BackgroundTasks` und definieren Sie einen Parameter in Ihrer *Pfadoperation-Funktion* mit der Typdeklaration `BackgroundTasks`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
**FastAPI** erstellt für Sie das Objekt vom Typ `BackgroundTasks` und übergibt es als diesen Parameter.
@@ -31,13 +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`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
## Den Hintergrundtask hinzufügen { #add-the-background-task }
Übergeben Sie innerhalb Ihrer *Pfadoperation-Funktion* Ihre Taskfunktion mit der Methode `.add_task()` an das *Hintergrundtasks*-Objekt:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
`.add_task()` erhält als Argumente:
@@ -63,7 +63,7 @@ Und dann schreibt ein weiterer Hintergrundtask, der in der *Pfadoperation-Funkti
## Technische Details { #technical-details }
-Die Klasse `BackgroundTasks` stammt direkt von `starlette.background`.
+Die Klasse `BackgroundTasks` stammt direkt von `starlette.background`.
Sie wird direkt in FastAPI importiert/inkludiert, sodass Sie sie von `fastapi` importieren können und vermeiden, versehentlich das alternative `BackgroundTask` (ohne das `s` am Ende) von `starlette.background` zu importieren.
@@ -71,7 +71,7 @@ Indem Sie nur `BackgroundTasks` (und nicht `BackgroundTask`) verwenden, ist es d
Es ist immer noch möglich, `BackgroundTask` allein in FastAPI zu verwenden, aber Sie müssen das Objekt in Ihrem Code erstellen und eine Starlette-`Response` zurückgeben, die es enthält.
-Weitere Details finden Sie in Starlettes offizieller Dokumentation für Hintergrundtasks.
+Weitere Details finden Sie in Starlettes offizieller Dokumentation für Hintergrundtasks.
## Vorbehalt { #caveat }
diff --git a/docs/de/docs/tutorial/bigger-applications.md b/docs/de/docs/tutorial/bigger-applications.md
index 928d50adf..d478d77c2 100644
--- a/docs/de/docs/tutorial/bigger-applications.md
+++ b/docs/de/docs/tutorial/bigger-applications.md
@@ -56,19 +56,19 @@ from app.routers import items
Die gleiche Dateistruktur mit Kommentaren:
-```
+```bash
.
-├── app # „app“ ist ein Python-Package
-│ ├── __init__.py # diese Datei macht „app“ zu einem „Python-Package“
-│ ├── main.py # „main“-Modul, z. B. import app.main
-│ ├── dependencies.py # „dependencies“-Modul, z. B. import app.dependencies
-│ └── routers # „routers“ ist ein „Python-Subpackage“
-│ │ ├── __init__.py # macht „routers“ zu einem „Python-Subpackage“
-│ │ ├── items.py # „items“-Submodul, z. B. import app.routers.items
-│ │ └── users.py # „users“-Submodul, z. B. import app.routers.users
-│ └── internal # „internal“ ist ein „Python-Subpackage“
-│ ├── __init__.py # macht „internal“ zu einem „Python-Subpackage“
-│ └── admin.py # „admin“-Submodul, z. B. import app.internal.admin
+├── app # "app" ist ein Python-Package
+│ ├── __init__.py # diese Datei macht "app" zu einem "Python-Package"
+│ ├── main.py # "main"-Modul, z. B. import app.main
+│ ├── dependencies.py # "dependencies"-Modul, z. B. import app.dependencies
+│ └── routers # "routers" ist ein "Python-Subpackage"
+│ │ ├── __init__.py # macht "routers" zu einem "Python-Subpackage"
+│ │ ├── items.py # "items"-Submodul, z. B. import app.routers.items
+│ │ └── users.py # "users"-Submodul, z. B. import app.routers.users
+│ └── internal # "internal" ist ein "Python-Subpackage"
+│ ├── __init__.py # macht "internal" zu einem "Python-Subpackage"
+│ └── admin.py # "admin"-Submodul, z. B. import app.internal.admin
```
## `APIRouter` { #apirouter }
@@ -85,9 +85,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_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
### *Pfadoperationen* mit `APIRouter` { #path-operations-with-apirouter }
@@ -95,9 +93,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_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
Sie können sich `APIRouter` als eine „Mini-`FastAPI`“-Klasse vorstellen.
@@ -121,35 +117,7 @@ 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:
-//// 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+ nicht annotiert
-
-/// 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!}
-```
-
-////
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
/// tip | Tipp
@@ -181,9 +149,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_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
Da der Pfad jeder *Pfadoperation* mit `/` beginnen muss, wie in:
@@ -242,9 +208,7 @@ 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_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
#### Wie relative Importe funktionieren { #how-relative-imports-work }
@@ -315,9 +279,7 @@ 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_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
/// tip | Tipp
@@ -343,17 +305,13 @@ 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_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
### Den `APIRouter` importieren { #import-the-apirouter }
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_an_py39/main.py hl[4:5] title["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.
@@ -416,17 +374,13 @@ 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_an_py39/main.py hl[5] title["app/main.py"] *}
### Die `APIRouter` für `users` und `items` inkludieren { #include-the-apirouters-for-users-and-items }
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_an_py39/main.py hl[10:11] title["app/main.py"] *}
/// info | Info
@@ -466,17 +420,13 @@ 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_an_py39/internal/admin.py hl[3] title["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.
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_an_py39/main.py hl[14:17] title["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.
@@ -497,9 +447,7 @@ 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_an_py39/main.py hl[21:23] title["app/main.py"] *}
und es wird korrekt funktionieren, zusammen mit allen anderen *Pfadoperationen*, die mit `app.include_router()` hinzugefügt wurden.
@@ -531,7 +479,7 @@ $ fastapi dev app/main.py
-und öffnen Sie die Dokumentation unter http://127.0.0.1:8000/docs.
+Und öffnen Sie die Dokumentation unter http://127.0.0.1:8000/docs.
Sie sehen die automatische API-Dokumentation, einschließlich der Pfade aller Submodule, mit den richtigen Pfaden (und Präfixen) und den richtigen Tags:
diff --git a/docs/de/docs/tutorial/body-nested-models.md b/docs/de/docs/tutorial/body-nested-models.md
index 324d31928..65a5d7c1d 100644
--- a/docs/de/docs/tutorial/body-nested-models.md
+++ b/docs/de/docs/tutorial/body-nested-models.md
@@ -14,35 +14,14 @@ Das bewirkt, dass `tags` eine Liste ist, wenngleich es nichts über den Typ der
Aber Python erlaubt es, Listen mit inneren Typen, auch „Typ-Parameter“ genannt, zu deklarieren.
-### `List` von `typing` importieren { #import-typings-list }
-
-In Python 3.9 oder darüber können Sie einfach `list` verwenden, um diese Typannotationen zu deklarieren, wie wir unten sehen werden. 💡
-
-In Python-Versionen vor 3.9 (3.6 und darüber), müssen Sie zuerst `List` von Pythons Standardmodul `typing` importieren.
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
### Eine `list` mit einem Typ-Parameter deklarieren { #declare-a-list-with-a-type-parameter }
-Um Typen wie `list`, `dict`, `tuple` mit inneren Typ-Parametern (inneren Typen) zu deklarieren:
-
-* Wenn Sie eine Python-Version kleiner als 3.9 verwenden, importieren Sie das Äquivalent zum entsprechenden Typ vom `typing`-Modul
-* Überreichen Sie den/die inneren Typ(en) von eckigen Klammern umschlossen, `[` und `]`, als „Typ-Parameter“
-
-In Python 3.9 wäre das:
+Um Typen zu deklarieren, die Typ-Parameter (innere Typen) haben, wie `list`, `dict`, `tuple`, übergeben Sie den/die inneren Typ(en) als „Typ-Parameter“ in eckigen Klammern: `[` und `]`
```Python
my_list: list[str]
```
-Und in Python-Versionen vor 3.9:
-
-```Python
-from typing import List
-
-my_list: List[str]
-```
-
Das ist alles Standard-Python-Syntax für Typdeklarationen.
Verwenden Sie dieselbe Standardsyntax für Modellattribute mit inneren Typen.
@@ -178,12 +157,6 @@ Beachten Sie, wie `Offer` eine Liste von `Item`s hat, die ihrerseits eine option
Wenn das äußerste Element des JSON-Bodys, das Sie erwarten, ein JSON-`array` (eine Python-`list`) ist, können Sie den Typ im Funktionsparameter deklarieren, mit der gleichen Syntax wie in Pydantic-Modellen:
-```Python
-images: List[Image]
-```
-
-oder in Python 3.9 und darüber:
-
```Python
images: list[Image]
```
diff --git a/docs/de/docs/tutorial/body-updates.md b/docs/de/docs/tutorial/body-updates.md
index aa62199fe..d260998e9 100644
--- a/docs/de/docs/tutorial/body-updates.md
+++ b/docs/de/docs/tutorial/body-updates.md
@@ -50,14 +50,6 @@ Wenn Sie Teil-Aktualisierungen entgegennehmen, ist der `exclude_unset`-Parameter
Wie in `item.model_dump(exclude_unset=True)`.
-/// info | Info
-
-In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecatet (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.
-
-///
-
Das wird ein `dict` erstellen, mit nur den Daten, die gesetzt wurden, als das `item`-Modell erstellt wurde, Defaultwerte ausgeschlossen.
Sie können das verwenden, um ein `dict` zu erstellen, das nur die (im Request) gesendeten Daten enthält, ohne Defaultwerte:
@@ -68,14 +60,6 @@ Sie können das verwenden, um ein `dict` zu erstellen, das nur die (im deprecatet (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)`:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
diff --git a/docs/de/docs/tutorial/body.md b/docs/de/docs/tutorial/body.md
index 1e6382b6f..cdf3122f2 100644
--- a/docs/de/docs/tutorial/body.md
+++ b/docs/de/docs/tutorial/body.md
@@ -127,14 +127,6 @@ Innerhalb der Funktion können Sie alle Attribute des Modellobjekts direkt verwe
{* ../../docs_src/body/tutorial002_py310.py *}
-/// info | Info
-
-In Pydantic v1 hieß die Methode `.dict()`, sie wurde in Pydantic v2 deprecatet (aber weiterhin unterstützt) und in `.model_dump()` umbenannt.
-
-Die Beispiele hier verwenden `.dict()` zur Kompatibilität mit Pydantic v1, aber Sie sollten stattdessen `.model_dump()` verwenden, wenn Sie Pydantic v2 nutzen können.
-
-///
-
## Requestbody- + Pfad-Parameter { #request-body-path-parameters }
Sie können Pfad-Parameter und den Requestbody gleichzeitig deklarieren.
@@ -162,7 +154,7 @@ Die Funktionsparameter werden wie folgt erkannt:
FastAPI weiß, dass der Wert von `q` nicht erforderlich ist, aufgrund des definierten Defaultwertes `= None`.
-Das `str | None` (Python 3.10+) oder `Union` in `Union[str, None]` (Python 3.8+) wird von FastAPI nicht verwendet, um zu bestimmen, dass der Wert nicht erforderlich ist. FastAPI weiß, dass er nicht erforderlich ist, weil er einen Defaultwert von `= None` hat.
+Das `str | None` (Python 3.10+) oder `Union` in `Union[str, None]` (Python 3.9+) wird von FastAPI nicht verwendet, um zu bestimmen, dass der Wert nicht erforderlich ist. FastAPI weiß, dass er nicht erforderlich ist, weil er einen Defaultwert von `= None` hat.
Das Hinzufügen der Typannotationen ermöglicht jedoch Ihrem Editor, Ihnen eine bessere Unterstützung zu bieten und Fehler zu erkennen.
diff --git a/docs/de/docs/tutorial/cookie-param-models.md b/docs/de/docs/tutorial/cookie-param-models.md
index 2baf3d70d..25718bd33 100644
--- a/docs/de/docs/tutorial/cookie-param-models.md
+++ b/docs/de/docs/tutorial/cookie-param-models.md
@@ -50,7 +50,7 @@ Ihre API hat jetzt die Macht, ihre eigene Response**.
diff --git a/docs/de/docs/tutorial/cors.md b/docs/de/docs/tutorial/cors.md
index 191a7b4ef..81f0f3605 100644
--- a/docs/de/docs/tutorial/cors.md
+++ b/docs/de/docs/tutorial/cors.md
@@ -46,7 +46,7 @@ Sie können auch angeben, ob Ihr Backend erlaubt:
* Bestimmte HTTP-Methoden (`POST`, `PUT`) oder alle mit der Wildcard `"*"`.
* Bestimmte HTTP-Header oder alle mit der Wildcard `"*"`.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
Die von der `CORSMiddleware`-Implementierung verwendeten Defaultparameter sind standardmäßig restriktiv, daher müssen Sie bestimmte Origins, Methoden oder Header ausdrücklich aktivieren, damit Browser sie in einem Cross-Domain-Kontext verwenden dürfen.
diff --git a/docs/de/docs/tutorial/debugging.md b/docs/de/docs/tutorial/debugging.md
index 0a31f8653..0d12877c1 100644
--- a/docs/de/docs/tutorial/debugging.md
+++ b/docs/de/docs/tutorial/debugging.md
@@ -6,7 +6,7 @@ Sie können den Debugger in Ihrem Editor verbinden, zum Beispiel mit Visual Stud
Importieren und führen Sie `uvicorn` direkt in Ihrer FastAPI-Anwendung aus:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
### Über `__name__ == "__main__"` { #about-name-main }
diff --git a/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md
index 3d4493f35..7df0842eb 100644
--- a/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/de/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -101,7 +101,7 @@ Jetzt können Sie Ihre Abhängigkeit mithilfe dieser Klasse deklarieren.
Beachten Sie, wie wir `CommonQueryParams` im obigen Code zweimal schreiben:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -109,7 +109,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
@@ -137,7 +137,7 @@ Aus diesem extrahiert FastAPI die deklarierten Parameter, und dieses ist es, was
In diesem Fall hat das erste `CommonQueryParams` in:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, ...
@@ -145,7 +145,7 @@ commons: Annotated[CommonQueryParams, ...
////
-//// tab | Python 3.8+ nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
@@ -163,7 +163,7 @@ commons: CommonQueryParams ...
Sie könnten tatsächlich einfach schreiben:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[Any, Depends(CommonQueryParams)]
@@ -171,7 +171,7 @@ commons: Annotated[Any, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
@@ -197,7 +197,7 @@ Es wird jedoch empfohlen, den Typ zu deklarieren, da Ihr Editor so weiß, was al
Aber Sie sehen, dass wir hier etwas Codeduplizierung haben, indem wir `CommonQueryParams` zweimal schreiben:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -205,7 +205,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
@@ -225,7 +225,7 @@ In diesem speziellen Fall können Sie Folgendes tun:
Anstatt zu schreiben:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -233,7 +233,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
@@ -249,7 +249,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
... schreiben Sie:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends()]
@@ -257,7 +257,7 @@ commons: Annotated[CommonQueryParams, Depends()]
////
-//// tab | Python 3.8 nicht annotiert
+//// tab | Python 3.9+ nicht annotiert
/// tip | Tipp
diff --git a/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md
index 178c2673e..0083e7e7e 100644
--- a/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/de/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,6 +1,6 @@
# Abhängigkeiten mit `yield` { #dependencies-with-yield }
-FastAPI unterstützt Abhängigkeiten, die nach Abschluss einige zusätzliche Schritte ausführen.
+FastAPI unterstützt Abhängigkeiten, die nach Abschluss einige zusätzliche Schritte ausführen.
Verwenden Sie dazu `yield` statt `return` und schreiben Sie die zusätzlichen Schritte / den zusätzlichen Code danach.
@@ -29,15 +29,15 @@ Sie könnten damit beispielsweise eine Datenbanksession erstellen und diese nach
Nur der Code vor und einschließlich der `yield`-Anweisung wird ausgeführt, bevor eine Response erzeugt wird:
-{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[2:4] *}
Der ge`yield`ete Wert ist das, was in *Pfadoperationen* und andere Abhängigkeiten eingefügt wird:
-{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[4] *}
-Der auf die `yield`-Anweisung folgende Code wird ausgeführt, nachdem die Response erstellt wurde, aber bevor sie gesendet wird:
+Der auf die `yield`-Anweisung folgende Code wird nach der Response ausgeführt:
-{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[5:6] *}
/// tip | Tipp
@@ -51,13 +51,13 @@ Sie können `async`- oder reguläre Funktionen verwenden.
Wenn Sie einen `try`-Block in einer Abhängigkeit mit `yield` verwenden, empfangen Sie alle Exceptions, die bei Verwendung der Abhängigkeit geworfen wurden.
-Wenn beispielsweise ein Code irgendwann in der Mitte, in einer anderen Abhängigkeit oder in einer *Pfadoperation*, ein „Rollback“ einer Datenbanktransaktion oder einen anderen Fehler verursacht, empfangen Sie die resultierende Exception in Ihrer Abhängigkeit.
+Wenn beispielsweise ein Code irgendwann in der Mitte, in einer anderen Abhängigkeit oder in einer *Pfadoperation*, ein „Rollback“ einer Datenbanktransaktion macht oder eine andere Exception verursacht, empfangen Sie die Exception in Ihrer Abhängigkeit.
Sie können also mit `except SomeException` diese bestimmte Exception innerhalb der Abhängigkeit handhaben.
Auf die gleiche Weise können Sie `finally` verwenden, um sicherzustellen, dass die Exit-Schritte ausgeführt werden, unabhängig davon, ob eine Exception geworfen wurde oder nicht.
-{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[3,5] *}
## Unterabhängigkeiten mit `yield` { #sub-dependencies-with-yield }
@@ -95,9 +95,11 @@ Dieses funktioniert dank Pythons > dep_req: Startet den Request
+ Note over dep_req: Führt den Code bis zum yield aus
+ dep_req ->> dep_func: Reicht Abhängigkeit weiter
+ Note over dep_func: Führt den Code bis zum yield aus
+ dep_func ->> operation: Führt Pfadoperation mit Abhängigkeit aus
+ operation ->> dep_func: Kehrt aus Pfadoperation zurück
+ Note over dep_func: Führt Code nach yield aus
+ Note over dep_func: ✅ Abhängigkeit geschlossen
+ dep_func ->> client: Sendet Response an Client
+ Note over client: Response gesendet
+ Note over dep_req: Führt Code nach yield aus
+ Note over dep_req: ✅ Abhängigkeit geschlossen
+```
-Wenn Sie sich früher auf dieses Verhalten verlassen haben, sollten Sie jetzt die Ressourcen für Hintergrundtasks innerhalb des Hintergrundtasks selbst erstellen und intern nur Daten verwenden, die nicht von den Ressourcen von Abhängigkeiten mit `yield` abhängen.
+## Abhängigkeiten mit `yield`, `HTTPException`, `except` und Hintergrundtasks { #dependencies-with-yield-httpexception-except-and-background-tasks }
-Anstatt beispielsweise dieselbe Datenbanksitzung zu verwenden, würden Sie eine neue Datenbanksitzung innerhalb des Hintergrundtasks erstellen und die Objekte mithilfe dieser neuen Sitzung aus der Datenbank abrufen. Und anstatt das Objekt aus der Datenbank als Parameter an die Hintergrundtask-Funktion zu übergeben, würden Sie die ID dieses Objekts übergeben und das Objekt dann innerhalb der Hintergrundtask-Funktion erneut laden.
+Abhängigkeiten mit `yield` haben sich im Laufe der Zeit weiterentwickelt, um verschiedene Anwendungsfälle abzudecken und einige Probleme zu beheben.
+Wenn Sie sehen möchten, was sich in verschiedenen Versionen von FastAPI geändert hat, lesen Sie mehr dazu im fortgeschrittenen Teil, unter [Fortgeschrittene Abhängigkeiten – Abhängigkeiten mit `yield`, `HTTPException`, `except` und Hintergrundtasks](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks){.internal-link target=_blank}.
## Kontextmanager { #context-managers }
### Was sind „Kontextmanager“ { #what-are-context-managers }
@@ -254,7 +268,7 @@ In Python können Sie Kontextmanager erstellen, indem Sie deprecatet (aber weiterhin unterstützt) und in `.model_dump()` umbenannt.
-
-Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, aber Sie sollten `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können.
-
-///
-
-### Über `**user_in.dict()` { #about-user-in-dict }
-
-#### Die `.dict()`-Methode von Pydantic { #pydantics-dict }
+#### Pydantics `.model_dump()` { #pydantics-model-dump }
`user_in` ist ein Pydantic-Modell der Klasse `UserIn`.
-Pydantic-Modelle haben eine `.dict()`-Methode, die ein `dict` mit den Daten des Modells zurückgibt.
+Pydantic-Modelle haben eine `.model_dump()`-Methode, die ein `dict` mit den Daten des Modells zurückgibt.
Wenn wir also ein Pydantic-Objekt `user_in` erstellen, etwa so:
@@ -47,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com
und dann aufrufen:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
```
haben wir jetzt ein `dict` mit den Daten in der Variablen `user_dict` (es ist ein `dict` statt eines Pydantic-Modellobjekts).
@@ -103,20 +95,20 @@ UserInDB(
#### Ein Pydantic-Modell aus dem Inhalt eines anderen { #a-pydantic-model-from-the-contents-of-another }
-Da wir im obigen Beispiel `user_dict` von `user_in.dict()` bekommen haben, wäre dieser Code:
+Da wir im obigen Beispiel `user_dict` von `user_in.model_dump()` bekommen haben, wäre dieser Code:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
UserInDB(**user_dict)
```
gleichwertig zu:
```Python
-UserInDB(**user_in.dict())
+UserInDB(**user_in.model_dump())
```
-... weil `user_in.dict()` ein `dict` ist, und dann lassen wir Python es „entpacken“, indem wir es an `UserInDB` mit vorangestelltem `**` übergeben.
+... weil `user_in.model_dump()` ein `dict` ist, und dann lassen wir Python es „entpacken“, indem wir es an `UserInDB` mit vorangestelltem `**` übergeben.
Auf diese Weise erhalten wir ein Pydantic-Modell aus den Daten eines anderen Pydantic-Modells.
@@ -125,7 +117,7 @@ Auf diese Weise erhalten wir ein Pydantic-Modell aus den Daten eines anderen Pyd
Und dann fügen wir das zusätzliche Schlüsselwort-Argument `hashed_password=hashed_password` hinzu, wie in:
```Python
-UserInDB(**user_in.dict(), hashed_password=hashed_password)
+UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
```
... was so ist wie:
@@ -180,7 +172,6 @@ Wenn Sie eine FastAPI Cloud deployen, treten Sie der Warteliste bei, falls Sie es noch nicht getan haben. 🚀
+
+Wenn Sie bereits ein **FastAPI Cloud**-Konto haben (wir haben Sie von der Warteliste eingeladen 😉), können Sie Ihre Anwendung mit einem Befehl deployen.
+
+Vor dem Deployen, stellen Sie sicher, dass Sie eingeloggt sind:
+
+kwargs. Selbst wenn diese keinen Defaultwert haben.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
### Besser mit `Annotated` { #better-with-annotated }
diff --git a/docs/de/docs/tutorial/path-params.md b/docs/de/docs/tutorial/path-params.md
index 1db288fb8..1de497315 100644
--- a/docs/de/docs/tutorial/path-params.md
+++ b/docs/de/docs/tutorial/path-params.md
@@ -2,7 +2,7 @@
Sie können Pfad-„Parameter“ oder -„Variablen“ mit der gleichen Syntax deklarieren, welche in Python-Formatstrings verwendet wird:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
Der Wert des Pfad-Parameters `item_id` wird Ihrer Funktion als das Argument `item_id` übergeben.
@@ -16,7 +16,7 @@ Wenn Sie dieses Beispiel ausführen und auf Enumerationen (oder Enums) gibt es in Python seit Version 3.4.
-
-///
/// tip | Tipp
@@ -158,7 +153,7 @@ Falls Sie sich fragen, was „AlexNet“, „ResNet“ und „LeNet“ ist, das
Dann erstellen Sie einen *Pfad-Parameter*, der als Typ die gerade erstellte Enum-Klasse hat (`ModelName`):
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
### Die API-Dokumentation testen { #check-the-docs }
@@ -174,13 +169,13 @@ Der *Pfad-Parameter* wird ein *Query ist die Menge von Schlüssel-Wert-Paaren, die nach dem `?` in einer URL folgen und durch `&`-Zeichen getrennt sind.
@@ -127,7 +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:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
Hier ist `needy` ein erforderlicher Query-Parameter vom Typ `str`.
diff --git a/docs/de/docs/tutorial/response-model.md b/docs/de/docs/tutorial/response-model.md
index 7b77125cb..f759bb257 100644
--- a/docs/de/docs/tutorial/response-model.md
+++ b/docs/de/docs/tutorial/response-model.md
@@ -183,7 +183,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}.
-{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.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.
@@ -193,7 +193,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.
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.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.
@@ -252,20 +252,6 @@ Wenn Sie also den Artikel mit der ID `foo` bei der *Pfadoperation* anfragen, wir
/// info | Info
-In Pydantic v1 hieß diese Methode `.dict()`, in Pydantic v2 wurde sie deprecatet (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.
-
-///
-
-/// info | Info
-
-FastAPI verwendet `.dict()` von Pydantic Modellen, mit dessen `exclude_unset`-Parameter, um das zu erreichen.
-
-///
-
-/// info | Info
-
Sie können auch:
* `response_model_exclude_defaults=True`
diff --git a/docs/de/docs/tutorial/response-status-code.md b/docs/de/docs/tutorial/response-status-code.md
index 928003c3f..fd17c9933 100644
--- a/docs/de/docs/tutorial/response-status-code.md
+++ b/docs/de/docs/tutorial/response-status-code.md
@@ -8,7 +8,7 @@ Genauso wie Sie ein Responsemodell angeben können, können Sie auch den HTTP-St
* `@app.delete()`
* usw.
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
/// note | Hinweis
@@ -74,7 +74,7 @@ Um mehr über die einzelnen Statuscodes zu erfahren und welcher wofür verwendet
Lassen Sie uns das vorherige Beispiel noch einmal anschauen:
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
`201` ist der Statuscode für „Created“ („Erzeugt“).
@@ -82,7 +82,7 @@ Aber Sie müssen sich nicht merken, was jeder dieser Codes bedeutet.
Sie können die Annehmlichkeit von Variablen aus `fastapi.status` nutzen.
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *}
Diese sind nur eine Annehmlichkeit, sie enthalten dieselbe Zahl, aber so können Sie die Autovervollständigung Ihres Editors verwenden, um sie zu finden:
diff --git a/docs/de/docs/tutorial/schema-extra-example.md b/docs/de/docs/tutorial/schema-extra-example.md
index e2ffed292..07fe8c5d9 100644
--- a/docs/de/docs/tutorial/schema-extra-example.md
+++ b/docs/de/docs/tutorial/schema-extra-example.md
@@ -8,36 +8,14 @@ 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.
-//// 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] *}
-
-////
-
Diese zusätzlichen Informationen werden unverändert zum für dieses Modell ausgegebenen **JSON-Schema** hinzugefügt und in der API-Dokumentation verwendet.
-//// 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.
+Sie können 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`.
-////
-
-//// tab | Pydantic v1
-
-In Pydantic Version 1 würden Sie eine interne Klasse `Config` und `schema_extra` verwenden, wie beschrieben in Pydantic-Dokumentation: Schema customization.
-
-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`.
-
-////
-
/// tip | Tipp
Mit derselben Technik können Sie das JSON-Schema erweitern und Ihre eigenen benutzerdefinierten Zusatzinformationen hinzufügen.
diff --git a/docs/de/docs/tutorial/security/oauth2-jwt.md b/docs/de/docs/tutorial/security/oauth2-jwt.md
index 4b81c8069..0d5ce587b 100644
--- a/docs/de/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/de/docs/tutorial/security/oauth2-jwt.md
@@ -64,20 +64,20 @@ 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).
-## `passlib` installieren { #install-passlib }
+## `pwdlib` installieren { #install-pwdlib }
-PassLib ist ein großartiges Python-Package, um Passwort-Hashes zu handhaben.
+pwdlib ist ein großartiges Python-Package, um Passwort-Hashes zu handhaben.
Es unterstützt viele sichere Hashing-Algorithmen und Werkzeuge, um mit diesen zu arbeiten.
-Der empfohlene Algorithmus ist „Bcrypt“.
+Der empfohlene Algorithmus ist „Argon2“.
-Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../../virtual-environments.md){.internal-link target=_blank} erstellen, sie aktivieren, und installieren Sie dann PassLib mit Bcrypt:
+Stellen Sie sicher, dass Sie eine [virtuelle Umgebung](../../virtual-environments.md){.internal-link target=_blank} erstellen, sie aktivieren, und installieren Sie dann pwdlib mit Argon2:
-
-## 🌀 🔢 📨 & 🛃 🕐
-
-👆 💪 💚 ✔️ 🔁 📨 👈 ✔ 📚 *➡ 🛠️*, ✋️ 👆 💚 🌀 👫 ⏮️ 🛃 📨 💚 🔠 *➡ 🛠️*.
-
-📚 💼, 👆 💪 ⚙️ 🐍 ⚒ "🏗" `dict` ⏮️ `**dict_to_unpack`:
-
-```Python
-old_dict = {
- "old key": "old value",
- "second old key": "second old value",
-}
-new_dict = {**old_dict, "new key": "new value"}
-```
-
-📥, `new_dict` 🔜 🔌 🌐 🔑-💲 👫 ⚪️➡️ `old_dict` ➕ 🆕 🔑-💲 👫:
-
-```Python
-{
- "old key": "old value",
- "second old key": "second old value",
- "new key": "new value",
-}
-```
-
-👆 💪 ⚙️ 👈 ⚒ 🏤-⚙️ 🔢 📨 👆 *➡ 🛠️* & 🌀 👫 ⏮️ 🌖 🛃 🕐.
-
-🖼:
-
-{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
-
-## 🌖 ℹ 🔃 🗄 📨
-
-👀 ⚫️❔ ⚫️❔ 👆 💪 🔌 📨, 👆 💪 ✅ 👉 📄 🗄 🔧:
-
-* 🗄 📨 🎚, ⚫️ 🔌 `Response Object`.
-* 🗄 📨 🎚, 👆 💪 🔌 🕳 ⚪️➡️ 👉 🔗 🔠 📨 🔘 👆 `responses` 🔢. ✅ `description`, `headers`, `content` (🔘 👉 👈 👆 📣 🎏 🔉 🆎 & 🎻 🔗), & `links`.
diff --git a/docs/em/docs/advanced/additional-status-codes.md b/docs/em/docs/advanced/additional-status-codes.md
deleted file mode 100644
index 907c7e68e..000000000
--- a/docs/em/docs/advanced/additional-status-codes.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# 🌖 👔 📟
-
-🔢, **FastAPI** 🔜 📨 📨 ⚙️ `JSONResponse`, 🚮 🎚 👆 📨 ⚪️➡️ 👆 *➡ 🛠️* 🔘 👈 `JSONResponse`.
-
-⚫️ 🔜 ⚙️ 🔢 👔 📟 ⚖️ 1️⃣ 👆 ⚒ 👆 *➡ 🛠️*.
-
-## 🌖 👔 📟
-
-🚥 👆 💚 📨 🌖 👔 📟 ↖️ ⚪️➡️ 👑 1️⃣, 👆 💪 👈 🛬 `Response` 🔗, 💖 `JSONResponse`, & ⚒ 🌖 👔 📟 🔗.
-
-🖼, ➡️ 💬 👈 👆 💚 ✔️ *➡ 🛠️* 👈 ✔ ℹ 🏬, & 📨 🇺🇸🔍 👔 📟 2️⃣0️⃣0️⃣ "👌" 🕐❔ 🏆.
-
-✋️ 👆 💚 ⚫️ 🚫 🆕 🏬. & 🕐❔ 🏬 🚫 🔀 ⏭, ⚫️ ✍ 👫, & 📨 🇺🇸🔍 👔 📟 2️⃣0️⃣1️⃣ "✍".
-
-🏆 👈, 🗄 `JSONResponse`, & 📨 👆 🎚 📤 🔗, ⚒ `status_code` 👈 👆 💚:
-
-{* ../../docs_src/additional_status_codes/tutorial001.py hl[4,25] *}
-
-/// warning
-
-🕐❔ 👆 📨 `Response` 🔗, 💖 🖼 🔛, ⚫️ 🔜 📨 🔗.
-
-⚫️ 🏆 🚫 🎻 ⏮️ 🏷, ♒️.
-
-⚒ 💭 ⚫️ ✔️ 📊 👆 💚 ⚫️ ✔️, & 👈 💲 ☑ 🎻 (🚥 👆 ⚙️ `JSONResponse`).
-
-///
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.responses import JSONResponse`.
-
-**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃. 🎏 ⏮️ `status`.
-
-///
-
-## 🗄 & 🛠️ 🩺
-
-🚥 👆 📨 🌖 👔 📟 & 📨 🔗, 👫 🏆 🚫 🔌 🗄 🔗 (🛠️ 🩺), ↩️ FastAPI 🚫 ✔️ 🌌 💭 ⏪ ⚫️❔ 👆 🚶 📨.
-
-✋️ 👆 💪 📄 👈 👆 📟, ⚙️: [🌖 📨](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/em/docs/advanced/advanced-dependencies.md b/docs/em/docs/advanced/advanced-dependencies.md
deleted file mode 100644
index 3404c2687..000000000
--- a/docs/em/docs/advanced/advanced-dependencies.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# 🏧 🔗
-
-## 🔗 🔗
-
-🌐 🔗 👥 ✔️ 👀 🔧 🔢 ⚖️ 🎓.
-
-✋️ 📤 💪 💼 🌐❔ 👆 💚 💪 ⚒ 🔢 🔛 🔗, 🍵 ✔️ 📣 📚 🎏 🔢 ⚖️ 🎓.
-
-➡️ 🌈 👈 👥 💚 ✔️ 🔗 👈 ✅ 🚥 🔢 🔢 `q` 🔌 🔧 🎚.
-
-✋️ 👥 💚 💪 🔗 👈 🔧 🎚.
-
-## "🇧🇲" 👐
-
-🐍 📤 🌌 ⚒ 👐 🎓 "🇧🇲".
-
-🚫 🎓 ⚫️ (❔ ⏪ 🇧🇲), ✋️ 👐 👈 🎓.
-
-👈, 👥 📣 👩🔬 `__call__`:
-
-{* ../../docs_src/dependencies/tutorial011.py hl[10] *}
-
-👉 💼, 👉 `__call__` ⚫️❔ **FastAPI** 🔜 ⚙️ ✅ 🌖 🔢 & 🎧-🔗, & 👉 ⚫️❔ 🔜 🤙 🚶♀️ 💲 🔢 👆 *➡ 🛠️ 🔢* ⏪.
-
-## 🔗 👐
-
-& 🔜, 👥 💪 ⚙️ `__init__` 📣 🔢 👐 👈 👥 💪 ⚙️ "🔗" 🔗:
-
-{* ../../docs_src/dependencies/tutorial011.py hl[7] *}
-
-👉 💼, **FastAPI** 🏆 🚫 ⏱ 👆 ⚖️ 💅 🔃 `__init__`, 👥 🔜 ⚙️ ⚫️ 🔗 👆 📟.
-
-## ✍ 👐
-
-👥 💪 ✍ 👐 👉 🎓 ⏮️:
-
-{* ../../docs_src/dependencies/tutorial011.py hl[16] *}
-
-& 👈 🌌 👥 💪 "🔗" 👆 🔗, 👈 🔜 ✔️ `"bar"` 🔘 ⚫️, 🔢 `checker.fixed_content`.
-
-## ⚙️ 👐 🔗
-
-⤴️, 👥 💪 ⚙️ 👉 `checker` `Depends(checker)`, ↩️ `Depends(FixedContentQueryChecker)`, ↩️ 🔗 👐, `checker`, 🚫 🎓 ⚫️.
-
-& 🕐❔ ❎ 🔗, **FastAPI** 🔜 🤙 👉 `checker` 💖:
-
-```Python
-checker(q="somequery")
-```
-
-...& 🚶♀️ ⚫️❔ 👈 📨 💲 🔗 👆 *➡ 🛠️ 🔢* 🔢 `fixed_content_included`:
-
-{* ../../docs_src/dependencies/tutorial011.py hl[20] *}
-
-/// tip
-
-🌐 👉 💪 😑 🎭. & ⚫️ 💪 🚫 📶 🆑 ❔ ⚫️ ⚠.
-
-👫 🖼 😫 🙅, ✋️ 🎦 ❔ ⚫️ 🌐 👷.
-
-📃 🔃 💂♂, 📤 🚙 🔢 👈 🛠️ 👉 🎏 🌌.
-
-🚥 👆 🤔 🌐 👉, 👆 ⏪ 💭 ❔ 👈 🚙 🧰 💂♂ 👷 🔘.
-
-///
diff --git a/docs/em/docs/advanced/async-tests.md b/docs/em/docs/advanced/async-tests.md
deleted file mode 100644
index 283d4aa09..000000000
--- a/docs/em/docs/advanced/async-tests.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# 🔁 💯
-
-👆 ✔️ ⏪ 👀 ❔ 💯 👆 **FastAPI** 🈸 ⚙️ 🚚 `TestClient`. 🆙 🔜, 👆 ✔️ 🕴 👀 ❔ ✍ 🔁 💯, 🍵 ⚙️ `async` 🔢.
-
-➖ 💪 ⚙️ 🔁 🔢 👆 💯 💪 ⚠, 🖼, 🕐❔ 👆 🔬 👆 💽 🔁. 🌈 👆 💚 💯 📨 📨 👆 FastAPI 🈸 & ⤴️ ✔ 👈 👆 👩💻 ⏪ ✍ ☑ 💽 💽, ⏪ ⚙️ 🔁 💽 🗃.
-
-➡️ 👀 ❔ 👥 💪 ⚒ 👈 👷.
-
-## pytest.mark.anyio
-
-🚥 👥 💚 🤙 🔁 🔢 👆 💯, 👆 💯 🔢 ✔️ 🔁. AnyIO 🚚 👌 📁 👉, 👈 ✔ 👥 ✔ 👈 💯 🔢 🤙 🔁.
-
-## 🇸🇲
-
-🚥 👆 **FastAPI** 🈸 ⚙️ 😐 `def` 🔢 ↩️ `async def`, ⚫️ `async` 🈸 🔘.
-
-`TestClient` 🔨 🎱 🔘 🤙 🔁 FastAPI 🈸 👆 😐 `def` 💯 🔢, ⚙️ 🐩 ✳. ✋️ 👈 🎱 🚫 👷 🚫🔜 🕐❔ 👥 ⚙️ ⚫️ 🔘 🔁 🔢. 🏃 👆 💯 🔁, 👥 💪 🙅♂ 📏 ⚙️ `TestClient` 🔘 👆 💯 🔢.
-
-`TestClient` ⚓️ 🔛 🇸🇲, & ↩️, 👥 💪 ⚙️ ⚫️ 🔗 💯 🛠️.
-
-## 🖼
-
-🙅 🖼, ➡️ 🤔 📁 📊 🎏 1️⃣ 🔬 [🦏 🈸](../tutorial/bigger-applications.md){.internal-link target=_blank} & [🔬](../tutorial/testing.md){.internal-link target=_blank}:
-
-```
-.
-├── app
-│ ├── __init__.py
-│ ├── main.py
-│ └── test_main.py
-```
-
-📁 `main.py` 🔜 ✔️:
-
-{* ../../docs_src/async_tests/main.py *}
-
-📁 `test_main.py` 🔜 ✔️ 💯 `main.py`, ⚫️ 💪 👀 💖 👉 🔜:
-
-{* ../../docs_src/async_tests/test_main.py *}
-
-## 🏃 ⚫️
-
-👆 💪 🏃 👆 💯 🐌 📨:
-
-
-
-✋️ 🚥 👥 🔐 🩺 🎚 "🛂" 📛 ⚙️ 🗳 ⏮️ ⛴ `9999`, `/api/v1/docs`, ⚫️ 👷 ☑ ❗ 👶
-
-👆 💪 ✅ ⚫️ http://127.0.0.1:9999/api/v1/docs:
-
-
-
-▶️️ 👥 💚 ⚫️. 👶 👶
-
-👉 ↩️ FastAPI ⚙️ 👉 `root_path` ✍ 🔢 `server` 🗄 ⏮️ 📛 🚚 `root_path`.
-
-## 🌖 💽
-
-/// warning
-
-👉 🌅 🏧 ⚙️ 💼. 💭 🆓 🚶 ⚫️.
-
-///
-
-🔢, **FastAPI** 🔜 ✍ `server` 🗄 🔗 ⏮️ 📛 `root_path`.
-
-✋️ 👆 💪 🚚 🎏 🎛 `servers`, 🖼 🚥 👆 💚 *🎏* 🩺 🎚 🔗 ⏮️ 🏗 & 🏭 🌐.
-
-🚥 👆 🚶♀️ 🛃 📇 `servers` & 📤 `root_path` (↩️ 👆 🛠️ 👨❤👨 ⛅ 🗳), **FastAPI** 🔜 📩 "💽" ⏮️ 👉 `root_path` ▶️ 📇.
-
-🖼:
-
-{* ../../docs_src/behind_a_proxy/tutorial003.py hl[4:7] *}
-
-🔜 🏗 🗄 🔗 💖:
-
-```JSON hl_lines="5-7"
-{
- "openapi": "3.0.2",
- // More stuff here
- "servers": [
- {
- "url": "/api/v1"
- },
- {
- "url": "https://stag.example.com",
- "description": "Staging environment"
- },
- {
- "url": "https://prod.example.com",
- "description": "Production environment"
- }
- ],
- "paths": {
- // More stuff here
- }
-}
-```
-
-/// tip
-
-👀 🚘-🏗 💽 ⏮️ `url` 💲 `/api/v1`, ✊ ⚪️➡️ `root_path`.
-
-///
-
-🩺 🎚 http://127.0.0.1:9999/api/v1/docs ⚫️ 🔜 👀 💖:
-
-
-
-/// tip
-
-🩺 🎚 🔜 🔗 ⏮️ 💽 👈 👆 🖊.
-
-///
-
-### ❎ 🏧 💽 ⚪️➡️ `root_path`
-
-🚥 👆 🚫 💚 **FastAPI** 🔌 🏧 💽 ⚙️ `root_path`, 👆 💪 ⚙️ 🔢 `root_path_in_servers=False`:
-
-{* ../../docs_src/behind_a_proxy/tutorial004.py hl[9] *}
-
-& ⤴️ ⚫️ 🏆 🚫 🔌 ⚫️ 🗄 🔗.
-
-## 🗜 🎧-🈸
-
-🚥 👆 💪 🗻 🎧-🈸 (🔬 [🎧 🈸 - 🗻](sub-applications.md){.internal-link target=_blank}) ⏪ ⚙️ 🗳 ⏮️ `root_path`, 👆 💪 ⚫️ 🛎, 👆 🔜 ⌛.
-
-FastAPI 🔜 🔘 ⚙️ `root_path` 🎆, ⚫️ 🔜 👷. 👶
diff --git a/docs/em/docs/advanced/custom-response.md b/docs/em/docs/advanced/custom-response.md
deleted file mode 100644
index ab95b3e7b..000000000
--- a/docs/em/docs/advanced/custom-response.md
+++ /dev/null
@@ -1,303 +0,0 @@
-# 🛃 📨 - 🕸, 🎏, 📁, 🎏
-
-🔢, **FastAPI** 🔜 📨 📨 ⚙️ `JSONResponse`.
-
-👆 💪 🔐 ⚫️ 🛬 `Response` 🔗 👀 [📨 📨 🔗](response-directly.md){.internal-link target=_blank}.
-
-✋️ 🚥 👆 📨 `Response` 🔗, 📊 🏆 🚫 🔁 🗜, & 🧾 🏆 🚫 🔁 🏗 (🖼, 🔌 🎯 "📻 🆎", 🇺🇸🔍 🎚 `Content-Type` 🍕 🏗 🗄).
-
-✋️ 👆 💪 📣 `Response` 👈 👆 💚 ⚙️, *➡ 🛠️ 👨🎨*.
-
-🎚 👈 👆 📨 ⚪️➡️ 👆 *➡ 🛠️ 🔢* 🔜 🚮 🔘 👈 `Response`.
-
-& 🚥 👈 `Response` ✔️ 🎻 📻 🆎 (`application/json`), 💖 💼 ⏮️ `JSONResponse` & `UJSONResponse`, 💽 👆 📨 🔜 🔁 🗜 (& ⛽) ⏮️ 🙆 Pydantic `response_model` 👈 👆 📣 *➡ 🛠️ 👨🎨*.
-
-/// note
-
-🚥 👆 ⚙️ 📨 🎓 ⏮️ 🙅♂ 📻 🆎, FastAPI 🔜 ⌛ 👆 📨 ✔️ 🙅♂ 🎚, ⚫️ 🔜 🚫 📄 📨 📁 🚮 🏗 🗄 🩺.
-
-///
-
-## ⚙️ `ORJSONResponse`
-
-🖼, 🚥 👆 ✊ 🎭, 👆 💪 ❎ & ⚙️ `orjson` & ⚒ 📨 `ORJSONResponse`.
-
-🗄 `Response` 🎓 (🎧-🎓) 👆 💚 ⚙️ & 📣 ⚫️ *➡ 🛠️ 👨🎨*.
-
-⭕ 📨, 📨 `Response` 🔗 🌅 ⏩ 🌘 🛬 📖.
-
-👉 ↩️ 🔢, FastAPI 🔜 ✔ 🔠 🏬 🔘 & ⚒ 💭 ⚫️ 🎻 ⏮️ 🎻, ⚙️ 🎏 [🎻 🔗 🔢](../tutorial/encoder.md){.internal-link target=_blank} 🔬 🔰. 👉 ⚫️❔ ✔ 👆 📨 **❌ 🎚**, 🖼 💽 🏷.
-
-✋️ 🚥 👆 🎯 👈 🎚 👈 👆 🛬 **🎻 ⏮️ 🎻**, 👆 💪 🚶♀️ ⚫️ 🔗 📨 🎓 & ❎ ➕ 🌥 👈 FastAPI 🔜 ✔️ 🚶♀️ 👆 📨 🎚 🔘 `jsonable_encoder` ⏭ 🚶♀️ ⚫️ 📨 🎓.
-
-{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
-
-/// info
-
-🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
-
-👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `application/json`.
-
- & ⚫️ 🔜 📄 ✅ 🗄.
-
-///
-
-/// tip
-
-`ORJSONResponse` ⏳ 🕴 💪 FastAPI, 🚫 💃.
-
-///
-
-## 🕸 📨
-
-📨 📨 ⏮️ 🕸 🔗 ⚪️➡️ **FastAPI**, ⚙️ `HTMLResponse`.
-
-* 🗄 `HTMLResponse`.
-* 🚶♀️ `HTMLResponse` 🔢 `response_class` 👆 *➡ 🛠️ 👨🎨*.
-
-{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
-
-/// info
-
-🔢 `response_class` 🔜 ⚙️ 🔬 "📻 🆎" 📨.
-
-👉 💼, 🇺🇸🔍 🎚 `Content-Type` 🔜 ⚒ `text/html`.
-
- & ⚫️ 🔜 📄 ✅ 🗄.
-
-///
-
-### 📨 `Response`
-
-👀 [📨 📨 🔗](response-directly.md){.internal-link target=_blank}, 👆 💪 🔐 📨 🔗 👆 *➡ 🛠️*, 🛬 ⚫️.
-
-🎏 🖼 ⚪️➡️ 🔛, 🛬 `HTMLResponse`, 💪 👀 💖:
-
-{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
-
-/// warning
-
-`Response` 📨 🔗 👆 *➡ 🛠️ 🔢* 🏆 🚫 📄 🗄 (🖼, `Content-Type` 🏆 🚫 📄) & 🏆 🚫 ⭐ 🏧 🎓 🩺.
-
-///
-
-/// info
-
-↗️, ☑ `Content-Type` 🎚, 👔 📟, ♒️, 🔜 👟 ⚪️➡️ `Response` 🎚 👆 📨.
-
-///
-
-### 📄 🗄 & 🔐 `Response`
-
-🚥 👆 💚 🔐 📨 ⚪️➡️ 🔘 🔢 ✋️ 🎏 🕰 📄 "📻 🆎" 🗄, 👆 💪 ⚙️ `response_class` 🔢 & 📨 `Response` 🎚.
-
-`response_class` 🔜 ⤴️ ⚙️ 🕴 📄 🗄 *➡ 🛠️*, ✋️ 👆 `Response` 🔜 ⚙️.
-
-#### 📨 `HTMLResponse` 🔗
-
-🖼, ⚫️ 💪 🕳 💖:
-
-{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
-
-👉 🖼, 🔢 `generate_html_response()` ⏪ 🏗 & 📨 `Response` ↩️ 🛬 🕸 `str`.
-
-🛬 🏁 🤙 `generate_html_response()`, 👆 ⏪ 🛬 `Response` 👈 🔜 🔐 🔢 **FastAPI** 🎭.
-
-✋️ 👆 🚶♀️ `HTMLResponse` `response_class` 💁♂️, **FastAPI** 🔜 💭 ❔ 📄 ⚫️ 🗄 & 🎓 🩺 🕸 ⏮️ `text/html`:
-
-
-
-## 💪 📨
-
-📥 💪 📨.
-
-✔️ 🤯 👈 👆 💪 ⚙️ `Response` 📨 🕳 🙆, ⚖️ ✍ 🛃 🎧-🎓.
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
-
-**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-### `Response`
-
-👑 `Response` 🎓, 🌐 🎏 📨 😖 ⚪️➡️ ⚫️.
-
-👆 💪 📨 ⚫️ 🔗.
-
-⚫️ 🚫 📄 🔢:
-
-* `content` - `str` ⚖️ `bytes`.
-* `status_code` - `int` 🇺🇸🔍 👔 📟.
-* `headers` - `dict` 🎻.
-* `media_type` - `str` 🤝 📻 🆎. 🤶 Ⓜ. `"text/html"`.
-
-FastAPI (🤙 💃) 🔜 🔁 🔌 🎚-📐 🎚. ⚫️ 🔜 🔌 🎚-🆎 🎚, ⚓️ 🔛 = & 🔁 = ✍ 🆎.
-
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-
-### `HTMLResponse`
-
-✊ ✍ ⚖️ 🔢 & 📨 🕸 📨, 👆 ✍ 🔛.
-
-### `PlainTextResponse`
-
-✊ ✍ ⚖️ 🔢 & 📨 ✅ ✍ 📨.
-
-{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
-
-### `JSONResponse`
-
-✊ 💽 & 📨 `application/json` 🗜 📨.
-
-👉 🔢 📨 ⚙️ **FastAPI**, 👆 ✍ 🔛.
-
-### `ORJSONResponse`
-
-⏩ 🎛 🎻 📨 ⚙️ `orjson`, 👆 ✍ 🔛.
-
-### `UJSONResponse`
-
-🎛 🎻 📨 ⚙️ `ujson`.
-
-/// warning
-
-`ujson` 🌘 💛 🌘 🐍 🏗-🛠️ ❔ ⚫️ 🍵 📐-💼.
-
-///
-
-{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
-
-/// tip
-
-⚫️ 💪 👈 `ORJSONResponse` 💪 ⏩ 🎛.
-
-///
-
-### `RedirectResponse`
-
-📨 🇺🇸🔍 ❎. ⚙️ 3️⃣0️⃣7️⃣ 👔 📟 (🍕 ❎) 🔢.
-
-👆 💪 📨 `RedirectResponse` 🔗:
-
-{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
-
----
-
-⚖️ 👆 💪 ⚙️ ⚫️ `response_class` 🔢:
-
-
-{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
-
-🚥 👆 👈, ⤴️ 👆 💪 📨 📛 🔗 ⚪️➡️ 👆 *➡ 🛠️* 🔢.
-
-👉 💼, `status_code` ⚙️ 🔜 🔢 1️⃣ `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()`), 👆 💪 ✍ 🚂 🔢 🔁 🤭 👈 📁-💖 🎚.
-
-👈 🌌, 👆 🚫 ✔️ ✍ ⚫️ 🌐 🥇 💾, & 👆 💪 🚶♀️ 👈 🚂 🔢 `StreamingResponse`, & 📨 ⚫️.
-
-👉 🔌 📚 🗃 🔗 ⏮️ ☁ 💾, 📹 🏭, & 🎏.
-
-```{ .python .annotate hl_lines="2 10-12 14" }
-{!../../docs_src/custom_response/tutorial008.py!}
-```
-
-1️⃣. 👉 🚂 🔢. ⚫️ "🚂 🔢" ↩️ ⚫️ 🔌 `yield` 📄 🔘.
-2️⃣. ⚙️ `with` 🍫, 👥 ⚒ 💭 👈 📁-💖 🎚 📪 ⏮️ 🚂 🔢 🔨. , ⏮️ ⚫️ 🏁 📨 📨.
-3️⃣. 👉 `yield from` 💬 🔢 🔁 🤭 👈 👜 🌟 `file_like`. & ⤴️, 🔠 🍕 🔁, 🌾 👈 🍕 👟 ⚪️➡️ 👉 🚂 🔢.
-
- , ⚫️ 🚂 🔢 👈 📨 "🏭" 👷 🕳 🙆 🔘.
-
- 🔨 ⚫️ 👉 🌌, 👥 💪 🚮 ⚫️ `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` & ⚙️ ⚫️.
-
-🖼, ➡️ 💬 👈 👆 💚 ⚙️ `orjson`, ✋️ ⏮️ 🛃 ⚒ 🚫 ⚙️ 🔌 `ORJSONResponse` 🎓.
-
-➡️ 💬 👆 💚 ⚫️ 📨 🔂 & 📁 🎻, 👆 💚 ⚙️ Orjson 🎛 `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"
-}
-```
-
-↗️, 👆 🔜 🎲 🔎 🌅 👍 🌌 ✊ 📈 👉 🌘 ❕ 🎻. 👶
-
-## 🔢 📨 🎓
-
-🕐❔ 🏗 **FastAPI** 🎓 👐 ⚖️ `APIRouter` 👆 💪 ✔ ❔ 📨 🎓 ⚙️ 🔢.
-
-🔢 👈 🔬 👉 `default_response_class`.
-
-🖼 🔛, **FastAPI** 🔜 ⚙️ `ORJSONResponse` 🔢, 🌐 *➡ 🛠️*, ↩️ `JSONResponse`.
-
-{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
-
-/// tip
-
-👆 💪 🔐 `response_class` *➡ 🛠️* ⏭.
-
-///
-
-## 🌖 🧾
-
-👆 💪 📣 📻 🆎 & 📚 🎏 ℹ 🗄 ⚙️ `responses`: [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/em/docs/advanced/dataclasses.md b/docs/em/docs/advanced/dataclasses.md
deleted file mode 100644
index 4dd597262..000000000
--- a/docs/em/docs/advanced/dataclasses.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# ⚙️ 🎻
-
-FastAPI 🏗 🔛 🔝 **Pydantic**, & 👤 ✔️ 🌏 👆 ❔ ⚙️ Pydantic 🏷 📣 📨 & 📨.
-
-✋️ FastAPI 🐕🦺 ⚙️ `dataclasses` 🎏 🌌:
-
-{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
-
-👉 🐕🦺 👏 **Pydantic**, ⚫️ ✔️ 🔗 🐕🦺 `dataclasses`.
-
-, ⏮️ 📟 🔛 👈 🚫 ⚙️ Pydantic 🎯, FastAPI ⚙️ Pydantic 🗜 📚 🐩 🎻 Pydantic 👍 🍛 🎻.
-
-& ↗️, ⚫️ 🐕🦺 🎏:
-
-* 💽 🔬
-* 💽 🛠️
-* 💽 🧾, ♒️.
-
-👉 👷 🎏 🌌 ⏮️ Pydantic 🏷. & ⚫️ 🤙 🏆 🎏 🌌 🔘, ⚙️ Pydantic.
-
-/// info
-
-✔️ 🤯 👈 🎻 💪 🚫 🌐 Pydantic 🏷 💪.
-
-, 👆 5️⃣📆 💪 ⚙️ Pydantic 🏷.
-
-✋️ 🚥 👆 ✔️ 📚 🎻 🤥 🤭, 👉 👌 🎱 ⚙️ 👫 🏋️ 🕸 🛠️ ⚙️ FastAPI. 👶
-
-///
-
-## 🎻 `response_model`
-
-👆 💪 ⚙️ `dataclasses` `response_model` 🔢:
-
-{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
-
-🎻 🔜 🔁 🗜 Pydantic 🎻.
-
-👉 🌌, 🚮 🔗 🔜 🎦 🆙 🛠️ 🩺 👩💻 🔢:
-
-
-
-## 🎻 🔁 📊 📊
-
-👆 💪 🌀 `dataclasses` ⏮️ 🎏 🆎 ✍ ⚒ 🐦 📊 📊.
-
-💼, 👆 💪 ✔️ ⚙️ Pydantic ⏬ `dataclasses`. 🖼, 🚥 👆 ✔️ ❌ ⏮️ 🔁 🏗 🛠️ 🧾.
-
-👈 💼, 👆 💪 🎯 💱 🐩 `dataclasses` ⏮️ `pydantic.dataclasses`, ❔ 💧-♻:
-
-```{ .python .annotate hl_lines="1 5 8-11 14-17 23-25 28" }
-{!../../docs_src/dataclasses/tutorial003.py!}
-```
-
-1️⃣. 👥 🗄 `field` ⚪️➡️ 🐩 `dataclasses`.
-
-2️⃣. `pydantic.dataclasses` 💧-♻ `dataclasses`.
-
-3️⃣. `Author` 🎻 🔌 📇 `Item` 🎻.
-
-4️⃣. `Author` 🎻 ⚙️ `response_model` 🔢.
-
-5️⃣. 👆 💪 ⚙️ 🎏 🐩 🆎 ✍ ⏮️ 🎻 📨 💪.
-
- 👉 💼, ⚫️ 📇 `Item` 🎻.
-
-6️⃣. 📥 👥 🛬 📖 👈 🔌 `items` ❔ 📇 🎻.
-
- FastAPI 🎯 ✍ 💽 🎻.
-
-7️⃣. 📥 `response_model` ⚙️ 🆎 ✍ 📇 `Author` 🎻.
-
- 🔄, 👆 💪 🌀 `dataclasses` ⏮️ 🐩 🆎 ✍.
-
-8️⃣. 👀 👈 👉 *➡ 🛠️ 🔢* ⚙️ 🥔 `def` ↩️ `async def`.
-
- 🕧, FastAPI 👆 💪 🌀 `def` & `async def` 💪.
-
- 🚥 👆 💪 ↗️ 🔃 🕐❔ ⚙️ ❔, ✅ 👅 📄 _"🏃 ❓" _ 🩺 🔃 `async` & `await`.
-
-9️⃣. 👉 *➡ 🛠️ 🔢* 🚫 🛬 🎻 (👐 ⚫️ 💪), ✋️ 📇 📖 ⏮️ 🔗 💽.
-
- FastAPI 🔜 ⚙️ `response_model` 🔢 (👈 🔌 🎻) 🗜 📨.
-
-👆 💪 🌀 `dataclasses` ⏮️ 🎏 🆎 ✍ 📚 🎏 🌀 📨 🏗 📊 📊.
-
-✅-📟 ✍ 💁♂ 🔛 👀 🌅 🎯 ℹ.
-
-## 💡 🌅
-
-👆 💪 🌀 `dataclasses` ⏮️ 🎏 Pydantic 🏷, 😖 ⚪️➡️ 👫, 🔌 👫 👆 👍 🏷, ♒️.
-
-💡 🌅, ✅ Pydantic 🩺 🔃 🎻.
-
-## ⏬
-
-👉 💪 ↩️ FastAPI ⏬ `0.67.0`. 👶
diff --git a/docs/em/docs/advanced/events.md b/docs/em/docs/advanced/events.md
deleted file mode 100644
index 68adb6d65..000000000
--- a/docs/em/docs/advanced/events.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# 🔆 🎉
-
-👆 💪 🔬 ⚛ (📟) 👈 🔜 🛠️ ⏭ 🈸 **▶️ 🆙**. 👉 ⛓ 👈 👉 📟 🔜 🛠️ **🕐**, **⏭** 🈸 **▶️ 📨 📨**.
-
-🎏 🌌, 👆 💪 🔬 ⚛ (📟) 👈 🔜 🛠️ 🕐❔ 🈸 **🤫 🔽**. 👉 💼, 👉 📟 🔜 🛠️ **🕐**, **⏮️** ✔️ 🍵 🎲 **📚 📨**.
-
-↩️ 👉 📟 🛠️ ⏭ 🈸 **▶️** ✊ 📨, & ▶️️ ⏮️ ⚫️ **🏁** 🚚 📨, ⚫️ 📔 🎂 🈸 **🔆** (🔤 "🔆" 🔜 ⚠ 🥈 👶).
-
-👉 💪 📶 ⚠ ⚒ 🆙 **ℹ** 👈 👆 💪 ⚙️ 🎂 📱, & 👈 **💰** 👪 📨, &/⚖️ 👈 👆 💪 **🧹 🆙** ⏮️. 🖼, 💽 🔗 🎱, ⚖️ 🚚 🔗 🎰 🏫 🏷.
-
-## ⚙️ 💼
-
-➡️ ▶️ ⏮️ 🖼 **⚙️ 💼** & ⤴️ 👀 ❔ ❎ ⚫️ ⏮️ 👉.
-
-➡️ 🌈 👈 👆 ✔️ **🎰 🏫 🏷** 👈 👆 💚 ⚙️ 🍵 📨. 👶
-
-🎏 🏷 🔗 👪 📨,, ⚫️ 🚫 1️⃣ 🏷 📍 📨, ⚖️ 1️⃣ 📍 👩💻 ⚖️ 🕳 🎏.
-
-➡️ 🌈 👈 🚚 🏷 💪 **✊ 🕰**, ↩️ ⚫️ ✔️ ✍ 📚 **💽 ⚪️➡️ 💾**. 👆 🚫 💚 ⚫️ 🔠 📨.
-
-👆 💪 📐 ⚫️ 🔝 🎚 🕹/📁, ✋️ 👈 🔜 ⛓ 👈 ⚫️ 🔜 **📐 🏷** 🚥 👆 🏃♂ 🙅 🏧 💯, ⤴️ 👈 💯 🔜 **🐌** ↩️ ⚫️ 🔜 ✔️ ⌛ 🏷 📐 ⏭ 💆♂ 💪 🏃 🔬 🍕 📟.
-
-👈 ⚫️❔ 👥 🔜 ❎, ➡️ 📐 🏷 ⏭ 📨 🍵, ✋️ 🕴 ▶️️ ⏭ 🈸 ▶️ 📨 📨, 🚫 ⏪ 📟 ➖ 📐.
-
-## 🔆
-
-👆 💪 🔬 👉 *🕴* & *🤫* ⚛ ⚙️ `lifespan` 🔢 `FastAPI` 📱, & "🔑 👨💼" (👤 🔜 🎦 👆 ⚫️❔ 👈 🥈).
-
-➡️ ▶️ ⏮️ 🖼 & ⤴️ 👀 ⚫️ ℹ.
-
-👥 ✍ 🔁 🔢 `lifespan()` ⏮️ `yield` 💖 👉:
-
-{* ../../docs_src/events/tutorial003.py hl[16,19] *}
-
-📥 👥 ⚖ 😥 *🕴* 🛠️ 🚚 🏷 🚮 (❌) 🏷 🔢 📖 ⏮️ 🎰 🏫 🏷 ⏭ `yield`. 👉 📟 🔜 🛠️ **⏭** 🈸 **▶️ ✊ 📨**, ⏮️ *🕴*.
-
-& ⤴️, ▶️️ ⏮️ `yield`, 👥 🚚 🏷. 👉 📟 🔜 🛠️ **⏮️** 🈸 **🏁 🚚 📨**, ▶️️ ⏭ *🤫*. 👉 💪, 🖼, 🚀 ℹ 💖 💾 ⚖️ 💻.
-
-/// tip
-
-`shutdown` 🔜 🔨 🕐❔ 👆 **⛔️** 🈸.
-
-🎲 👆 💪 ▶️ 🆕 ⏬, ⚖️ 👆 🤚 🎡 🏃 ⚫️. 🤷
-
-///
-
-### 🔆 🔢
-
-🥇 👜 👀, 👈 👥 ⚖ 🔁 🔢 ⏮️ `yield`. 👉 📶 🎏 🔗 ⏮️ `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()
-```
-
-🕐❔ 👆 ✍ 🔑 👨💼 ⚖️ 🔁 🔑 👨💼 💖 🔛, ⚫️❔ ⚫️ 🔨 👈, ⏭ 🛬 `with` 🍫, ⚫️ 🔜 🛠️ 📟 ⏭ `yield`, & ⏮️ ❎ `with` 🍫, ⚫️ 🔜 🛠️ 📟 ⏮️ `yield`.
-
-👆 📟 🖼 🔛, 👥 🚫 ⚙️ ⚫️ 🔗, ✋️ 👥 🚶♀️ ⚫️ FastAPI ⚫️ ⚙️ ⚫️.
-
-`lifespan` 🔢 `FastAPI` 📱 ✊ **🔁 🔑 👨💼**, 👥 💪 🚶♀️ 👆 🆕 `lifespan` 🔁 🔑 👨💼 ⚫️.
-
-{* ../../docs_src/events/tutorial003.py hl[22] *}
-
-## 🎛 🎉 (😢)
-
-/// warning
-
-👍 🌌 🍵 *🕴* & *🤫* ⚙️ `lifespan` 🔢 `FastAPI` 📱 🔬 🔛.
-
-👆 💪 🎲 🚶 👉 🍕.
-
-///
-
-📤 🎛 🌌 🔬 👉 ⚛ 🛠️ ⏮️ *🕴* & ⏮️ *🤫*.
-
-👆 💪 🔬 🎉 🐕🦺 (🔢) 👈 💪 🛠️ ⏭ 🈸 ▶️ 🆙, ⚖️ 🕐❔ 🈸 🤫 🔽.
-
-👫 🔢 💪 📣 ⏮️ `async def` ⚖️ 😐 `def`.
-
-### `startup` 🎉
-
-🚮 🔢 👈 🔜 🏃 ⏭ 🈸 ▶️, 📣 ⚫️ ⏮️ 🎉 `"startup"`:
-
-{* ../../docs_src/events/tutorial001.py hl[8] *}
-
-👉 💼, `startup` 🎉 🐕🦺 🔢 🔜 🔢 🏬 "💽" ( `dict`) ⏮️ 💲.
-
-👆 💪 🚮 🌅 🌘 1️⃣ 🎉 🐕🦺 🔢.
-
-& 👆 🈸 🏆 🚫 ▶️ 📨 📨 ⏭ 🌐 `startup` 🎉 🐕🦺 ✔️ 🏁.
-
-### `shutdown` 🎉
-
-🚮 🔢 👈 🔜 🏃 🕐❔ 🈸 🤫 🔽, 📣 ⚫️ ⏮️ 🎉 `"shutdown"`:
-
-{* ../../docs_src/events/tutorial002.py hl[6] *}
-
-📥, `shutdown` 🎉 🐕🦺 🔢 🔜 ✍ ✍ ⏸ `"Application shutdown"` 📁 `log.txt`.
-
-/// info
-
-`open()` 🔢, `mode="a"` ⛓ "🎻",, ⏸ 🔜 🚮 ⏮️ ⚫️❔ 🔛 👈 📁, 🍵 📁 ⏮️ 🎚.
-
-///
-
-/// tip
-
-👀 👈 👉 💼 👥 ⚙️ 🐩 🐍 `open()` 🔢 👈 🔗 ⏮️ 📁.
-
-, ⚫️ 🔌 👤/🅾 (🔢/🔢), 👈 🚚 "⌛" 👜 ✍ 💾.
-
-✋️ `open()` 🚫 ⚙️ `async` & `await`.
-
-, 👥 📣 🎉 🐕🦺 🔢 ⏮️ 🐩 `def` ↩️ `async def`.
-
-///
-
-/// info
-
-👆 💪 ✍ 🌅 🔃 👫 🎉 🐕🦺 💃 🎉' 🩺.
-
-///
-
-### `startup` & `shutdown` 👯♂️
-
-📤 ↕ 🤞 👈 ⚛ 👆 *🕴* & *🤫* 🔗, 👆 💪 💚 ▶️ 🕳 & ⤴️ 🏁 ⚫️, 📎 ℹ & ⤴️ 🚀 ⚫️, ♒️.
-
-🔨 👈 👽 🔢 👈 🚫 💰 ⚛ ⚖️ 🔢 👯♂️ 🌅 ⚠ 👆 🔜 💪 🏪 💲 🌐 🔢 ⚖️ 🎏 🎱.
-
-↩️ 👈, ⚫️ 🔜 👍 ↩️ ⚙️ `lifespan` 🔬 🔛.
-
-## 📡 ℹ
-
-📡 ℹ 😟 🤓. 👶
-
-🔘, 🔫 📡 🔧, 👉 🍕 🔆 🛠️, & ⚫️ 🔬 🎉 🤙 `startup` & `shutdown`.
-
-## 🎧 🈸
-
-👶 ✔️ 🤯 👈 👫 🔆 🎉 (🕴 & 🤫) 🔜 🕴 🛠️ 👑 🈸, 🚫 [🎧 🈸 - 🗻](sub-applications.md){.internal-link target=_blank}.
diff --git a/docs/em/docs/advanced/generate-clients.md b/docs/em/docs/advanced/generate-clients.md
deleted file mode 100644
index a680c9051..000000000
--- a/docs/em/docs/advanced/generate-clients.md
+++ /dev/null
@@ -1,238 +0,0 @@
-# 🏗 👩💻
-
-**FastAPI** ⚓️ 🔛 🗄 🔧, 👆 🤚 🏧 🔗 ⏮️ 📚 🧰, 🔌 🏧 🛠️ 🩺 (🚚 🦁 🎚).
-
-1️⃣ 🎯 📈 👈 🚫 🎯 ⭐ 👈 👆 💪 **🏗 👩💻** (🕣 🤙 **📱** ) 👆 🛠️, 📚 🎏 **🛠️ 🇪🇸**.
-
-## 🗄 👩💻 🚂
-
-📤 📚 🧰 🏗 👩💻 ⚪️➡️ **🗄**.
-
-⚠ 🧰 🗄 🚂.
-
-🚥 👆 🏗 **🕸**, 📶 😌 🎛 🗄-📕-🇦🇪.
-
-## 🏗 📕 🕸 👩💻
-
-➡️ ▶️ ⏮️ 🙅 FastAPI 🈸:
-
-{* ../../docs_src/generate_clients/tutorial001.py hl[9:11,14:15,18,19,23] *}
-
-👀 👈 *➡ 🛠️* 🔬 🏷 👫 ⚙️ 📨 🚀 & 📨 🚀, ⚙️ 🏷 `Item` & `ResponseMessage`.
-
-### 🛠️ 🩺
-
-🚥 👆 🚶 🛠️ 🩺, 👆 🔜 👀 👈 ⚫️ ✔️ **🔗** 📊 📨 📨 & 📨 📨:
-
-
-
-👆 💪 👀 👈 🔗 ↩️ 👫 📣 ⏮️ 🏷 📱.
-
-👈 ℹ 💪 📱 **🗄 🔗**, & ⤴️ 🎦 🛠️ 🩺 (🦁 🎚).
-
-& 👈 🎏 ℹ ⚪️➡️ 🏷 👈 🔌 🗄 ⚫️❔ 💪 ⚙️ **🏗 👩💻 📟**.
-
-### 🏗 📕 👩💻
-
-🔜 👈 👥 ✔️ 📱 ⏮️ 🏷, 👥 💪 🏗 👩💻 📟 🕸.
-
-#### ❎ `openapi-ts`
-
-👆 💪 ❎ `openapi-ts` 👆 🕸 📟 ⏮️:
-
-
-
-👆 🔜 🤚 ✍ 🚀 📨:
-
-
-
-/// tip
-
-👀 ✍ `name` & `price`, 👈 🔬 FastAPI 🈸, `Item` 🏷.
-
-///
-
-👆 🔜 ✔️ ⏸ ❌ 📊 👈 👆 📨:
-
-
-
-📨 🎚 🔜 ✔️ ✍:
-
-
-
-## FastAPI 📱 ⏮️ 🔖
-
-📚 💼 👆 FastAPI 📱 🔜 🦏, & 👆 🔜 🎲 ⚙️ 🔖 🎏 🎏 👪 *➡ 🛠️*.
-
-🖼, 👆 💪 ✔️ 📄 **🏬** & ➕1️⃣ 📄 **👩💻**, & 👫 💪 👽 🔖:
-
-
-{* ../../docs_src/generate_clients/tutorial002.py hl[23,28,36] *}
-
-### 🏗 📕 👩💻 ⏮️ 🔖
-
-🚥 👆 🏗 👩💻 FastAPI 📱 ⚙️ 🔖, ⚫️ 🔜 🛎 🎏 👩💻 📟 ⚓️ 🔛 🔖.
-
-👉 🌌 👆 🔜 💪 ✔️ 👜 ✔ & 👪 ☑ 👩💻 📟:
-
-
-
-👉 💼 👆 ✔️:
-
-* `ItemsService`
-* `UsersService`
-
-### 👩💻 👩🔬 📛
-
-▶️️ 🔜 🏗 👩🔬 📛 💖 `createItemItemsPost` 🚫 👀 📶 🧹:
-
-```TypeScript
-ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
-```
-
-...👈 ↩️ 👩💻 🚂 ⚙️ 🗄 🔗 **🛠️ 🆔** 🔠 *➡ 🛠️*.
-
-🗄 🚚 👈 🔠 🛠️ 🆔 😍 🤭 🌐 *➡ 🛠️*, FastAPI ⚙️ **🔢 📛**, **➡**, & **🇺🇸🔍 👩🔬/🛠️** 🏗 👈 🛠️ 🆔, ↩️ 👈 🌌 ⚫️ 💪 ⚒ 💭 👈 🛠️ 🆔 😍.
-
-✋️ 👤 🔜 🎦 👆 ❔ 📉 👈 ⏭. 👶
-
-## 🛃 🛠️ 🆔 & 👍 👩🔬 📛
-
-👆 💪 **🔀** 🌌 👫 🛠️ 🆔 **🏗** ⚒ 👫 🙅 & ✔️ **🙅 👩🔬 📛** 👩💻.
-
-👉 💼 👆 🔜 ✔️ 🚚 👈 🔠 🛠️ 🆔 **😍** 🎏 🌌.
-
-🖼, 👆 💪 ⚒ 💭 👈 🔠 *➡ 🛠️* ✔️ 🔖, & ⤴️ 🏗 🛠️ 🆔 ⚓️ 🔛 **🔖** & *➡ 🛠️* **📛** (🔢 📛).
-
-### 🛃 🏗 😍 🆔 🔢
-
-FastAPI ⚙️ **😍 🆔** 🔠 *➡ 🛠️*, ⚫️ ⚙️ **🛠️ 🆔** & 📛 🙆 💪 🛃 🏷, 📨 ⚖️ 📨.
-
-👆 💪 🛃 👈 🔢. ⚫️ ✊ `APIRoute` & 🔢 🎻.
-
-🖼, 📥 ⚫️ ⚙️ 🥇 🔖 (👆 🔜 🎲 ✔️ 🕴 1️⃣ 🔖) & *➡ 🛠️* 📛 (🔢 📛).
-
-👆 💪 ⤴️ 🚶♀️ 👈 🛃 🔢 **FastAPI** `generate_unique_id_function` 🔢:
-
-{* ../../docs_src/generate_clients/tutorial003.py hl[8:9,12] *}
-
-### 🏗 📕 👩💻 ⏮️ 🛃 🛠️ 🆔
-
-🔜 🚥 👆 🏗 👩💻 🔄, 👆 🔜 👀 👈 ⚫️ ✔️ 📉 👩🔬 📛:
-
-
-
-👆 👀, 👩🔬 📛 🔜 ✔️ 🔖 & ⤴️ 🔢 📛, 🔜 👫 🚫 🔌 ℹ ⚪️➡️ 📛 ➡ & 🇺🇸🔍 🛠️.
-
-### 🗜 🗄 🔧 👩💻 🚂
-
-🏗 📟 ✔️ **❎ ℹ**.
-
-👥 ⏪ 💭 👈 👉 👩🔬 🔗 **🏬** ↩️ 👈 🔤 `ItemsService` (✊ ⚪️➡️ 🔖), ✋️ 👥 ✔️ 📛 🔡 👩🔬 📛 💁♂️. 👶
-
-👥 🔜 🎲 💚 🚧 ⚫️ 🗄 🏢, 👈 🔜 🚚 👈 🛠️ 🆔 **😍**.
-
-✋️ 🏗 👩💻 👥 💪 **🔀** 🗄 🛠️ 🆔 ▶️️ ⏭ 🏭 👩💻, ⚒ 👈 👩🔬 📛 👌 & **🧹**.
-
-👥 💪 ⏬ 🗄 🎻 📁 `openapi.json` & ⤴️ 👥 💪 **❎ 👈 🔡 🔖** ⏮️ ✍ 💖 👉:
-
-{* ../../docs_src/generate_clients/tutorial004.py *}
-
-⏮️ 👈, 🛠️ 🆔 🔜 📁 ⚪️➡️ 👜 💖 `items-get_items` `get_items`, 👈 🌌 👩💻 🚂 💪 🏗 🙅 👩🔬 📛.
-
-### 🏗 📕 👩💻 ⏮️ 🗜 🗄
-
-🔜 🔚 🏁 📁 `openapi.json`, 👆 🔜 🔀 `package.json` ⚙️ 👈 🇧🇿 📁, 🖼:
-
-```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"
- }
-}
-```
-
-⏮️ 🏭 🆕 👩💻, 👆 🔜 🔜 ✔️ **🧹 👩🔬 📛**, ⏮️ 🌐 **✍**, **⏸ ❌**, ♒️:
-
-
-
-## 💰
-
-🕐❔ ⚙️ 🔁 🏗 👩💻 👆 🔜 **✍** :
-
-* 👩🔬.
-* 📨 🚀 💪, 🔢 🔢, ♒️.
-* 📨 🚀.
-
-👆 🔜 ✔️ **⏸ ❌** 🌐.
-
-& 🕐❔ 👆 ℹ 👩💻 📟, & **♻** 🕸, ⚫️ 🔜 ✔️ 🙆 🆕 *➡ 🛠️* 💪 👩🔬, 🗝 🕐 ❎, & 🙆 🎏 🔀 🔜 🎨 🔛 🏗 📟. 👶
-
-👉 ⛓ 👈 🚥 🕳 🔀 ⚫️ 🔜 **🎨** 🔛 👩💻 📟 🔁. & 🚥 👆 **🏗** 👩💻 ⚫️ 🔜 ❌ 👅 🚥 👆 ✔️ 🙆 **🔖** 📊 ⚙️.
-
-, 👆 🔜 **🔍 📚 ❌** 📶 ⏪ 🛠️ 🛵 ↩️ ✔️ ⌛ ❌ 🎦 🆙 👆 🏁 👩💻 🏭 & ⤴️ 🔄 ℹ 🌐❔ ⚠. 👶
diff --git a/docs/em/docs/advanced/index.md b/docs/em/docs/advanced/index.md
deleted file mode 100644
index 48ef8e46d..000000000
--- a/docs/em/docs/advanced/index.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# 🏧 👩💻 🦮
-
-## 🌖 ⚒
-
-👑 [🔰 - 👩💻 🦮](../tutorial/index.md){.internal-link target=_blank} 🔜 🥃 🤝 👆 🎫 🔘 🌐 👑 ⚒ **FastAPI**.
-
-⏭ 📄 👆 🔜 👀 🎏 🎛, 📳, & 🌖 ⚒.
-
-/// tip
-
-⏭ 📄 **🚫 🎯 "🏧"**.
-
- & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
-
-///
-
-## ✍ 🔰 🥇
-
-👆 💪 ⚙️ 🏆 ⚒ **FastAPI** ⏮️ 💡 ⚪️➡️ 👑 [🔰 - 👩💻 🦮](../tutorial/index.md){.internal-link target=_blank}.
-
-& ⏭ 📄 🤔 👆 ⏪ ✍ ⚫️, & 🤔 👈 👆 💭 👈 👑 💭.
-
-## 🏎.🅾 ↗️
-
-🚥 👆 🔜 💖 ✊ 🏧-🔰 ↗️ 🔗 👉 📄 🩺, 👆 💪 💚 ✅: 💯-💾 🛠️ ⏮️ FastAPI & ☁ **🏎.🅾**.
-
-👫 ⏳ 🩸 1️⃣0️⃣ 💯 🌐 💰 🛠️ **FastAPI**. 👶 👶
diff --git a/docs/em/docs/advanced/middleware.md b/docs/em/docs/advanced/middleware.md
deleted file mode 100644
index cb04fa3fb..000000000
--- a/docs/em/docs/advanced/middleware.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# 🏧 🛠️
-
-👑 🔰 👆 ✍ ❔ 🚮 [🛃 🛠️](../tutorial/middleware.md){.internal-link target=_blank} 👆 🈸.
-
-& ⤴️ 👆 ✍ ❔ 🍵 [⚜ ⏮️ `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
-
-👉 📄 👥 🔜 👀 ❔ ⚙️ 🎏 🛠️.
-
-## ❎ 🔫 🛠️
-
-**FastAPI** ⚓️ 🔛 💃 & 🛠️ 🔫 🔧, 👆 💪 ⚙️ 🙆 🔫 🛠️.
-
-🛠️ 🚫 ✔️ ⚒ FastAPI ⚖️ 💃 👷, 📏 ⚫️ ⏩ 🔫 🔌.
-
-🏢, 🔫 🛠️ 🎓 👈 ⌛ 📨 🔫 📱 🥇 ❌.
-
-, 🧾 🥉-🥳 🔫 🛠️ 👫 🔜 🎲 💬 👆 🕳 💖:
-
-```Python
-from unicorn import UnicornMiddleware
-
-app = SomeASGIApp()
-
-new_app = UnicornMiddleware(app, some_config="rainbow")
-```
-
-✋️ FastAPI (🤙 💃) 🚚 🙅 🌌 ⚫️ 👈 ⚒ 💭 👈 🔗 🛠️ 🍵 💽 ❌ & 🛃 ⚠ 🐕🦺 👷 ☑.
-
-👈, 👆 ⚙️ `app.add_middleware()` (🖼 ⚜).
-
-```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` 🏪 👆, 👩💻. ✋️ 🌅 💪 🛠️ 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-## `HTTPSRedirectMiddleware`
-
-🛠️ 👈 🌐 📨 📨 🔜 👯♂️ `https` ⚖️ `wss`.
-
-🙆 📨 📨 `http` ⚖️ `ws` 🔜 ❎ 🔐 ⚖ ↩️.
-
-{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
-
-## `TrustedHostMiddleware`
-
-🛠️ 👈 🌐 📨 📨 ✔️ ☑ ⚒ `Host` 🎚, ✔ 💂♂ 🛡 🇺🇸🔍 🦠 🎚 👊.
-
-{* ../../docs_src/advanced_middleware/tutorial002.py hl[2,6:8] *}
-
-📄 ❌ 🐕🦺:
-
-* `allowed_hosts` - 📇 🆔 📛 👈 🔜 ✔ 📛. 🃏 🆔 ✅ `*.example.com` 🐕🦺 🎀 📁. ✔ 🙆 📛 👯♂️ ⚙️ `allowed_hosts=["*"]` ⚖️ 🚫 🛠️.
-
-🚥 📨 📨 🔨 🚫 ✔ ☑ ⤴️ `400` 📨 🔜 📨.
-
-## `GZipMiddleware`
-
-🍵 🗜 📨 🙆 📨 👈 🔌 `"gzip"` `Accept-Encoding` 🎚.
-
-🛠️ 🔜 🍵 👯♂️ 🐩 & 🎥 📨.
-
-{* ../../docs_src/advanced_middleware/tutorial003.py hl[2,6] *}
-
-📄 ❌ 🐕🦺:
-
-* `minimum_size` - 🚫 🗜 📨 👈 🤪 🌘 👉 💯 📐 🔢. 🔢 `500`.
-
-## 🎏 🛠️
-
-📤 📚 🎏 🔫 🛠️.
-
-🖼:
-
-* Uvicorn `ProxyHeadersMiddleware`
-* 🇸🇲
-
-👀 🎏 💪 🛠️ ✅ 💃 🛠️ 🩺 & 🔫 👌 📇.
diff --git a/docs/em/docs/advanced/openapi-callbacks.md b/docs/em/docs/advanced/openapi-callbacks.md
deleted file mode 100644
index b0a821668..000000000
--- a/docs/em/docs/advanced/openapi-callbacks.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# 🗄 ⏲
-
-👆 💪 ✍ 🛠️ ⏮️ *➡ 🛠️* 👈 💪 ⏲ 📨 *🔢 🛠️* ✍ 👱 🙆 (🎲 🎏 👩💻 👈 🔜 *⚙️* 👆 🛠️).
-
-🛠️ 👈 🔨 🕐❔ 👆 🛠️ 📱 🤙 *🔢 🛠️* 📛 "⏲". ↩️ 🖥 👈 🔢 👩💻 ✍ 📨 📨 👆 🛠️ & ⤴️ 👆 🛠️ *🤙 🔙*, 📨 📨 *🔢 🛠️* (👈 🎲 ✍ 🎏 👩💻).
-
-👉 💼, 👆 💪 💚 📄 ❔ 👈 🔢 🛠️ *🔜* 👀 💖. ⚫️❔ *➡ 🛠️* ⚫️ 🔜 ✔️, ⚫️❔ 💪 ⚫️ 🔜 ⌛, ⚫️❔ 📨 ⚫️ 🔜 📨, ♒️.
-
-## 📱 ⏮️ ⏲
-
-➡️ 👀 🌐 👉 ⏮️ 🖼.
-
-🌈 👆 🛠️ 📱 👈 ✔ 🏗 🧾.
-
-👉 🧾 🔜 ✔️ `id`, `title` (📦), `customer`, & `total`.
-
-👩💻 👆 🛠️ (🔢 👩💻) 🔜 ✍ 🧾 👆 🛠️ ⏮️ 🏤 📨.
-
-⤴️ 👆 🛠️ 🔜 (➡️ 🌈):
-
-* 📨 🧾 🕴 🔢 👩💻.
-* 📈 💸.
-* 📨 📨 🔙 🛠️ 👩💻 (🔢 👩💻).
- * 👉 🔜 🔨 📨 🏤 📨 (⚪️➡️ *👆 🛠️*) *🔢 🛠️* 🚚 👈 🔢 👩💻 (👉 "⏲").
-
-## 😐 **FastAPI** 📱
-
-➡️ 🥇 👀 ❔ 😐 🛠️ 📱 🔜 👀 💖 ⏭ ❎ ⏲.
-
-⚫️ 🔜 ✔️ *➡ 🛠️* 👈 🔜 📨 `Invoice` 💪, & 🔢 🔢 `callback_url` 👈 🔜 🔌 📛 ⏲.
-
-👉 🍕 📶 😐, 🌅 📟 🎲 ⏪ 😰 👆:
-
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[9:13,36:53] *}
-
-/// tip
-
-`callback_url` 🔢 🔢 ⚙️ Pydantic 📛 🆎.
-
-///
-
-🕴 🆕 👜 `callbacks=messages_callback_router.routes` ❌ *➡ 🛠️ 👨🎨*. 👥 🔜 👀 ⚫️❔ 👈 ⏭.
-
-## 🔬 ⏲
-
-☑ ⏲ 📟 🔜 🪀 🙇 🔛 👆 👍 🛠️ 📱.
-
-& ⚫️ 🔜 🎲 🪀 📚 ⚪️➡️ 1️⃣ 📱 ⏭.
-
-⚫️ 💪 1️⃣ ⚖️ 2️⃣ ⏸ 📟, 💖:
-
-```Python
-callback_url = "https://example.com/api/v1/invoices/events/"
-httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
-```
-
-✋️ 🎲 🏆 ⚠ 🍕 ⏲ ⚒ 💭 👈 👆 🛠️ 👩💻 (🔢 👩💻) 🛠️ *🔢 🛠️* ☑, 🛄 💽 👈 *👆 🛠️* 🔜 📨 📨 💪 ⏲, ♒️.
-
-, ⚫️❔ 👥 🔜 ⏭ 🚮 📟 📄 ❔ 👈 *🔢 🛠️* 🔜 👀 💖 📨 ⏲ ⚪️➡️ *👆 🛠️*.
-
-👈 🧾 🔜 🎦 🆙 🦁 🎚 `/docs` 👆 🛠️, & ⚫️ 🔜 ➡️ 🔢 👩💻 💭 ❔ 🏗 *🔢 🛠️*.
-
-👉 🖼 🚫 🛠️ ⏲ ⚫️ (👈 💪 ⏸ 📟), 🕴 🧾 🍕.
-
-/// tip
-
-☑ ⏲ 🇺🇸🔍 📨.
-
-🕐❔ 🛠️ ⏲ 👆, 👆 💪 ⚙️ 🕳 💖 🇸🇲 ⚖️ 📨.
-
-///
-
-## ✍ ⏲ 🧾 📟
-
-👉 📟 🏆 🚫 🛠️ 👆 📱, 👥 🕴 💪 ⚫️ *📄* ❔ 👈 *🔢 🛠️* 🔜 👀 💖.
-
-✋️, 👆 ⏪ 💭 ❔ 💪 ✍ 🏧 🧾 🛠️ ⏮️ **FastAPI**.
-
-👥 🔜 ⚙️ 👈 🎏 💡 📄 ❔ *🔢 🛠️* 🔜 👀 💖... 🏗 *➡ 🛠️(Ⓜ)* 👈 🔢 🛠️ 🔜 🛠️ (🕐 👆 🛠️ 🔜 🤙).
-
-/// tip
-
-🕐❔ ✍ 📟 📄 ⏲, ⚫️ 💪 ⚠ 🌈 👈 👆 👈 *🔢 👩💻*. & 👈 👆 ⏳ 🛠️ *🔢 🛠️*, 🚫 *👆 🛠️*.
-
-🍕 🛠️ 👉 ☝ 🎑 ( *🔢 👩💻*) 💪 ℹ 👆 💭 💖 ⚫️ 🌅 ⭐ 🌐❔ 🚮 🔢, Pydantic 🏷 💪, 📨, ♒️. 👈 *🔢 🛠️*.
-
-///
-
-### ✍ ⏲ `APIRouter`
-
-🥇 ✍ 🆕 `APIRouter` 👈 🔜 🔌 1️⃣ ⚖️ 🌅 ⏲.
-
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
-
-### ✍ ⏲ *➡ 🛠️*
-
-✍ ⏲ *➡ 🛠️* ⚙️ 🎏 `APIRouter` 👆 ✍ 🔛.
-
-⚫️ 🔜 👀 💖 😐 FastAPI *➡ 🛠️*:
-
-* ⚫️ 🔜 🎲 ✔️ 📄 💪 ⚫️ 🔜 📨, ✅ `body: InvoiceEvent`.
-* & ⚫️ 💪 ✔️ 📄 📨 ⚫️ 🔜 📨, ✅ `response_model=InvoiceEventReceived`.
-
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
-
-📤 2️⃣ 👑 🔺 ⚪️➡️ 😐 *➡ 🛠️*:
-
-* ⚫️ 🚫 💪 ✔️ 🙆 ☑ 📟, ↩️ 👆 📱 🔜 🙅 🤙 👉 📟. ⚫️ 🕴 ⚙️ 📄 *🔢 🛠️*. , 🔢 💪 ✔️ `pass`.
-* *➡* 💪 🔌 🗄 3️⃣ 🧬 (👀 🌖 🔛) 🌐❔ ⚫️ 💪 ⚙️ 🔢 ⏮️ 🔢 & 🍕 ⏮️ 📨 📨 *👆 🛠️*.
-
-### ⏲ ➡ 🧬
-
-⏲ *➡* 💪 ✔️ 🗄 3️⃣ 🧬 👈 💪 🔌 🍕 ⏮️ 📨 📨 *👆 🛠️*.
-
-👉 💼, ⚫️ `str`:
-
-```Python
-"{$callback_url}/invoices/{$request.body.id}"
-```
-
-, 🚥 👆 🛠️ 👩💻 (🔢 👩💻) 📨 📨 *👆 🛠️* :
-
-```
-https://yourapi.com/invoices/?callback_url=https://www.external.org/events
-```
-
-⏮️ 🎻 💪:
-
-```JSON
-{
- "id": "2expen51ve",
- "customer": "Mr. Richie Rich",
- "total": "9999"
-}
-```
-
-⤴️ *👆 🛠️* 🔜 🛠️ 🧾, & ☝ ⏪, 📨 ⏲ 📨 `callback_url` ( *🔢 🛠️*):
-
-```
-https://www.external.org/events/invoices/2expen51ve
-```
-
-⏮️ 🎻 💪 ⚗ 🕳 💖:
-
-```JSON
-{
- "description": "Payment celebration",
- "paid": true
-}
-```
-
-& ⚫️ 🔜 ⌛ 📨 ⚪️➡️ 👈 *🔢 🛠️* ⏮️ 🎻 💪 💖:
-
-```JSON
-{
- "ok": true
-}
-```
-
-/// tip
-
-👀 ❔ ⏲ 📛 ⚙️ 🔌 📛 📨 🔢 🔢 `callback_url` (`https://www.external.org/events`) & 🧾 `id` ⚪️➡️ 🔘 🎻 💪 (`2expen51ve`).
-
-///
-
-### 🚮 ⏲ 📻
-
-👉 ☝ 👆 ✔️ *⏲ ➡ 🛠️(Ⓜ)* 💪 (1️⃣(Ⓜ) 👈 *🔢 👩💻* 🔜 🛠️ *🔢 🛠️*) ⏲ 📻 👆 ✍ 🔛.
-
-🔜 ⚙️ 🔢 `callbacks` *👆 🛠️ ➡ 🛠️ 👨🎨* 🚶♀️ 🔢 `.routes` (👈 🤙 `list` 🛣/*➡ 🛠️*) ⚪️➡️ 👈 ⏲ 📻:
-
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
-
-/// tip
-
-👀 👈 👆 🚫 🚶♀️ 📻 ⚫️ (`invoices_callback_router`) `callback=`, ✋️ 🔢 `.routes`, `invoices_callback_router.routes`.
-
-///
-
-### ✅ 🩺
-
-🔜 👆 💪 ▶️ 👆 📱 ⏮️ Uvicorn & 🚶 http://127.0.0.1:8000/docs.
-
-👆 🔜 👀 👆 🩺 ✅ "⏲" 📄 👆 *➡ 🛠️* 👈 🎦 ❔ *🔢 🛠️* 🔜 👀 💖:
-
-
diff --git a/docs/em/docs/advanced/path-operation-advanced-configuration.md b/docs/em/docs/advanced/path-operation-advanced-configuration.md
deleted file mode 100644
index 9d9d5fa8d..000000000
--- a/docs/em/docs/advanced/path-operation-advanced-configuration.md
+++ /dev/null
@@ -1,172 +0,0 @@
-# ➡ 🛠️ 🏧 📳
-
-## 🗄 {
-
-/// warning
-
-🚥 👆 🚫 "🕴" 🗄, 👆 🎲 🚫 💪 👉.
-
-///
-
-👆 💪 ⚒ 🗄 `operationId` ⚙️ 👆 *➡ 🛠️* ⏮️ 🔢 `operation_id`.
-
-👆 🔜 ✔️ ⚒ 💭 👈 ⚫️ 😍 🔠 🛠️.
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
-
-### ⚙️ *➡ 🛠️ 🔢* 📛 {
-
-🚥 👆 💚 ⚙️ 👆 🔗' 🔢 📛 `operationId`Ⓜ, 👆 💪 🔁 🤭 🌐 👫 & 🔐 🔠 *➡ 🛠️* `operation_id` ⚙️ 👫 `APIRoute.name`.
-
-👆 🔜 ⚫️ ⏮️ ❎ 🌐 👆 *➡ 🛠️*.
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2,12:21,24] *}
-
-/// tip
-
-🚥 👆 ❎ 🤙 `app.openapi()`, 👆 🔜 ℹ `operationId`Ⓜ ⏭ 👈.
-
-///
-
-/// warning
-
-🚥 👆 👉, 👆 ✔️ ⚒ 💭 🔠 1️⃣ 👆 *➡ 🛠️ 🔢* ✔️ 😍 📛.
-
-🚥 👫 🎏 🕹 (🐍 📁).
-
-///
-
-## 🚫 ⚪️➡️ 🗄
-
-🚫 *➡ 🛠️* ⚪️➡️ 🏗 🗄 🔗 (& ➡️, ⚪️➡️ 🏧 🧾 ⚙️), ⚙️ 🔢 `include_in_schema` & ⚒ ⚫️ `False`:
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
-
-## 🏧 📛 ⚪️➡️ #️⃣
-
-👆 💪 📉 ⏸ ⚙️ ⚪️➡️ #️⃣ *➡ 🛠️ 🔢* 🗄.
-
-❎ `\f` (😖 "📨 🍼" 🦹) 🤕 **FastAPI** 🔁 🔢 ⚙️ 🗄 👉 ☝.
-
-⚫️ 🏆 🚫 🎦 🆙 🧾, ✋️ 🎏 🧰 (✅ 🐉) 🔜 💪 ⚙️ 🎂.
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
-
-## 🌖 📨
-
-👆 🎲 ✔️ 👀 ❔ 📣 `response_model` & `status_code` *➡ 🛠️*.
-
-👈 🔬 🗃 🔃 👑 📨 *➡ 🛠️*.
-
-👆 💪 📣 🌖 📨 ⏮️ 👫 🏷, 👔 📟, ♒️.
-
-📤 🎂 📃 📥 🧾 🔃 ⚫️, 👆 💪 ✍ ⚫️ [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
-
-## 🗄 ➕
-
-🕐❔ 👆 📣 *➡ 🛠️* 👆 🈸, **FastAPI** 🔁 🏗 🔗 🗃 🔃 👈 *➡ 🛠️* 🔌 🗄 🔗.
-
-/// note | 📡 ℹ
-
-🗄 🔧 ⚫️ 🤙 🛠️ 🎚.
-
-///
-
-⚫️ ✔️ 🌐 ℹ 🔃 *➡ 🛠️* & ⚙️ 🏗 🏧 🧾.
-
-⚫️ 🔌 `tags`, `parameters`, `requestBody`, `responses`, ♒️.
-
-👉 *➡ 🛠️*-🎯 🗄 🔗 🛎 🏗 🔁 **FastAPI**, ✋️ 👆 💪 ↔ ⚫️.
-
-/// tip
-
-👉 🔅 🎚 ↔ ☝.
-
-🚥 👆 🕴 💪 📣 🌖 📨, 🌅 🏪 🌌 ⚫️ ⏮️ [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
-
-///
-
-👆 💪 ↔ 🗄 🔗 *➡ 🛠️* ⚙️ 🔢 `openapi_extra`.
-
-### 🗄 ↔
-
-👉 `openapi_extra` 💪 👍, 🖼, 📣 [🗄 ↔](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial005.py hl[6] *}
-
-🚥 👆 📂 🏧 🛠️ 🩺, 👆 ↔ 🔜 🎦 🆙 🔝 🎯 *➡ 🛠️*.
-
-
-
-& 🚥 👆 👀 📉 🗄 ( `/openapi.json` 👆 🛠️), 👆 🔜 👀 👆 ↔ 🍕 🎯 *➡ 🛠️* 💁♂️:
-
-```JSON hl_lines="22"
-{
- "openapi": "3.0.2",
- "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"
- }
- }
- }
-}
-```
-
-### 🛃 🗄 *➡ 🛠️* 🔗
-
-📖 `openapi_extra` 🔜 🙇 🔗 ⏮️ 🔁 🏗 🗄 🔗 *➡ 🛠️*.
-
-, 👆 💪 🚮 🌖 💽 🔁 🏗 🔗.
-
-🖼, 👆 💪 💭 ✍ & ✔ 📨 ⏮️ 👆 👍 📟, 🍵 ⚙️ 🏧 ⚒ FastAPI ⏮️ Pydantic, ✋️ 👆 💪 💚 🔬 📨 🗄 🔗.
-
-👆 💪 👈 ⏮️ `openapi_extra`:
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[20:37,39:40] *}
-
-👉 🖼, 👥 🚫 📣 🙆 Pydantic 🏷. 👐, 📨 💪 🚫 🎻 🎻, ⚫️ ✍ 🔗 `bytes`, & 🔢 `magic_data_reader()` 🔜 🈚 🎻 ⚫️ 🌌.
-
-👐, 👥 💪 📣 📈 🔗 📨 💪.
-
-### 🛃 🗄 🎚 🆎
-
-⚙️ 👉 🎏 🎱, 👆 💪 ⚙️ Pydantic 🏷 🔬 🎻 🔗 👈 ⤴️ 🔌 🛃 🗄 🔗 📄 *➡ 🛠️*.
-
-& 👆 💪 👉 🚥 💽 🆎 📨 🚫 🎻.
-
-🖼, 👉 🈸 👥 🚫 ⚙️ FastAPI 🛠️ 🛠️ ⚗ 🎻 🔗 ⚪️➡️ Pydantic 🏷 🚫 🏧 🔬 🎻. 👐, 👥 📣 📨 🎚 🆎 📁, 🚫 🎻:
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
-
-👐, 👐 👥 🚫 ⚙️ 🔢 🛠️ 🛠️, 👥 ⚙️ Pydantic 🏷 ❎ 🏗 🎻 🔗 💽 👈 👥 💚 📨 📁.
-
-⤴️ 👥 ⚙️ 📨 🔗, & ⚗ 💪 `bytes`. 👉 ⛓ 👈 FastAPI 🏆 🚫 🔄 🎻 📨 🚀 🎻.
-
-& ⤴️ 👆 📟, 👥 🎻 👈 📁 🎚 🔗, & ⤴️ 👥 🔄 ⚙️ 🎏 Pydantic 🏷 ✔ 📁 🎚:
-
-{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[26:33] *}
-
-/// tip
-
-📥 👥 🏤-⚙️ 🎏 Pydantic 🏷.
-
-✋️ 🎏 🌌, 👥 💪 ✔️ ✔ ⚫️ 🎏 🌌.
-
-///
diff --git a/docs/em/docs/advanced/response-change-status-code.md b/docs/em/docs/advanced/response-change-status-code.md
deleted file mode 100644
index 4933484dd..000000000
--- a/docs/em/docs/advanced/response-change-status-code.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# 📨 - 🔀 👔 📟
-
-👆 🎲 ✍ ⏭ 👈 👆 💪 ⚒ 🔢 [📨 👔 📟](../tutorial/response-status-code.md){.internal-link target=_blank}.
-
-✋️ 💼 👆 💪 📨 🎏 👔 📟 🌘 🔢.
-
-## ⚙️ 💼
-
-🖼, 🌈 👈 👆 💚 📨 🇺🇸🔍 👔 📟 "👌" `200` 🔢.
-
-✋️ 🚥 💽 🚫 🔀, 👆 💚 ✍ ⚫️, & 📨 🇺🇸🔍 👔 📟 "✍" `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` 🔢 🔗, & ⚒ 👔 📟 👫. ✋️ ✔️ 🤯 👈 🏁 1️⃣ ⚒ 🔜 🏆.
diff --git a/docs/em/docs/advanced/response-cookies.md b/docs/em/docs/advanced/response-cookies.md
deleted file mode 100644
index d9fdbaa87..000000000
--- a/docs/em/docs/advanced/response-cookies.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# 📨 🍪
-
-## ⚙️ `Response` 🔢
-
-👆 💪 📣 🔢 🆎 `Response` 👆 *➡ 🛠️ 🔢*.
-
-& ⤴️ 👆 💪 ⚒ 🍪 👈 *🔀* 📨 🎚.
-
-{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
-
-& ⤴️ 👆 💪 📨 🙆 🎚 👆 💪, 👆 🛎 🔜 ( `dict`, 💽 🏷, ♒️).
-
-& 🚥 👆 📣 `response_model`, ⚫️ 🔜 ⚙️ ⛽ & 🗜 🎚 👆 📨.
-
-**FastAPI** 🔜 ⚙️ 👈 *🔀* 📨 ⚗ 🍪 (🎚 & 👔 📟), & 🔜 🚮 👫 🏁 📨 👈 🔌 💲 👆 📨, ⛽ 🙆 `response_model`.
-
-👆 💪 📣 `Response` 🔢 🔗, & ⚒ 🍪 (& 🎚) 👫.
-
-## 📨 `Response` 🔗
-
-👆 💪 ✍ 🍪 🕐❔ 🛬 `Response` 🔗 👆 📟.
-
-👈, 👆 💪 ✍ 📨 🔬 [📨 📨 🔗](response-directly.md){.internal-link target=_blank}.
-
-⤴️ ⚒ 🍪 ⚫️, & ⤴️ 📨 ⚫️:
-
-{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
-
-/// tip
-
-✔️ 🤯 👈 🚥 👆 📨 📨 🔗 ↩️ ⚙️ `Response` 🔢, FastAPI 🔜 📨 ⚫️ 🔗.
-
-, 👆 🔜 ✔️ ⚒ 💭 👆 💽 ☑ 🆎. 🤶 Ⓜ. ⚫️ 🔗 ⏮️ 🎻, 🚥 👆 🛬 `JSONResponse`.
-
- & 👈 👆 🚫 📨 🙆 📊 👈 🔜 ✔️ ⛽ `response_model`.
-
-///
-
-### 🌅 ℹ
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.responses import Response` ⚖️ `from starlette.responses import JSONResponse`.
-
-**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
deleted file mode 100644
index 29819a205..000000000
--- a/docs/em/docs/advanced/response-directly.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# 📨 📨 🔗
-
-🕐❔ 👆 ✍ **FastAPI** *➡ 🛠️* 👆 💪 🛎 📨 🙆 📊 ⚪️➡️ ⚫️: `dict`, `list`, Pydantic 🏷, 💽 🏷, ♒️.
-
-🔢, **FastAPI** 🔜 🔁 🗜 👈 📨 💲 🎻 ⚙️ `jsonable_encoder` 🔬 [🎻 🔗 🔢](../tutorial/encoder.md){.internal-link target=_blank}.
-
-⤴️, ⛅ 🎑, ⚫️ 🔜 🚮 👈 🎻-🔗 💽 (✅ `dict`) 🔘 `JSONResponse` 👈 🔜 ⚙️ 📨 📨 👩💻.
-
-✋️ 👆 💪 📨 `JSONResponse` 🔗 ⚪️➡️ 👆 *➡ 🛠️*.
-
-⚫️ 💪 ⚠, 🖼, 📨 🛃 🎚 ⚖️ 🍪.
-
-## 📨 `Response`
-
-👐, 👆 💪 📨 🙆 `Response` ⚖️ 🙆 🎧-🎓 ⚫️.
-
-/// tip
-
-`JSONResponse` ⚫️ 🎧-🎓 `Response`.
-
-///
-
-& 🕐❔ 👆 📨 `Response`, **FastAPI** 🔜 🚶♀️ ⚫️ 🔗.
-
-⚫️ 🏆 🚫 🙆 💽 🛠️ ⏮️ Pydantic 🏷, ⚫️ 🏆 🚫 🗜 🎚 🙆 🆎, ♒️.
-
-👉 🤝 👆 📚 💪. 👆 💪 📨 🙆 📊 🆎, 🔐 🙆 💽 📄 ⚖️ 🔬, ♒️.
-
-## ⚙️ `jsonable_encoder` `Response`
-
-↩️ **FastAPI** 🚫 🙆 🔀 `Response` 👆 📨, 👆 ✔️ ⚒ 💭 ⚫️ 🎚 🔜 ⚫️.
-
-🖼, 👆 🚫🔜 🚮 Pydantic 🏷 `JSONResponse` 🍵 🥇 🏭 ⚫️ `dict` ⏮️ 🌐 📊 🆎 (💖 `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` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-## 🛬 🛃 `Response`
-
-🖼 🔛 🎦 🌐 🍕 👆 💪, ✋️ ⚫️ 🚫 📶 ⚠, 👆 💪 ✔️ 📨 `item` 🔗, & **FastAPI** 🔜 🚮 ⚫️ `JSONResponse` 👆, 🏭 ⚫️ `dict`, ♒️. 🌐 👈 🔢.
-
-🔜, ➡️ 👀 ❔ 👆 💪 ⚙️ 👈 📨 🛃 📨.
-
-➡️ 💬 👈 👆 💚 📨 📂 📨.
-
-👆 💪 🚮 👆 📂 🎚 🎻, 🚮 ⚫️ `Response`, & 📨 ⚫️:
-
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-
-## 🗒
-
-🕐❔ 👆 📨 `Response` 🔗 🚮 📊 🚫 ✔, 🗜 (🎻), 🚫 📄 🔁.
-
-✋️ 👆 💪 📄 ⚫️ 🔬 [🌖 📨 🗄](additional-responses.md){.internal-link target=_blank}.
-
-👆 💪 👀 ⏪ 📄 ❔ ⚙️/📣 👉 🛃 `Response`Ⓜ ⏪ ✔️ 🏧 💽 🛠️, 🧾, ♒️.
diff --git a/docs/em/docs/advanced/response-headers.md b/docs/em/docs/advanced/response-headers.md
deleted file mode 100644
index e9e1b62d2..000000000
--- a/docs/em/docs/advanced/response-headers.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# 📨 🎚
-
-## ⚙️ `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` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
-
- & `Response` 💪 ⚙️ 🛎 ⚒ 🎚 & 🍪, **FastAPI** 🚚 ⚫️ `fastapi.Response`.
-
-///
-
-## 🛃 🎚
-
-✔️ 🤯 👈 🛃 © 🎚 💪 🚮 ⚙️ '✖-' 🔡.
-
-✋️ 🚥 👆 ✔️ 🛃 🎚 👈 👆 💚 👩💻 🖥 💪 👀, 👆 💪 🚮 👫 👆 ⚜ 📳 (✍ 🌅 [⚜ (✖️-🇨🇳 ℹ 🤝)](../tutorial/cors.md){.internal-link target=_blank}), ⚙️ 🔢 `expose_headers` 📄 💃 ⚜ 🩺.
diff --git a/docs/em/docs/advanced/security/http-basic-auth.md b/docs/em/docs/advanced/security/http-basic-auth.md
deleted file mode 100644
index 73736f3b3..000000000
--- a/docs/em/docs/advanced/security/http-basic-auth.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# 🇺🇸🔍 🔰 🔐
-
-🙅 💼, 👆 💪 ⚙️ 🇺🇸🔍 🔰 🔐.
-
-🇺🇸🔍 🔰 🔐, 🈸 ⌛ 🎚 👈 🔌 🆔 & 🔐.
-
-🚥 ⚫️ 🚫 📨 ⚫️, ⚫️ 📨 🇺🇸🔍 4️⃣0️⃣1️⃣ "⛔" ❌.
-
-& 📨 🎚 `WWW-Authenticate` ⏮️ 💲 `Basic`, & 📦 `realm` 🔢.
-
-👈 💬 🖥 🎦 🛠️ 📋 🆔 & 🔐.
-
-⤴️, 🕐❔ 👆 🆎 👈 🆔 & 🔐, 🖥 📨 👫 🎚 🔁.
-
-## 🙅 🇺🇸🔍 🔰 🔐
-
-* 🗄 `HTTPBasic` & `HTTPBasicCredentials`.
-* ✍ "`security` ⚖" ⚙️ `HTTPBasic`.
-* ⚙️ 👈 `security` ⏮️ 🔗 👆 *➡ 🛠️*.
-* ⚫️ 📨 🎚 🆎 `HTTPBasicCredentials`:
- * ⚫️ 🔌 `username` & `password` 📨.
-
-{* ../../docs_src/security/tutorial006.py hl[2,6,10] *}
-
-🕐❔ 👆 🔄 📂 📛 🥇 🕰 (⚖️ 🖊 "🛠️" 🔼 🩺) 🖥 🔜 💭 👆 👆 🆔 & 🔐:
-
-
-
-## ✅ 🆔
-
-📥 🌅 🏁 🖼.
-
-⚙️ 🔗 ✅ 🚥 🆔 & 🔐 ☑.
-
-👉, ⚙️ 🐍 🐩 🕹 `secrets` ✅ 🆔 & 🔐.
-
-`secrets.compare_digest()` 💪 ✊ `bytes` ⚖️ `str` 👈 🕴 🔌 🔠 🦹 (🕐 🇪🇸), 👉 ⛓ ⚫️ 🚫🔜 👷 ⏮️ 🦹 💖 `á`, `Sebastián`.
-
-🍵 👈, 👥 🥇 🗜 `username` & `password` `bytes` 🔢 👫 ⏮️ 🔠-8️⃣.
-
-⤴️ 👥 💪 ⚙️ `secrets.compare_digest()` 🚚 👈 `credentials.username` `"stanleyjobson"`, & 👈 `credentials.password` `"swordfish"`.
-
-{* ../../docs_src/security/tutorial007.py hl[1,11:21] *}
-
-👉 🔜 🎏:
-
-```Python
-if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
- # Return some error
- ...
-```
-
-✋️ ⚙️ `secrets.compare_digest()` ⚫️ 🔜 🔐 🛡 🆎 👊 🤙 "🕰 👊".
-
-### ⏲ 👊
-
-✋️ ⚫️❔ "⏲ 👊"❓
-
-➡️ 🌈 👊 🔄 💭 🆔 & 🔐.
-
-& 👫 📨 📨 ⏮️ 🆔 `johndoe` & 🔐 `love123`.
-
-⤴️ 🐍 📟 👆 🈸 🔜 🌓 🕳 💖:
-
-```Python
-if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
- ...
-```
-
-✋️ ▶️️ 🙍 🐍 🔬 🥇 `j` `johndoe` 🥇 `s` `stanleyjobson`, ⚫️ 🔜 📨 `False`, ↩️ ⚫️ ⏪ 💭 👈 📚 2️⃣ 🎻 🚫 🎏, 💭 👈 "📤 🙅♂ 💪 🗑 🌅 📊 ⚖ 🎂 🔤". & 👆 🈸 🔜 💬 "❌ 👩💻 ⚖️ 🔐".
-
-✋️ ⤴️ 👊 🔄 ⏮️ 🆔 `stanleyjobsox` & 🔐 `love123`.
-
-& 👆 🈸 📟 🔨 🕳 💖:
-
-```Python
-if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
- ...
-```
-
-🐍 🔜 ✔️ 🔬 🎂 `stanleyjobso` 👯♂️ `stanleyjobsox` & `stanleyjobson` ⏭ 🤔 👈 👯♂️ 🎻 🚫 🎏. ⚫️ 🔜 ✊ ➕ ⏲ 📨 🔙 "❌ 👩💻 ⚖️ 🔐".
-
-#### 🕰 ❔ ℹ 👊
-
-👈 ☝, 👀 👈 💽 ✊ ⏲ 📏 📨 "❌ 👩💻 ⚖️ 🔐" 📨, 👊 🔜 💭 👈 👫 🤚 _🕳_ ▶️️, ▶️ 🔤 ▶️️.
-
-& ⤴️ 👫 💪 🔄 🔄 🤔 👈 ⚫️ 🎲 🕳 🌖 🎏 `stanleyjobsox` 🌘 `johndoe`.
-
-#### "🕴" 👊
-
-↗️, 👊 🔜 🚫 🔄 🌐 👉 ✋, 👫 🔜 ✍ 📋 ⚫️, 🎲 ⏮️ 💯 ⚖️ 💯 💯 📍 🥈. & 🔜 🤚 1️⃣ ➕ ☑ 🔤 🕰.
-
-✋️ 🔨 👈, ⏲ ⚖️ 📆 👊 🔜 ✔️ 💭 ☑ 🆔 & 🔐, ⏮️ "ℹ" 👆 🈸, ⚙️ 🕰 ✊ ❔.
-
-#### 🔧 ⚫️ ⏮️ `secrets.compare_digest()`
-
-✋️ 👆 📟 👥 🤙 ⚙️ `secrets.compare_digest()`.
-
-📏, ⚫️ 🔜 ✊ 🎏 🕰 🔬 `stanleyjobsox` `stanleyjobson` 🌘 ⚫️ ✊ 🔬 `johndoe` `stanleyjobson`. & 🎏 🔐.
-
-👈 🌌, ⚙️ `secrets.compare_digest()` 👆 🈸 📟, ⚫️ 🔜 🔒 🛡 👉 🎂 ↔ 💂♂ 👊.
-
-### 📨 ❌
-
-⏮️ 🔍 👈 🎓 ❌, 📨 `HTTPException` ⏮️ 👔 📟 4️⃣0️⃣1️⃣ (🎏 📨 🕐❔ 🙅♂ 🎓 🚚) & 🚮 🎚 `WWW-Authenticate` ⚒ 🖥 🎦 💳 📋 🔄:
-
-{* ../../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
deleted file mode 100644
index 5cdc47505..000000000
--- a/docs/em/docs/advanced/security/index.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# 🏧 💂♂
-
-## 🌖 ⚒
-
-📤 ➕ ⚒ 🍵 💂♂ ↖️ ⚪️➡️ 🕐 📔 [🔰 - 👩💻 🦮: 💂♂](../../tutorial/security/index.md){.internal-link target=_blank}.
-
-/// tip
-
-⏭ 📄 **🚫 🎯 "🏧"**.
-
- & ⚫️ 💪 👈 👆 ⚙️ 💼, ⚗ 1️⃣ 👫.
-
-///
-
-## ✍ 🔰 🥇
-
-⏭ 📄 🤔 👆 ⏪ ✍ 👑 [🔰 - 👩💻 🦮: 💂♂](../../tutorial/security/index.md){.internal-link target=_blank}.
-
-👫 🌐 ⚓️ 🔛 🎏 🔧, ✋️ ✔ ➕ 🛠️.
diff --git a/docs/em/docs/advanced/security/oauth2-scopes.md b/docs/em/docs/advanced/security/oauth2-scopes.md
deleted file mode 100644
index 9e3bc0058..000000000
--- a/docs/em/docs/advanced/security/oauth2-scopes.md
+++ /dev/null
@@ -1,274 +0,0 @@
-# Oauth2️⃣ ↔
-
-👆 💪 ⚙️ Oauth2️⃣ ↔ 🔗 ⏮️ **FastAPI**, 👫 🛠️ 👷 💎.
-
-👉 🔜 ✔ 👆 ✔️ 🌖 👌-🧽 ✔ ⚙️, 📄 Oauth2️⃣ 🐩, 🛠️ 🔘 👆 🗄 🈸 (& 🛠️ 🩺).
-
-Oauth2️⃣ ⏮️ ↔ 🛠️ ⚙️ 📚 🦏 🤝 🐕🦺, 💖 👱📔, 🇺🇸🔍, 📂, 🤸♂, 👱📔, ♒️. 👫 ⚙️ ⚫️ 🚚 🎯 ✔ 👩💻 & 🈸.
-
-🔠 🕰 👆 "🕹 ⏮️" 👱📔, 🇺🇸🔍, 📂, 🤸♂, 👱📔, 👈 🈸 ⚙️ Oauth2️⃣ ⏮️ ↔.
-
-👉 📄 👆 🔜 👀 ❔ 🛠️ 🤝 & ✔ ⏮️ 🎏 Oauth2️⃣ ⏮️ ↔ 👆 **FastAPI** 🈸.
-
-/// warning
-
-👉 🌅 ⚖️ 🌘 🏧 📄. 🚥 👆 ▶️, 👆 💪 🚶 ⚫️.
-
-👆 🚫 🎯 💪 Oauth2️⃣ ↔, & 👆 💪 🍵 🤝 & ✔ 👐 👆 💚.
-
-✋️ Oauth2️⃣ ⏮️ ↔ 💪 🎆 🛠️ 🔘 👆 🛠️ (⏮️ 🗄) & 👆 🛠️ 🩺.
-
-👐, 👆 🛠️ 📚 ↔, ⚖️ 🙆 🎏 💂♂/✔ 📄, 👐 👆 💪, 👆 📟.
-
-📚 💼, Oauth2️⃣ ⏮️ ↔ 💪 👹.
-
-✋️ 🚥 👆 💭 👆 💪 ⚫️, ⚖️ 👆 😟, 🚧 👂.
-
-///
-
-## Oauth2️⃣ ↔ & 🗄
-
-Oauth2️⃣ 🔧 🔬 "↔" 📇 🎻 🎏 🚀.
-
-🎚 🔠 👉 🎻 💪 ✔️ 🙆 📁, ✋️ 🔜 🚫 🔌 🚀.
-
-👫 ↔ 🎨 "✔".
-
-🗄 (✅ 🛠️ 🩺), 👆 💪 🔬 "💂♂ ⚖".
-
-🕐❔ 1️⃣ 👫 💂♂ ⚖ ⚙️ Oauth2️⃣, 👆 💪 📣 & ⚙️ ↔.
-
-🔠 "↔" 🎻 (🍵 🚀).
-
-👫 🛎 ⚙️ 📣 🎯 💂♂ ✔, 🖼:
-
-* `users:read` ⚖️ `users:write` ⚠ 🖼.
-* `instagram_basic` ⚙️ 👱📔 / 👱📔.
-* `https://www.googleapis.com/auth/drive` ⚙️ 🇺🇸🔍.
-
-/// info
-
-Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
-
-⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
-
-👈 ℹ 🛠️ 🎯.
-
-Oauth2️⃣ 👫 🎻.
-
-///
-
-## 🌐 🎑
-
-🥇, ➡️ 🔜 👀 🍕 👈 🔀 ⚪️➡️ 🖼 👑 **🔰 - 👩💻 🦮** [Oauth2️⃣ ⏮️ 🔐 (& 🔁), 📨 ⏮️ 🥙 🤝](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. 🔜 ⚙️ Oauth2️⃣ ↔:
-
-{* ../../docs_src/security/tutorial005.py hl[2,4,8,12,46,64,105,107:115,121:125,129:135,140,156] *}
-
-🔜 ➡️ 📄 👈 🔀 🔁 🔁.
-
-## Oauth2️⃣ 💂♂ ⚖
-
-🥇 🔀 👈 🔜 👥 📣 Oauth2️⃣ 💂♂ ⚖ ⏮️ 2️⃣ 💪 ↔, `me` & `items`.
-
-`scopes` 🔢 📨 `dict` ⏮️ 🔠 ↔ 🔑 & 📛 💲:
-
-{* ../../docs_src/security/tutorial005.py hl[62:65] *}
-
-↩️ 👥 🔜 📣 📚 ↔, 👫 🔜 🎦 🆙 🛠️ 🩺 🕐❔ 👆 🕹-/✔.
-
-& 👆 🔜 💪 🖊 ❔ ↔ 👆 💚 🤝 🔐: `me` & `items`.
-
-👉 🎏 🛠️ ⚙️ 🕐❔ 👆 🤝 ✔ ⏪ 🚨 ⏮️ 👱📔, 🇺🇸🔍, 📂, ♒️:
-
-
-
-## 🥙 🤝 ⏮️ ↔
-
-🔜, 🔀 🤝 *➡ 🛠️* 📨 ↔ 📨.
-
-👥 ⚙️ 🎏 `OAuth2PasswordRequestForm`. ⚫️ 🔌 🏠 `scopes` ⏮️ `list` `str`, ⏮️ 🔠 ↔ ⚫️ 📨 📨.
-
-& 👥 📨 ↔ 🍕 🥙 🤝.
-
-/// danger
-
-🦁, 📥 👥 ❎ ↔ 📨 🔗 🤝.
-
-✋️ 👆 🈸, 💂♂, 👆 🔜 ⚒ 💭 👆 🕴 🚮 ↔ 👈 👩💻 🤙 💪 ✔️, ⚖️ 🕐 👆 ✔️ 🔁.
-
-///
-
-{* ../../docs_src/security/tutorial005.py hl[156] *}
-
-## 📣 ↔ *➡ 🛠️* & 🔗
-
-🔜 👥 📣 👈 *➡ 🛠️* `/users/me/items/` 🚚 ↔ `items`.
-
-👉, 👥 🗄 & ⚙️ `Security` ⚪️➡️ `fastapi`.
-
-👆 💪 ⚙️ `Security` 📣 🔗 (💖 `Depends`), ✋️ `Security` 📨 🔢 `scopes` ⏮️ 📇 ↔ (🎻).
-
-👉 💼, 👥 🚶♀️ 🔗 🔢 `get_current_active_user` `Security` (🎏 🌌 👥 🔜 ⏮️ `Depends`).
-
-✋️ 👥 🚶♀️ `list` ↔, 👉 💼 ⏮️ 1️⃣ ↔: `items` (⚫️ 💪 ✔️ 🌅).
-
-& 🔗 🔢 `get_current_active_user` 💪 📣 🎧-🔗, 🚫 🕴 ⏮️ `Depends` ✋️ ⏮️ `Security`. 📣 🚮 👍 🎧-🔗 🔢 (`get_current_user`), & 🌖 ↔ 📄.
-
-👉 💼, ⚫️ 🚚 ↔ `me` (⚫️ 💪 🚚 🌅 🌘 1️⃣ ↔).
-
-/// note
-
-👆 🚫 🎯 💪 🚮 🎏 ↔ 🎏 🥉.
-
-👥 🔨 ⚫️ 📥 🎦 ❔ **FastAPI** 🍵 ↔ 📣 🎏 🎚.
-
-///
-
-{* ../../docs_src/security/tutorial005.py hl[4,140,169] *}
-
-/// info | 📡 ℹ
-
-`Security` 🤙 🏿 `Depends`, & ⚫️ ✔️ 1️⃣ ➕ 🔢 👈 👥 🔜 👀 ⏪.
-
-✋️ ⚙️ `Security` ↩️ `Depends`, **FastAPI** 🔜 💭 👈 ⚫️ 💪 📣 💂♂ ↔, ⚙️ 👫 🔘, & 📄 🛠️ ⏮️ 🗄.
-
-✋️ 🕐❔ 👆 🗄 `Query`, `Path`, `Depends`, `Security` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-
-///
-
-## ⚙️ `SecurityScopes`
-
-🔜 ℹ 🔗 `get_current_user`.
-
-👉 1️⃣ ⚙️ 🔗 🔛.
-
-📥 👥 ⚙️ 🎏 Oauth2️⃣ ⚖ 👥 ✍ ⏭, 📣 ⚫️ 🔗: `oauth2_scheme`.
-
-↩️ 👉 🔗 🔢 🚫 ✔️ 🙆 ↔ 📄 ⚫️, 👥 💪 ⚙️ `Depends` ⏮️ `oauth2_scheme`, 👥 🚫 ✔️ ⚙️ `Security` 🕐❔ 👥 🚫 💪 ✔ 💂♂ ↔.
-
-👥 📣 🎁 🔢 🆎 `SecurityScopes`, 🗄 ⚪️➡️ `fastapi.security`.
-
-👉 `SecurityScopes` 🎓 🎏 `Request` (`Request` ⚙️ 🤚 📨 🎚 🔗).
-
-{* ../../docs_src/security/tutorial005.py hl[8,105] *}
-
-## ⚙️ `scopes`
-
-🔢 `security_scopes` 🔜 🆎 `SecurityScopes`.
-
-⚫️ 🔜 ✔️ 🏠 `scopes` ⏮️ 📇 ⚗ 🌐 ↔ ✔ ⚫️ & 🌐 🔗 👈 ⚙️ 👉 🎧-🔗. 👈 ⛓, 🌐 "⚓️"... 👉 💪 🔊 😨, ⚫️ 🔬 🔄 ⏪ 🔛.
-
-`security_scopes` 🎚 (🎓 `SecurityScopes`) 🚚 `scope_str` 🔢 ⏮️ 👁 🎻, 🔌 👈 ↔ 👽 🚀 (👥 🔜 ⚙️ ⚫️).
-
-👥 ✍ `HTTPException` 👈 👥 💪 🏤-⚙️ (`raise`) ⏪ 📚 ☝.
-
-👉 ⚠, 👥 🔌 ↔ 🚚 (🚥 🙆) 🎻 👽 🚀 (⚙️ `scope_str`). 👥 🚮 👈 🎻 ⚗ ↔ `WWW-Authenticate` 🎚 (👉 🍕 🔌).
-
-{* ../../docs_src/security/tutorial005.py hl[105,107:115] *}
-
-## ✔ `username` & 💽 💠
-
-👥 ✔ 👈 👥 🤚 `username`, & ⚗ ↔.
-
-& ⤴️ 👥 ✔ 👈 📊 ⏮️ Pydantic 🏷 (✊ `ValidationError` ⚠), & 🚥 👥 🤚 ❌ 👂 🥙 🤝 ⚖️ ⚖ 📊 ⏮️ Pydantic, 👥 🤚 `HTTPException` 👥 ✍ ⏭.
-
-👈, 👥 ℹ Pydantic 🏷 `TokenData` ⏮️ 🆕 🏠 `scopes`.
-
-⚖ 📊 ⏮️ Pydantic 👥 💪 ⚒ 💭 👈 👥 ✔️, 🖼, ⚫️❔ `list` `str` ⏮️ ↔ & `str` ⏮️ `username`.
-
-↩️, 🖼, `dict`, ⚖️ 🕳 🙆, ⚫️ 💪 💔 🈸 ☝ ⏪, ⚒ ⚫️ 💂♂ ⚠.
-
-👥 ✔ 👈 👥 ✔️ 👩💻 ⏮️ 👈 🆔, & 🚥 🚫, 👥 🤚 👈 🎏 ⚠ 👥 ✍ ⏭.
-
-{* ../../docs_src/security/tutorial005.py hl[46,116:128] *}
-
-## ✔ `scopes`
-
-👥 🔜 ✔ 👈 🌐 ↔ ✔, 👉 🔗 & 🌐 ⚓️ (🔌 *➡ 🛠️*), 🔌 ↔ 🚚 🤝 📨, ⏪ 🤚 `HTTPException`.
-
-👉, 👥 ⚙️ `security_scopes.scopes`, 👈 🔌 `list` ⏮️ 🌐 👫 ↔ `str`.
-
-{* ../../docs_src/security/tutorial005.py hl[129:135] *}
-
-## 🔗 🌲 & ↔
-
-➡️ 📄 🔄 👉 🔗 🌲 & ↔.
-
-`get_current_active_user` 🔗 ✔️ 🎧-🔗 🔛 `get_current_user`, ↔ `"me"` 📣 `get_current_active_user` 🔜 🔌 📇 ✔ ↔ `security_scopes.scopes` 🚶♀️ `get_current_user`.
-
-*➡ 🛠️* ⚫️ 📣 ↔, `"items"`, 👉 🔜 📇 `security_scopes.scopes` 🚶♀️ `get_current_user`.
-
-📥 ❔ 🔗 🔗 & ↔ 👀 💖:
-
-* *➡ 🛠️* `read_own_items` ✔️:
- * ✔ ↔ `["items"]` ⏮️ 🔗:
- * `get_current_active_user`:
- * 🔗 🔢 `get_current_active_user` ✔️:
- * ✔ ↔ `["me"]` ⏮️ 🔗:
- * `get_current_user`:
- * 🔗 🔢 `get_current_user` ✔️:
- * 🙅♂ ↔ ✔ ⚫️.
- * 🔗 ⚙️ `oauth2_scheme`.
- * `security_scopes` 🔢 🆎 `SecurityScopes`:
- * 👉 `security_scopes` 🔢 ✔️ 🏠 `scopes` ⏮️ `list` ⚗ 🌐 👫 ↔ 📣 🔛,:
- * `security_scopes.scopes` 🔜 🔌 `["me", "items"]` *➡ 🛠️* `read_own_items`.
- * `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` ✅ 🔠 *➡ 🛠️*.
-
-🌐 ⚓️ 🔛 `scopes` 📣 🔠 *➡ 🛠️* & 🔠 🔗 🔗 🌲 👈 🎯 *➡ 🛠️*.
-
-///
-
-## 🌖 ℹ 🔃 `SecurityScopes`
-
-👆 💪 ⚙️ `SecurityScopes` 🙆 ☝, & 💗 🥉, ⚫️ 🚫 ✔️ "🌱" 🔗.
-
-⚫️ 🔜 🕧 ✔️ 💂♂ ↔ 📣 ⏮️ `Security` 🔗 & 🌐 ⚓️ **👈 🎯** *➡ 🛠️* & **👈 🎯** 🔗 🌲.
-
-↩️ `SecurityScopes` 🔜 ✔️ 🌐 ↔ 📣 ⚓️, 👆 💪 ⚙️ ⚫️ ✔ 👈 🤝 ✔️ 🚚 ↔ 🇨🇫 🔗 🔢, & ⤴️ 📣 🎏 ↔ 📄 🎏 *➡ 🛠️*.
-
-👫 🔜 ✅ ➡ 🔠 *➡ 🛠️*.
-
-## ✅ ⚫️
-
-🚥 👆 📂 🛠️ 🩺, 👆 💪 🔓 & ✔ ❔ ↔ 👆 💚 ✔.
-
-
-
-🚥 👆 🚫 🖊 🙆 ↔, 👆 🔜 "🔓", ✋️ 🕐❔ 👆 🔄 🔐 `/users/me/` ⚖️ `/users/me/items/` 👆 🔜 🤚 ❌ 💬 👈 👆 🚫 ✔️ 🥃 ✔. 👆 🔜 💪 🔐 `/status/`.
-
-& 🚥 👆 🖊 ↔ `me` ✋️ 🚫 ↔ `items`, 👆 🔜 💪 🔐 `/users/me/` ✋️ 🚫 `/users/me/items/`.
-
-👈 ⚫️❔ 🔜 🔨 🥉 🥳 🈸 👈 🔄 🔐 1️⃣ 👫 *➡ 🛠️* ⏮️ 🤝 🚚 👩💻, ⚓️ 🔛 ❔ 📚 ✔ 👩💻 🤝 🈸.
-
-## 🔃 🥉 🥳 🛠️
-
-👉 🖼 👥 ⚙️ Oauth2️⃣ "🔐" 💧.
-
-👉 ☑ 🕐❔ 👥 🚨 👆 👍 🈸, 🎲 ⏮️ 👆 👍 🕸.
-
-↩️ 👥 💪 💙 ⚫️ 📨 `username` & `password`, 👥 🎛 ⚫️.
-
-✋️ 🚥 👆 🏗 Oauth2️⃣ 🈸 👈 🎏 🔜 🔗 (➡, 🚥 👆 🏗 🤝 🐕🦺 🌓 👱📔, 🇺🇸🔍, 📂, ♒️.) 👆 🔜 ⚙️ 1️⃣ 🎏 💧.
-
-🌅 ⚠ 🔑 💧.
-
-🏆 🔐 📟 💧, ✋️ 🌖 🏗 🛠️ ⚫️ 🚚 🌅 📶. ⚫️ 🌅 🏗, 📚 🐕🦺 🔚 🆙 ✔ 🔑 💧.
-
-/// note
-
-⚫️ ⚠ 👈 🔠 🤝 🐕🦺 📛 👫 💧 🎏 🌌, ⚒ ⚫️ 🍕 👫 🏷.
-
-✋️ 🔚, 👫 🛠️ 🎏 Oauth2️⃣ 🐩.
-
-///
-
-**FastAPI** 🔌 🚙 🌐 👫 Oauth2️⃣ 🤝 💧 `fastapi.security.oauth2`.
-
-## `Security` 👨🎨 `dependencies`
-
-🎏 🌌 👆 💪 🔬 `list` `Depends` 👨🎨 `dependencies` 🔢 (🔬 [🔗 ➡ 🛠️ 👨🎨](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), 👆 💪 ⚙️ `Security` ⏮️ `scopes` 📤.
diff --git a/docs/em/docs/advanced/settings.md b/docs/em/docs/advanced/settings.md
deleted file mode 100644
index 7fdd0d68a..000000000
--- a/docs/em/docs/advanced/settings.md
+++ /dev/null
@@ -1,396 +0,0 @@
-# ⚒ & 🌐 🔢
-
-📚 💼 👆 🈸 💪 💪 🔢 ⚒ ⚖️ 📳, 🖼 ㊙ 🔑, 💽 🎓, 🎓 📧 🐕🦺, ♒️.
-
-🏆 👫 ⚒ 🔢 (💪 🔀), 💖 💽 📛. & 📚 💪 🚿, 💖 ㊙.
-
-👉 🤔 ⚫️ ⚠ 🚚 👫 🌐 🔢 👈 ✍ 🈸.
-
-## 🌐 🔢
-
-/// tip
-
-🚥 👆 ⏪ 💭 ⚫️❔ "🌐 🔢" & ❔ ⚙️ 👫, 💭 🆓 🚶 ⏭ 📄 🔛.
-
-///
-
-🌐 🔢 (💭 "🇨🇻 {") 🔢 👈 🖖 🏞 🐍 📟, 🏃♂ ⚙️, & 💪 ✍ 👆 🐍 📟 (⚖️ 🎏 📋 👍).
-
-👆 💪 ✍ & ⚙️ 🌐 🔢 🐚, 🍵 💆♂ 🐍:
-
-//// tab | 💾, 🇸🇻, 🚪 🎉
-
-
-
-& ⤴️, 📂 🩺 🎧-🈸, http://127.0.0.1:8000/subapi/docs.
-
-👆 🔜 👀 🏧 🛠️ 🩺 🎧-🈸, ✅ 🕴 🚮 👍 _➡ 🛠️_, 🌐 🔽 ☑ 🎧-➡ 🔡 `/subapi`:
-
-
-
-🚥 👆 🔄 🔗 ⏮️ 🙆 2️⃣ 👩💻 🔢, 👫 🔜 👷 ☑, ↩️ 🖥 🔜 💪 💬 🔠 🎯 📱 ⚖️ 🎧-📱.
-
-### 📡 ℹ: `root_path`
-
-🕐❔ 👆 🗻 🎧-🈸 🔬 🔛, FastAPI 🔜 ✊ 💅 🔗 🗻 ➡ 🎧-🈸 ⚙️ 🛠️ ⚪️➡️ 🔫 🔧 🤙 `root_path`.
-
-👈 🌌, 🎧-🈸 🔜 💭 ⚙️ 👈 ➡ 🔡 🩺 🎚.
-
-& 🎧-🈸 💪 ✔️ 🚮 👍 📌 🎧-🈸 & 🌐 🔜 👷 ☑, ↩️ FastAPI 🍵 🌐 👉 `root_path`Ⓜ 🔁.
-
-👆 🔜 💡 🌅 🔃 `root_path` & ❔ ⚙️ ⚫️ 🎯 📄 🔃 [⛅ 🗳](behind-a-proxy.md){.internal-link target=_blank}.
diff --git a/docs/em/docs/advanced/templates.md b/docs/em/docs/advanced/templates.md
deleted file mode 100644
index ad4d4fc71..000000000
--- a/docs/em/docs/advanced/templates.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# 📄
-
-👆 💪 ⚙️ 🙆 📄 🚒 👆 💚 ⏮️ **FastAPI**.
-
-⚠ ⚒ Jinja2️⃣, 🎏 1️⃣ ⚙️ 🏺 & 🎏 🧰.
-
-📤 🚙 🔗 ⚫️ 💪 👈 👆 💪 ⚙️ 🔗 👆 **FastAPI** 🈸 (🚚 💃).
-
-## ❎ 🔗
-
-❎ `jinja2`:
-
-
-
-👆 💪 🆎 📧 🔢 📦, & 📨 👫:
-
-
-
-& 👆 **FastAPI** 🈸 ⏮️ *️⃣ 🔜 📨 🔙:
-
-
-
-👆 💪 📨 (& 📨) 📚 📧:
-
-
-
-& 🌐 👫 🔜 ⚙️ 🎏 *️⃣ 🔗.
-
-## ⚙️ `Depends` & 🎏
-
-*️⃣ 🔗 👆 💪 🗄 ⚪️➡️ `fastapi` & ⚙️:
-
-* `Depends`
-* `Security`
-* `Cookie`
-* `Header`
-* `Path`
-* `Query`
-
-👫 👷 🎏 🌌 🎏 FastAPI 🔗/*➡ 🛠️*:
-
-{* ../../docs_src/websockets/tutorial002.py hl[66:77,76:91] *}
-
-/// info
-
-👉 *️⃣ ⚫️ 🚫 🤙 ⚒ 🔑 🤚 `HTTPException`, ↩️ 👥 🤚 `WebSocketException`.
-
-👆 💪 ⚙️ 📪 📟 ⚪️➡️ ☑ 📟 🔬 🔧.
-
-///
-
-### 🔄 *️⃣ ⏮️ 🔗
-
-🚥 👆 📁 📛 `main.py`, 🏃 👆 🈸 ⏮️:
-
-
-
-## 🚚 🔀 & 💗 👩💻
-
-🕐❔ *️⃣ 🔗 📪, `await websocket.receive_text()` 🔜 🤚 `WebSocketDisconnect` ⚠, ❔ 👆 💪 ⤴️ ✊ & 🍵 💖 👉 🖼.
-
-{* ../../docs_src/websockets/tutorial003.py hl[81:83] *}
-
-🔄 ⚫️ 👅:
-
-* 📂 📱 ⏮️ 📚 🖥 📑.
-* ✍ 📧 ⚪️➡️ 👫.
-* ⤴️ 🔐 1️⃣ 📑.
-
-👈 🔜 🤚 `WebSocketDisconnect` ⚠, & 🌐 🎏 👩💻 🔜 📨 📧 💖:
-
-```
-Client #1596980209979 left the chat
-```
-
-/// tip
-
-📱 🔛 ⭐ & 🙅 🖼 🎦 ❔ 🍵 & 📻 📧 📚 *️⃣ 🔗.
-
-✋️ ✔️ 🤯 👈, 🌐 🍵 💾, 👁 📇, ⚫️ 🔜 🕴 👷 ⏪ 🛠️ 🏃, & 🔜 🕴 👷 ⏮️ 👁 🛠️.
-
-🚥 👆 💪 🕳 ⏩ 🛠️ ⏮️ FastAPI ✋️ 👈 🌖 🏋️, 🐕🦺 ✳, ✳ ⚖️ 🎏, ✅ 🗜/📻.
-
-///
-
-## 🌅 ℹ
-
-💡 🌅 🔃 🎛, ✅ 💃 🧾:
-
-* `WebSocket` 🎓.
-* 🎓-⚓️ *️⃣ 🚚.
diff --git a/docs/em/docs/advanced/wsgi.md b/docs/em/docs/advanced/wsgi.md
deleted file mode 100644
index d923347d5..000000000
--- a/docs/em/docs/advanced/wsgi.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# ✅ 🇨🇻 - 🏺, ✳, 🎏
-
-👆 💪 🗻 🇨🇻 🈸 👆 👀 ⏮️ [🎧 🈸 - 🗻](sub-applications.md){.internal-link target=_blank}, [⛅ 🗳](behind-a-proxy.md){.internal-link target=_blank}.
-
-👈, 👆 💪 ⚙️ `WSGIMiddleware` & ⚙️ ⚫️ 🎁 👆 🇨🇻 🈸, 🖼, 🏺, ✳, ♒️.
-
-## ⚙️ `WSGIMiddleware`
-
-👆 💪 🗄 `WSGIMiddleware`.
-
-⤴️ 🎁 🇨🇻 (✅ 🏺) 📱 ⏮️ 🛠️.
-
-& ⤴️ 🗻 👈 🔽 ➡.
-
-{* ../../docs_src/wsgi/tutorial001.py hl[2:3,22] *}
-
-## ✅ ⚫️
-
-🔜, 🔠 📨 🔽 ➡ `/v1/` 🔜 🍵 🏺 🈸.
-
-& 🎂 🔜 🍵 **FastAPI**.
-
-🚥 👆 🏃 ⚫️ ⏮️ Uvicorn & 🚶 http://localhost:8000/v1/ 👆 🔜 👀 📨 ⚪️➡️ 🏺:
-
-```txt
-Hello, World from Flask!
-```
-
-& 🚥 👆 🚶 http://localhost:8000/v2 👆 🔜 👀 📨 ⚪️➡️ FastAPI:
-
-```JSON
-{
- "message": "Hello World"
-}
-```
diff --git a/docs/em/docs/alternatives.md b/docs/em/docs/alternatives.md
deleted file mode 100644
index 59b587285..000000000
--- a/docs/em/docs/alternatives.md
+++ /dev/null
@@ -1,485 +0,0 @@
-# 🎛, 🌈 & 🔺
-
-⚫️❔ 😮 **FastAPI**, ❔ ⚫️ 🔬 🎏 🎛 & ⚫️❔ ⚫️ 🇭🇲 ⚪️➡️ 👫.
-
-## 🎶
-
-**FastAPI** 🚫🔜 🔀 🚥 🚫 ⏮️ 👷 🎏.
-
-📤 ✔️ 📚 🧰 ✍ ⏭ 👈 ✔️ ℹ 😮 🚮 🏗.
-
-👤 ✔️ ❎ 🏗 🆕 🛠️ 📚 1️⃣2️⃣🗓️. 🥇 👤 🔄 ❎ 🌐 ⚒ 📔 **FastAPI** ⚙️ 📚 🎏 🛠️, 🔌-🔌, & 🧰.
-
-✋️ ☝, 📤 🙅♂ 🎏 🎛 🌘 🏗 🕳 👈 🚚 🌐 👫 ⚒, ✊ 🏆 💭 ⚪️➡️ ⏮️ 🧰, & 🌀 👫 🏆 🌌 💪, ⚙️ 🇪🇸 ⚒ 👈 ➖🚫 💪 ⏭ (🐍 3️⃣.6️⃣ ➕ 🆎 🔑).
-
-## ⏮️ 🧰
-
-### ✳
-
-⚫️ 🌅 🌟 🐍 🛠️ & 🛎 🕴. ⚫️ ⚙️ 🏗 ⚙️ 💖 👱📔.
-
-⚫️ 📶 😆 🔗 ⏮️ 🔗 💽 (💖 ✳ ⚖️ ✳),, ✔️ ☁ 💽 (💖 🗄, ✳, 👸, ♒️) 👑 🏪 🚒 🚫 📶 ⏩.
-
-⚫️ ✍ 🏗 🕸 👩💻, 🚫 ✍ 🔗 ⚙️ 🏛 🕸 (💖 😥, Vue.js & 📐) ⚖️ 🎏 ⚙️ (💖 ☁ 📳) 🔗 ⏮️ ⚫️.
-
-### ✳ 🎂 🛠️
-
-✳ 🎂 🛠️ ✍ 🗜 🧰 🏗 🕸 🔗 ⚙️ ✳ 🔘, 📉 🚮 🛠️ 🛠️.
-
-⚫️ ⚙️ 📚 🏢 ✅ 🦎, 🟥 👒 & 🎟.
-
-⚫️ 🕐 🥇 🖼 **🏧 🛠️ 🧾**, & 👉 🎯 🕐 🥇 💭 👈 😮 "🔎" **FastAPI**.
-
-/// note
-
-✳ 🎂 🛠️ ✍ ✡ 🇺🇸🏛. 🎏 👼 💃 & Uvicorn, 🔛 ❔ **FastAPI** ⚓️.
-
-///
-
-/// check | 😮 **FastAPI**
-
-✔️ 🏧 🛠️ 🧾 🕸 👩💻 🔢.
-
-///
-
-### 🏺
-
-🏺 "🕸", ⚫️ 🚫 🔌 💽 🛠️ 🚫 📚 👜 👈 👟 🔢 ✳.
-
-👉 🦁 & 💪 ✔ 🔨 👜 💖 ⚙️ ☁ 💽 👑 💽 💾 ⚙️.
-
-⚫️ 📶 🙅, ⚫️ 📶 🏋️ 💡, 👐 🧾 🤚 🙁 📡 ☝.
-
-⚫️ 🛎 ⚙️ 🎏 🈸 👈 🚫 🎯 💪 💽, 👩💻 🧾, ⚖️ 🙆 📚 ⚒ 👈 👟 🏤-🏗 ✳. 👐 📚 👫 ⚒ 💪 🚮 ⏮️ 🔌-🔌.
-
-👉 ⚖ 🍕, & ➖ "🕸" 👈 💪 ↔ 📔 ⚫️❔ ⚫️❔ 💪 🔑 ⚒ 👈 👤 💚 🚧.
-
-👐 🦁 🏺, ⚫️ 😑 💖 👍 🏏 🏗 🔗. ⏭ 👜 🔎 "✳ 🎂 🛠️" 🏺.
-
-/// check | 😮 **FastAPI**
-
-◾-🛠️. ⚒ ⚫️ ⏩ 🌀 & 🏏 🧰 & 🍕 💪.
-
-✔️ 🙅 & ⏩ ⚙️ 🕹 ⚙️.
-
-///
-
-### 📨
-
-**FastAPI** 🚫 🤙 🎛 **📨**. 👫 ↔ 📶 🎏.
-
-⚫️ 🔜 🤙 ⚠ ⚙️ 📨 *🔘* FastAPI 🈸.
-
-✋️, FastAPI 🤚 🌈 ⚪️➡️ 📨.
-
-**📨** 🗃 *🔗* ⏮️ 🔗 (👩💻), ⏪ **FastAPI** 🗃 *🏗* 🔗 (💽).
-
-👫, 🌖 ⚖️ 🌘, 🔄 🔚, 🔗 🔠 🎏.
-
-📨 ✔️ 📶 🙅 & 🏋️ 🔧, ⚫️ 📶 ⏩ ⚙️, ⏮️ 🤔 🔢. ✋️ 🎏 🕰, ⚫️ 📶 🏋️ & 🛃.
-
-👈 ⚫️❔, 💬 🛂 🕸:
-
-> 📨 1️⃣ 🏆 ⏬ 🐍 📦 🌐 🕰
-
-🌌 👆 ⚙️ ⚫️ 📶 🙅. 🖼, `GET` 📨, 👆 🔜 ✍:
-
-```Python
-response = requests.get("http://example.com/some/url")
-```
-
-FastAPI 😑 🛠️ *➡ 🛠️* 💪 👀 💖:
-
-```Python hl_lines="1"
-@app.get("/some/url")
-def read_url():
- return {"message": "Hello World"}
-```
-
-👀 🔀 `requests.get(...)` & `@app.get(...)`.
-
-/// check | 😮 **FastAPI**
-
-* ✔️ 🙅 & 🏋️ 🛠️.
-* ⚙️ 🇺🇸🔍 👩🔬 📛 (🛠️) 🔗, 🎯 & 🏋️ 🌌.
-* ✔️ 🤔 🔢, ✋️ 🏋️ 🛃.
-
-///
-
-### 🦁 / 🗄
-
-👑 ⚒ 👤 💚 ⚪️➡️ ✳ 🎂 🛠️ 🏧 🛠️ 🧾.
-
-⤴️ 👤 🔎 👈 📤 🐩 📄 🔗, ⚙️ 🎻 (⚖️ 📁, ↔ 🎻) 🤙 🦁.
-
-& 📤 🕸 👩💻 🔢 🦁 🛠️ ⏪ ✍. , 💆♂ 💪 🏗 🦁 🧾 🛠️ 🔜 ✔ ⚙️ 👉 🕸 👩💻 🔢 🔁.
-
-☝, 🦁 👐 💾 🏛, 📁 🗄.
-
-👈 ⚫️❔ 🕐❔ 💬 🔃 ⏬ 2️⃣.0️⃣ ⚫️ ⚠ 💬 "🦁", & ⏬ 3️⃣ ➕ "🗄".
-
-/// check | 😮 **FastAPI**
-
-🛠️ & ⚙️ 📂 🐩 🛠️ 🔧, ↩️ 🛃 🔗.
-
- & 🛠️ 🐩-⚓️ 👩💻 🔢 🧰:
-
-* 🦁 🎚
-* 📄
-
-👫 2️⃣ 👐 ➖ 📶 🌟 & ⚖, ✋️ 🔨 ⏩ 🔎, 👆 💪 🔎 💯 🌖 🎛 👩💻 🔢 🗄 (👈 👆 💪 ⚙️ ⏮️ **FastAPI**).
-
-///
-
-### 🏺 🎂 🛠️
-
-📤 📚 🏺 🎂 🛠️, ✋️ ⏮️ 💰 🕰 & 👷 🔘 🔬 👫, 👤 🔎 👈 📚 😞 ⚖️ 🚫, ⏮️ 📚 🧍 ❔ 👈 ⚒ 👫 🙃.
-
-### 🍭
-
-1️⃣ 👑 ⚒ 💪 🛠️ ⚙️ 📊 "🛠️" ❔ ✊ 📊 ⚪️➡️ 📟 (🐍) & 🏭 ⚫️ 🔘 🕳 👈 💪 📨 🔘 🕸. 🖼, 🏭 🎚 ⚗ 📊 ⚪️➡️ 💽 🔘 🎻 🎚. 🏭 `datetime` 🎚 🔘 🎻, ♒️.
-
-➕1️⃣ 🦏 ⚒ 💚 🔗 💽 🔬, ⚒ 💭 👈 💽 ☑, 🤝 🎯 🔢. 🖼, 👈 🏑 `int`, & 🚫 🎲 🎻. 👉 ✴️ ⚠ 📨 💽.
-
-🍵 💽 🔬 ⚙️, 👆 🔜 ✔️ 🌐 ✅ ✋, 📟.
-
-👫 ⚒ ⚫️❔ 🍭 🏗 🚚. ⚫️ 👑 🗃, & 👤 ✔️ ⚙️ ⚫️ 📚 ⏭.
-
-✋️ ⚫️ ✍ ⏭ 📤 🔀 🐍 🆎 🔑. , 🔬 🔠 🔗 👆 💪 ⚙️ 🎯 🇨🇻 & 🎓 🚚 🍭.
-
-/// check | 😮 **FastAPI**
-
-⚙️ 📟 🔬 "🔗" 👈 🚚 💽 🆎 & 🔬, 🔁.
-
-///
-
-### Webarg
-
-➕1️⃣ 🦏 ⚒ ✔ 🔗 ✍ 📊 ⚪️➡️ 📨 📨.
-
-Webarg 🧰 👈 ⚒ 🚚 👈 🔛 🔝 📚 🛠️, 🔌 🏺.
-
-⚫️ ⚙️ 🍭 🔘 💽 🔬. & ⚫️ ✍ 🎏 👩💻.
-
-⚫️ 👑 🧰 & 👤 ✔️ ⚙️ ⚫️ 📚 💁♂️, ⏭ ✔️ **FastAPI**.
-
-/// info
-
-Webarg ✍ 🎏 🍭 👩💻.
-
-///
-
-/// check | 😮 **FastAPI**
-
-✔️ 🏧 🔬 📨 📨 💽.
-
-///
-
-### APISpec
-
-🍭 & Webarg 🚚 🔬, ✍ & 🛠️ 🔌-🔌.
-
-✋️ 🧾 ❌. ⤴️ APISpec ✍.
-
-⚫️ 🔌-📚 🛠️ (& 📤 🔌-💃 💁♂️).
-
-🌌 ⚫️ 👷 👈 👆 ✍ 🔑 🔗 ⚙️ 📁 📁 🔘 #️⃣ 🔠 🔢 🚚 🛣.
-
-& ⚫️ 🏗 🗄 🔗.
-
-👈 ❔ ⚫️ 👷 🏺, 💃, 🆘, ♒️.
-
-✋️ ⤴️, 👥 ✔️ 🔄 ⚠ ✔️ ◾-❕, 🔘 🐍 🎻 (🦏 📁).
-
-👨🎨 💪 🚫 ℹ 🌅 ⏮️ 👈. & 🚥 👥 🔀 🔢 ⚖️ 🍭 🔗 & 💭 🔀 👈 📁#️⃣, 🏗 🔗 🔜 ❌.
-
-/// info
-
-APISpec ✍ 🎏 🍭 👩💻.
-
-///
-
-/// check | 😮 **FastAPI**
-
-🐕🦺 📂 🐩 🛠️, 🗄.
-
-///
-
-### 🏺-Apispec
-
-⚫️ 🏺 🔌 -, 👈 👔 👯♂️ Webarg, 🍭 & APISpec.
-
-⚫️ ⚙️ ℹ ⚪️➡️ Webarg & 🍭 🔁 🏗 🗄 🔗, ⚙️ APISpec.
-
-⚫️ 👑 🧰, 📶 🔽-📈. ⚫️ 🔜 🌌 🌖 🌟 🌘 📚 🏺 🔌-🔌 👅 📤. ⚫️ 💪 ↩️ 🚮 🧾 ➖ 💁♂️ 🩲 & 📝.
-
-👉 ❎ ✔️ ✍ 📁 (➕1️⃣ ❕) 🔘 🐍 ✍.
-
-👉 🌀 🏺, 🏺-Apispec ⏮️ 🍭 & Webarg 👇 💕 👩💻 📚 ⏭ 🏗 **FastAPI**.
-
-⚙️ ⚫️ ↘️ 🏗 📚 🏺 🌕-📚 🚂. 👫 👑 📚 👤 (& 📚 🔢 🏉) ✔️ ⚙️ 🆙 🔜:
-
-* https://github.com/tiangolo/full-stack
-* https://github.com/tiangolo/full-stack-flask-couchbase
-* https://github.com/tiangolo/full-stack-flask-couchdb
-
-& 👫 🎏 🌕-📚 🚂 🧢 [**FastAPI** 🏗 🚂](project-generation.md){.internal-link target=_blank}.
-
-/// info
-
-🏺-Apispec ✍ 🎏 🍭 👩💻.
-
-///
-
-/// check | 😮 **FastAPI**
-
-🏗 🗄 🔗 🔁, ⚪️➡️ 🎏 📟 👈 🔬 🛠️ & 🔬.
-
-///
-
-### NestJS (& 📐)
-
-👉 ➖🚫 🚫 🐍, NestJS 🕸 (📕) ✳ 🛠️ 😮 📐.
-
-⚫️ 🏆 🕳 🙁 🎏 ⚫️❔ 💪 🔨 ⏮️ 🏺-Apispec.
-
-⚫️ ✔️ 🛠️ 🔗 💉 ⚙️, 😮 📐 2️⃣. ⚫️ 🚚 🏤-® "💉" (💖 🌐 🎏 🔗 💉 ⚙️ 👤 💭),, ⚫️ 🚮 🎭 & 📟 🔁.
-
-🔢 🔬 ⏮️ 📕 🆎 (🎏 🐍 🆎 🔑), 👨🎨 🐕🦺 👍.
-
-✋️ 📕 📊 🚫 🛡 ⏮️ 📹 🕸, ⚫️ 🚫🔜 ⚓️ 🔛 🆎 🔬 🔬, 🛠️ & 🧾 🎏 🕰. ↩️ 👉 & 🔧 🚫, 🤚 🔬, 🛠️ & 🏧 🔗 ⚡, ⚫️ 💪 🚮 👨🎨 📚 🥉. , ⚫️ ▶️️ 🔁.
-
-⚫️ 💪 🚫 🍵 🔁 🏷 📶 👍. , 🚥 🎻 💪 📨 🎻 🎚 👈 ✔️ 🔘 🏑 👈 🔄 🐦 🎻 🎚, ⚫️ 🚫🔜 ☑ 📄 & ✔.
-
-/// check | 😮 **FastAPI**
-
-⚙️ 🐍 🆎 ✔️ 👑 👨🎨 🐕🦺.
-
-✔️ 🏋️ 🔗 💉 ⚙️. 🔎 🌌 📉 📟 🔁.
-
-///
-
-### 🤣
-
-⚫️ 🕐 🥇 📶 ⏩ 🐍 🛠️ ⚓️ 🔛 `asyncio`. ⚫️ ⚒ 📶 🎏 🏺.
-
-/// note | 📡 ℹ
-
-⚫️ ⚙️ `uvloop` ↩️ 🔢 🐍 `asyncio` ➰. 👈 ⚫️❔ ⚒ ⚫️ ⏩.
-
-⚫️ 🎯 😮 Uvicorn & 💃, 👈 ⏳ ⏩ 🌘 🤣 📂 📇.
-
-///
-
-/// check | 😮 **FastAPI**
-
-🔎 🌌 ✔️ 😜 🎭.
-
-👈 ⚫️❔ **FastAPI** ⚓️ 🔛 💃, ⚫️ ⏩ 🛠️ 💪 (💯 🥉-🥳 📇).
-
-///
-
-### 🦅
-
-🦅 ➕1️⃣ ↕ 🎭 🐍 🛠️, ⚫️ 🔧 ⭐, & 👷 🏛 🎏 🛠️ 💖 🤗.
-
-⚫️ 🏗 ✔️ 🔢 👈 📨 2️⃣ 🔢, 1️⃣ "📨" & 1️⃣ "📨". ⤴️ 👆 "✍" 🍕 ⚪️➡️ 📨, & "✍" 🍕 📨. ↩️ 👉 🔧, ⚫️ 🚫 💪 📣 📨 🔢 & 💪 ⏮️ 🐩 🐍 🆎 🔑 🔢 🔢.
-
-, 💽 🔬, 🛠️, & 🧾, ✔️ ⌛ 📟, 🚫 🔁. ⚖️ 👫 ✔️ 🛠️ 🛠️ 🔛 🔝 🦅, 💖 🤗. 👉 🎏 🔺 🔨 🎏 🛠️ 👈 😮 🦅 🔧, ✔️ 1️⃣ 📨 🎚 & 1️⃣ 📨 🎚 🔢.
-
-/// check | 😮 **FastAPI**
-
-🔎 🌌 🤚 👑 🎭.
-
-⤴️ ⏮️ 🤗 (🤗 ⚓️ 🔛 🦅) 😮 **FastAPI** 📣 `response` 🔢 🔢.
-
-👐 FastAPI ⚫️ 📦, & ⚙️ ✴️ ⚒ 🎚, 🍪, & 🎛 👔 📟.
-
-///
-
-### ♨
-
-👤 🔎 ♨ 🥇 ▶️ 🏗 **FastAPI**. & ⚫️ ✔️ 🎏 💭:
-
-* ⚓️ 🔛 🐍 🆎 🔑.
-* 🔬 & 🧾 ⚪️➡️ 👫 🆎.
-* 🔗 💉 ⚙️.
-
-⚫️ 🚫 ⚙️ 💽 🔬, 🛠️ & 🧾 🥉-🥳 🗃 💖 Pydantic, ⚫️ ✔️ 🚮 👍. , 👫 💽 🆎 🔑 🔜 🚫 ♻ 💪.
-
-⚫️ 🚚 🐥 🍖 🌅 🔁 📳. & ⚫️ ⚓️ 🔛 🇨🇻 (↩️ 🔫), ⚫️ 🚫 🔧 ✊ 📈 ↕-🎭 🚚 🧰 💖 Uvicorn, 💃 & 🤣.
-
-🔗 💉 ⚙️ 🚚 🏤-® 🔗 & 🔗 ❎ 🧢 🔛 📣 🆎. , ⚫️ 🚫 💪 📣 🌅 🌘 1️⃣ "🦲" 👈 🚚 🎯 🆎.
-
-🛣 📣 👁 🥉, ⚙️ 🔢 📣 🎏 🥉 (↩️ ⚙️ 👨🎨 👈 💪 🥉 ▶️️ 🔛 🔝 🔢 👈 🍵 🔗). 👉 🔐 ❔ ✳ 🔨 ⚫️ 🌘 ❔ 🏺 (& 💃) 🔨 ⚫️. ⚫️ 🎏 📟 👜 👈 📶 😆 🔗.
-
-/// check | 😮 **FastAPI**
-
-🔬 ➕ 🔬 💽 🆎 ⚙️ "🔢" 💲 🏷 🔢. 👉 📉 👨🎨 🐕🦺, & ⚫️ 🚫 💪 Pydantic ⏭.
-
-👉 🤙 😮 🛠️ 🍕 Pydantic, 🐕🦺 🎏 🔬 📄 👗 (🌐 👉 🛠️ 🔜 ⏪ 💪 Pydantic).
-
-///
-
-### 🤗
-
-🤗 🕐 🥇 🛠️ 🛠️ 📄 🛠️ 🔢 🆎 ⚙️ 🐍 🆎 🔑. 👉 👑 💭 👈 😮 🎏 🧰 🎏.
-
-⚫️ ⚙️ 🛃 🆎 🚮 📄 ↩️ 🐩 🐍 🆎, ✋️ ⚫️ 🦏 🔁 ⏩.
-
-⚫️ 🕐 🥇 🛠️ 🏗 🛃 🔗 📣 🎂 🛠️ 🎻.
-
-⚫️ 🚫 ⚓️ 🔛 🐩 💖 🗄 & 🎻 🔗. ⚫️ 🚫🔜 🎯 🛠️ ⚫️ ⏮️ 🎏 🧰, 💖 🦁 🎚. ✋️ 🔄, ⚫️ 📶 💡 💭.
-
-⚫️ ✔️ 😌, ⭐ ⚒: ⚙️ 🎏 🛠️, ⚫️ 💪 ✍ 🔗 & 🇳🇨.
-
-⚫️ ⚓️ 🔛 ⏮️ 🐩 🔁 🐍 🕸 🛠️ (🇨🇻), ⚫️ 💪 🚫 🍵 *️⃣ & 🎏 👜, 👐 ⚫️ ✔️ ↕ 🎭 💁♂️.
-
-/// info
-
-🤗 ✍ ✡ 🗄, 🎏 👼 `isort`, 👑 🧰 🔁 😇 🗄 🐍 📁.
-
-///
-
-/// check | 💭 😮 **FastAPI**
-
-🤗 😮 🍕 APIStar, & 1️⃣ 🧰 👤 🔎 🏆 👍, 🌟 APIStar.
-
-🤗 ℹ 😍 **FastAPI** ⚙️ 🐍 🆎 🔑 📣 🔢, & 🏗 🔗 ⚖ 🛠️ 🔁.
-
-🤗 😮 **FastAPI** 📣 `response` 🔢 🔢 ⚒ 🎚 & 🍪.
-
-///
-
-### APIStar (<= 0️⃣.5️⃣)
-
-▶️️ ⏭ 🤔 🏗 **FastAPI** 👤 🔎 **APIStar** 💽. ⚫️ ✔️ 🌖 🌐 👤 👀 & ✔️ 👑 🔧.
-
-⚫️ 🕐 🥇 🛠️ 🛠️ ⚙️ 🐍 🆎 🔑 📣 🔢 & 📨 👈 👤 ⏱ 👀 (⏭ NestJS & ♨). 👤 🔎 ⚫️ 🌅 ⚖️ 🌘 🎏 🕰 🤗. ✋️ APIStar ⚙️ 🗄 🐩.
-
-⚫️ ✔️ 🏧 💽 🔬, 💽 🛠️ & 🗄 🔗 ⚡ ⚓️ 🔛 🎏 🆎 🔑 📚 🥉.
-
-💪 🔗 🔑 🚫 ⚙️ 🎏 🐍 🆎 🔑 💖 Pydantic, ⚫️ 🍖 🌅 🎏 🍭,, 👨🎨 🐕🦺 🚫🔜 👍, ✋️, APIStar 🏆 💪 🎛.
-
-⚫️ ✔️ 🏆 🎭 📇 🕰 (🕴 💥 💃).
-
-🥇, ⚫️ 🚫 ✔️ 🏧 🛠️ 🧾 🕸 🎚, ✋️ 👤 💭 👤 💪 🚮 🦁 🎚 ⚫️.
-
-⚫️ ✔️ 🔗 💉 ⚙️. ⚫️ ✔ 🏤-® 🦲, 🎏 🧰 🔬 🔛. ✋️, ⚫️ 👑 ⚒.
-
-👤 🙅 💪 ⚙️ ⚫️ 🌕 🏗, ⚫️ 🚫 ✔️ 💂♂ 🛠️,, 👤 🚫 🚫 ❎ 🌐 ⚒ 👤 ✔️ ⏮️ 🌕-📚 🚂 ⚓️ 🔛 🏺-Apispec. 👤 ✔️ 👇 📈 🏗 ✍ 🚲 📨 ❎ 👈 🛠️.
-
-✋️ ⤴️, 🏗 🎯 🔀.
-
-⚫️ 🙅♂ 📏 🛠️ 🕸 🛠️, 👼 💪 🎯 🔛 💃.
-
-🔜 APIStar ⚒ 🧰 ✔ 🗄 🔧, 🚫 🕸 🛠️.
-
-/// info
-
-APIStar ✍ ✡ 🇺🇸🏛. 🎏 👨 👈 ✍:
-
-* ✳ 🎂 🛠️
-* 💃 (❔ **FastAPI** ⚓️)
-* Uvicorn (⚙️ 💃 & **FastAPI**)
-
-///
-
-/// check | 😮 **FastAPI**
-
-🔀.
-
-💭 📣 💗 👜 (💽 🔬, 🛠️ & 🧾) ⏮️ 🎏 🐍 🆎, 👈 🎏 🕰 🚚 👑 👨🎨 🐕🦺, 🕳 👤 🤔 💎 💭.
-
- & ⏮️ 🔎 📏 🕰 🎏 🛠️ & 🔬 📚 🎏 🎛, APIStar 🏆 🎛 💪.
-
-⤴️ APIStar ⛔️ 🔀 💽 & 💃 ✍, & 🆕 👻 🏛 ✅ ⚙️. 👈 🏁 🌈 🏗 **FastAPI**.
-
-👤 🤔 **FastAPI** "🛐 👨💼" APIStar, ⏪ 📉 & 📈 ⚒, ⌨ ⚙️, & 🎏 🍕, ⚓️ 🔛 🏫 ⚪️➡️ 🌐 👉 ⏮️ 🧰.
-
-///
-
-## ⚙️ **FastAPI**
-
-### Pydantic
-
-Pydantic 🗃 🔬 💽 🔬, 🛠️ & 🧾 (⚙️ 🎻 🔗) ⚓️ 🔛 🐍 🆎 🔑.
-
-👈 ⚒ ⚫️ 📶 🏋️.
-
-⚫️ ⭐ 🍭. 👐 ⚫️ ⏩ 🌘 🍭 📇. & ⚫️ ⚓️ 🔛 🎏 🐍 🆎 🔑, 👨🎨 🐕🦺 👑.
-
-/// check | **FastAPI** ⚙️ ⚫️
-
-🍵 🌐 💽 🔬, 💽 🛠️ & 🏧 🏷 🧾 (⚓️ 🔛 🎻 🔗).
-
-**FastAPI** ⤴️ ✊ 👈 🎻 🔗 💽 & 🚮 ⚫️ 🗄, ↖️ ⚪️➡️ 🌐 🎏 👜 ⚫️ 🔨.
-
-///
-
-### 💃
-
-💃 💿 🔫 🛠️/🧰, ❔ 💯 🏗 ↕-🎭 ✳ 🐕🦺.
-
-⚫️ 📶 🙅 & 🏋️. ⚫️ 🔧 💪 🏧, & ✔️ 🔧 🦲.
-
-⚫️ ✔️:
-
-* 🤙 🎆 🎭.
-* *️⃣ 🐕🦺.
-* -🛠️ 🖥 📋.
-* 🕴 & 🤫 🎉.
-* 💯 👩💻 🏗 🔛 🇸🇲.
-* ⚜, 🗜, 🎻 📁, 🎏 📨.
-* 🎉 & 🍪 🐕🦺.
-* 1️⃣0️⃣0️⃣ 💯 💯 💰.
-* 1️⃣0️⃣0️⃣ 💯 🆎 ✍ ✍.
-* 👩❤👨 🏋️ 🔗.
-
-💃 ⏳ ⏩ 🐍 🛠️ 💯. 🕴 💥 Uvicorn, ❔ 🚫 🛠️, ✋️ 💽.
-
-💃 🚚 🌐 🔰 🕸 🕸 🛠️.
-
-✋️ ⚫️ 🚫 🚚 🏧 💽 🔬, 🛠️ ⚖️ 🧾.
-
-👈 1️⃣ 👑 👜 👈 **FastAPI** 🚮 🔛 🔝, 🌐 ⚓️ 🔛 🐍 🆎 🔑 (⚙️ Pydantic). 👈, ➕ 🔗 💉 ⚙️, 💂♂ 🚙, 🗄 🔗 ⚡, ♒️.
-
-/// note | 📡 ℹ
-
-🔫 🆕 "🐩" ➖ 🛠️ ✳ 🐚 🏉 👨🎓. ⚫️ 🚫 "🐍 🐩" (🇩🇬), 👐 👫 🛠️ 🔨 👈.
-
-👐, ⚫️ ⏪ ➖ ⚙️ "🐩" 📚 🧰. 👉 📉 📉 🛠️, 👆 💪 🎛 Uvicorn 🙆 🎏 🔫 💽 (💖 👸 ⚖️ Hypercorn), ⚖️ 👆 💪 🚮 🔫 🔗 🧰, 💖 `python-socketio`.
-
-///
-
-/// check | **FastAPI** ⚙️ ⚫️
-
-🍵 🌐 🐚 🕸 🍕. ❎ ⚒ 🔛 🔝.
-
-🎓 `FastAPI` ⚫️ 😖 🔗 ⚪️➡️ 🎓 `Starlette`.
-
-, 🕳 👈 👆 💪 ⏮️ 💃, 👆 💪 ⚫️ 🔗 ⏮️ **FastAPI**, ⚫️ 🌖 💃 🔛 💊.
-
-///
-
-### Uvicorn
-
-Uvicorn 🌩-⏩ 🔫 💽, 🏗 🔛 uvloop & httptool.
-
-⚫️ 🚫 🕸 🛠️, ✋️ 💽. 🖼, ⚫️ 🚫 🚚 🧰 🕹 ➡. 👈 🕳 👈 🛠️ 💖 💃 (⚖️ **FastAPI**) 🔜 🚚 🔛 🔝.
-
-⚫️ 👍 💽 💃 & **FastAPI**.
-
-/// check | **FastAPI** 👍 ⚫️
-
-👑 🕸 💽 🏃 **FastAPI** 🈸.
-
-👆 💪 🌀 ⚫️ ⏮️ 🐁, ✔️ 🔁 👁-🛠️ 💽.
-
-✅ 🌅 ℹ [🛠️](deployment/index.md){.internal-link target=_blank} 📄.
-
-///
-
-## 📇 & 🚅
-
-🤔, 🔬, & 👀 🔺 🖖 Uvicorn, 💃 & FastAPI, ✅ 📄 🔃 [📇](benchmarks.md){.internal-link target=_blank}.
diff --git a/docs/em/docs/async.md b/docs/em/docs/async.md
deleted file mode 100644
index cde778b0f..000000000
--- a/docs/em/docs/async.md
+++ /dev/null
@@ -1,442 +0,0 @@
-# 🛠️ & 🔁 / ⌛
-
-ℹ 🔃 `async def` ❕ *➡ 🛠️ 🔢* & 🖥 🔃 🔁 📟, 🛠️, & 🔁.
-
-## 🏃 ❓
-
-🆑;👩⚕️:
-
-🚥 👆 ⚙️ 🥉 🥳 🗃 👈 💬 👆 🤙 👫 ⏮️ `await`, 💖:
-
-```Python
-results = await some_library()
-```
-
-⤴️, 📣 👆 *➡ 🛠️ 🔢* ⏮️ `async def` 💖:
-
-```Python hl_lines="2"
-@app.get('/')
-async def read_results():
- results = await some_library()
- return results
-```
-
-/// note
-
-👆 💪 🕴 ⚙️ `await` 🔘 🔢 ✍ ⏮️ `async def`.
-
-///
-
----
-
-🚥 👆 ⚙️ 🥉 🥳 🗃 👈 🔗 ⏮️ 🕳 (💽, 🛠️, 📁 ⚙️, ♒️.) & 🚫 ✔️ 🐕🦺 ⚙️ `await`, (👉 ⏳ 💼 🌅 💽 🗃), ⤴️ 📣 👆 *➡ 🛠️ 🔢* 🛎, ⏮️ `def`, 💖:
-
-```Python hl_lines="2"
-@app.get('/')
-def results():
- results = some_library()
- return results
-```
-
----
-
-🚥 👆 🈸 (😫) 🚫 ✔️ 🔗 ⏮️ 🕳 🙆 & ⌛ ⚫️ 📨, ⚙️ `async def`.
-
----
-
-🚥 👆 🚫 💭, ⚙️ 😐 `def`.
-
----
-
-**🗒**: 👆 💪 🌀 `def` & `async def` 👆 *➡ 🛠️ 🔢* 🌅 👆 💪 & 🔬 🔠 1️⃣ ⚙️ 🏆 🎛 👆. FastAPI 🔜 ▶️️ 👜 ⏮️ 👫.
-
-😆, 🙆 💼 🔛, FastAPI 🔜 👷 🔁 & 📶 ⏩.
-
-✋️ 📄 📶 🔛, ⚫️ 🔜 💪 🎭 🛠️.
-
-## 📡 ℹ
-
-🏛 ⏬ 🐍 ✔️ 🐕🦺 **"🔁 📟"** ⚙️ 🕳 🤙 **"🔁"**, ⏮️ **`async` & `await`** ❕.
-
-➡️ 👀 👈 🔤 🍕 📄 🔛:
-
-* **🔁 📟**
-* **`async` & `await`**
-* **🔁**
-
-## 🔁 📟
-
-🔁 📟 ⛓ 👈 🇪🇸 👶 ✔️ 🌌 💬 💻 / 📋 👶 👈 ☝ 📟, ⚫️ 👶 🔜 ✔️ ⌛ *🕳 🙆* 🏁 👱 🙆. ➡️ 💬 👈 *🕳 🙆* 🤙 "🐌-📁" 👶.
-
-, ⏮️ 👈 🕰, 💻 💪 🚶 & 🎏 👷, ⏪ "🐌-📁" 👶 🏁.
-
-⤴️ 💻 / 📋 👶 🔜 👟 🔙 🔠 🕰 ⚫️ ✔️ 🤞 ↩️ ⚫️ ⌛ 🔄, ⚖️ 🕐❔ ⚫️ 👶 🏁 🌐 👷 ⚫️ ✔️ 👈 ☝. & ⚫️ 👶 🔜 👀 🚥 🙆 📋 ⚫️ ⌛ ✔️ ⏪ 🏁, 🤸 ⚫️❔ ⚫️ ✔️.
-
-⏭, ⚫️ 👶 ✊ 🥇 📋 🏁 (➡️ 💬, 👆 "🐌-📁" 👶) & 😣 ⚫️❔ ⚫️ ✔️ ⏮️ ⚫️.
-
-👈 "⌛ 🕳 🙆" 🛎 🔗 👤/🅾 🛠️ 👈 📶 "🐌" (🔬 🚅 🕹 & 💾 💾), 💖 ⌛:
-
-* 📊 ⚪️➡️ 👩💻 📨 🔘 🕸
-* 📊 📨 👆 📋 📨 👩💻 🔘 🕸
-* 🎚 📁 💾 ✍ ⚙️ & 🤝 👆 📋
-* 🎚 👆 📋 🤝 ⚙️ ✍ 💾
-* 🛰 🛠️ 🛠️
-* 💽 🛠️ 🏁
-* 💽 🔢 📨 🏁
-* ♒️.
-
-🛠️ 🕰 🍴 ✴️ ⌛ 👤/🅾 🛠️, 👫 🤙 👫 "👤/🅾 🔗" 🛠️.
-
-⚫️ 🤙 "🔁" ↩️ 💻 / 📋 🚫 ✔️ "🔁" ⏮️ 🐌 📋, ⌛ ☑ 🙍 👈 📋 🏁, ⏪ 🔨 🕳, 💪 ✊ 📋 🏁 & 😣 👷.
-
-↩️ 👈, 💆♂ "🔁" ⚙️, 🕐 🏁, 📋 💪 ⌛ ⏸ 🐥 👄 (⏲) 💻 / 📋 🏁 ⚫️❔ ⚫️ 🚶, & ⤴️ 👟 🔙 ✊ 🏁 & 😣 👷 ⏮️ 👫.
-
-"🔁" (👽 "🔁") 👫 🛎 ⚙️ ⚖ "🔁", ↩️ 💻 / 📋 ⏩ 🌐 📶 🔁 ⏭ 🔀 🎏 📋, 🚥 👈 🔁 🔌 ⌛.
-
-### 🛠️ & 🍔
-
-👉 💭 **🔁** 📟 🔬 🔛 🕣 🤙 **"🛠️"**. ⚫️ 🎏 ⚪️➡️ **"🔁"**.
-
-**🛠️** & **🔁** 👯♂️ 🔗 "🎏 👜 😥 🌅 ⚖️ 🌘 🎏 🕰".
-
-✋️ ℹ 🖖 *🛠️* & *🔁* 🎏.
-
-👀 🔺, 🌈 📄 📖 🔃 🍔:
-
-### 🛠️ 🍔
-
-👆 🚶 ⏮️ 👆 🥰 🤚 ⏩ 🥕, 👆 🧍 ⏸ ⏪ 🏧 ✊ ✔ ⚪️➡️ 👫👫 🚪 👆. 👶
-
-
-
-⤴️ ⚫️ 👆 🔄, 👆 🥉 👆 ✔ 2️⃣ 📶 🎀 🍔 👆 🥰 & 👆. 👶 👶
-
-
-
-🏧 💬 🕳 🍳 👨🍳 👫 💭 👫 ✔️ 🏗 👆 🍔 (✋️ 👫 ⏳ 🏗 🕐 ⏮️ 👩💻).
-
-
-
-👆 💸. 👶
-
-🏧 🤝 👆 🔢 👆 🔄.
-
-
-
-⏪ 👆 ⌛, 👆 🚶 ⏮️ 👆 🥰 & ⚒ 🏓, 👆 🧎 & 💬 ⏮️ 👆 🥰 📏 🕰 (👆 🍔 📶 🎀 & ✊ 🕰 🏗).
-
-👆 🏖 🏓 ⏮️ 👆 🥰, ⏪ 👆 ⌛ 🍔, 👆 💪 💸 👈 🕰 😮 ❔ 👌, 🐨 & 🙃 👆 🥰 👶 👶 👶.
-
-
-
-⏪ ⌛ & 💬 👆 🥰, ⚪️➡️ 🕰 🕰, 👆 ✅ 🔢 🖥 🔛 ⏲ 👀 🚥 ⚫️ 👆 🔄 ⏪.
-
-⤴️ ☝, ⚫️ 😒 👆 🔄. 👆 🚶 ⏲, 🤚 👆 🍔 & 👟 🔙 🏓.
-
-
-
-👆 & 👆 🥰 🍴 🍔 & ✔️ 👌 🕰. 👶
-
-
-
-/// info
-
-🌹 🖼 👯 🍏. 👶
-
-///
-
----
-
-🌈 👆 💻 / 📋 👶 👈 📖.
-
-⏪ 👆 ⏸, 👆 ⛽ 👶, ⌛ 👆 🔄, 🚫 🔨 🕳 📶 "😌". ✋️ ⏸ ⏩ ↩️ 🏧 🕴 ✊ ✔ (🚫 🏗 👫), 👈 👌.
-
-⤴️, 🕐❔ ⚫️ 👆 🔄, 👆 ☑ "😌" 👷, 👆 🛠️ 🍣, 💭 ⚫️❔ 👆 💚, 🤚 👆 🥰 ⚒, 💸, ✅ 👈 👆 🤝 ☑ 💵 ⚖️ 💳, ✅ 👈 👆 🈚 ☑, ✅ 👈 ✔ ✔️ ☑ 🏬, ♒️.
-
-✋️ ⤴️, ✋️ 👆 🚫 ✔️ 👆 🍔, 👆 👷 ⏮️ 🏧 "🔛 ⏸" ⏸, ↩️ 👆 ✔️ ⌛ 👶 👆 🍔 🔜.
-
-✋️ 👆 🚶 ↖️ ⚪️➡️ ⏲ & 🧎 🏓 ⏮️ 🔢 👆 🔄, 👆 💪 🎛 👶 👆 🙋 👆 🥰, & "👷" 👶 👶 🔛 👈. ⤴️ 👆 🔄 🔨 🕳 📶 "😌" 😏 ⏮️ 👆 🥰 👶.
-
-⤴️ 🏧 👶 💬 "👤 🏁 ⏮️ 🔨 🍔" 🚮 👆 🔢 🔛 ⏲ 🖥, ✋️ 👆 🚫 🦘 💖 😜 ⏪ 🕐❔ 🖥 🔢 🔀 👆 🔄 🔢. 👆 💭 🙅♂ 1️⃣ 🔜 📎 👆 🍔 ↩️ 👆 ✔️ 🔢 👆 🔄, & 👫 ✔️ 👫.
-
-👆 ⌛ 👆 🥰 🏁 📖 (🏁 ⏮️ 👷 👶 / 📋 ➖ 🛠️ 👶), 😀 🖐 & 💬 👈 👆 🔜 🍔 ⏸.
-
-⤴️ 👆 🚶 ⏲ 👶, ▶️ 📋 👈 🔜 🏁 👶, ⚒ 🍔, 💬 👏 & ✊ 👫 🏓. 👈 🏁 👈 🔁 / 📋 🔗 ⏮️ ⏲ ⏹. 👈 🔄, ✍ 🆕 📋, "🍴 🍔" 👶 👶, ✋️ ⏮️ 1️⃣ "🤚 🍔" 🏁 ⏹.
-
-### 🔗 🍔
-
-🔜 ➡️ 🌈 👫 ➖🚫 🚫 "🛠️ 🍔", ✋️ "🔗 🍔".
-
-👆 🚶 ⏮️ 👆 🥰 🤚 🔗 ⏩ 🥕.
-
-👆 🧍 ⏸ ⏪ 📚 (➡️ 💬 8️⃣) 🏧 👈 🎏 🕰 🍳 ✊ ✔ ⚪️➡️ 👫👫 🚪 👆.
-
-👱 ⏭ 👆 ⌛ 👫 🍔 🔜 ⏭ 🍂 ⏲ ↩️ 🔠 8️⃣ 🏧 🚶 & 🏗 🍔 ▶️️ ↖️ ⏭ 💆♂ ⏭ ✔.
-
-
-
-⤴️ ⚫️ 😒 👆 🔄, 👆 🥉 👆 ✔ 2️⃣ 📶 🎀 🍔 👆 🥰 & 👆.
-
-👆 💸 👶.
-
-
-
-🏧 🚶 👨🍳.
-
-👆 ⌛, 🧍 🚪 ⏲ 👶, 👈 🙅♂ 1️⃣ 🙆 ✊ 👆 🍔 ⏭ 👆, 📤 🙅♂ 🔢 🔄.
-
-
-
-👆 & 👆 🥰 😩 🚫 ➡️ 🙆 🤚 🚪 👆 & ✊ 👆 🍔 🕐❔ 👫 🛬, 👆 🚫🔜 💸 🙋 👆 🥰. 👶
-
-👉 "🔁" 👷, 👆 "🔁" ⏮️ 🏧/🍳 👶 👶. 👆 ✔️ ⌛ 👶 & 📤 ☑ 🙍 👈 🏧/🍳 👶 👶 🏁 🍔 & 🤝 👫 👆, ⚖️ ⏪, 👱 🙆 💪 ✊ 👫.
-
-
-
-⤴️ 👆 🏧/🍳 👶 👶 😒 👟 🔙 ⏮️ 👆 🍔, ⏮️ 📏 🕰 ⌛ 👶 📤 🚪 ⏲.
-
-
-
-👆 ✊ 👆 🍔 & 🚶 🏓 ⏮️ 👆 🥰.
-
-👆 🍴 👫, & 👆 🔨. ⏹
-
-
-
-📤 🚫 🌅 💬 ⚖️ 😏 🌅 🕰 💸 ⌛ 👶 🚪 ⏲. 👶
-
-/// info
-
-🌹 🖼 👯 🍏. 👶
-
-///
-
----
-
-👉 😐 🔗 🍔, 👆 💻 / 📋 👶 ⏮️ 2️⃣ 🕹 (👆 & 👆 🥰), 👯♂️ ⌛ 👶 & 💡 👫 🙋 👶 "⌛ 🔛 ⏲" 👶 📏 🕰.
-
-⏩ 🥕 🏪 ✔️ 8️⃣ 🕹 (🏧/🍳). ⏪ 🛠️ 🍔 🏪 💪 ✔️ ✔️ 🕴 2️⃣ (1️⃣ 🏧 & 1️⃣ 🍳).
-
-✋️, 🏁 💡 🚫 🏆. 👶
-
----
-
-👉 🔜 🔗 🌓 📖 🍔. 👶
-
-🌅 "🎰 👨❤👨" 🖼 👉, 🌈 🏦.
-
-🆙 ⏳, 🏆 🏦 ✔️ 💗 🏧 👶 👶 👶 👶 👶 👶 👶 👶 & 🦏 ⏸ 👶 👶 👶 👶 👶 👶 👶 👶.
-
-🌐 🏧 🔨 🌐 👷 ⏮️ 1️⃣ 👩💻 ⏮️ 🎏 👶 👶 👶.
-
-& 👆 ✔️ ⌛ 👶 ⏸ 📏 🕰 ⚖️ 👆 💸 👆 🔄.
-
-👆 🎲 🚫🔜 💚 ✊ 👆 🥰 👶 ⏮️ 👆 👷 🏦 👶.
-
-### 🍔 🏁
-
-👉 😐 "⏩ 🥕 🍔 ⏮️ 👆 🥰", 📤 📚 ⌛ 👶, ⚫️ ⚒ 📚 🌅 🔑 ✔️ 🛠️ ⚙️ ⏸ 👶 👶.
-
-👉 💼 🌅 🕸 🈸.
-
-📚, 📚 👩💻, ✋️ 👆 💽 ⌛ 👶 👫 🚫--👍 🔗 📨 👫 📨.
-
-& ⤴️ ⌛ 👶 🔄 📨 👟 🔙.
-
-👉 "⌛" 👶 ⚖ ⏲, ✋️, ⚖ ⚫️ 🌐, ⚫️ 📚 ⌛ 🔚.
-
-👈 ⚫️❔ ⚫️ ⚒ 📚 🔑 ⚙️ 🔁 ⏸ 👶 👶 📟 🕸 🔗.
-
-👉 😇 🔀 ⚫️❔ ⚒ ✳ 🌟 (✋️ ✳ 🚫 🔗) & 👈 💪 🚶 🛠️ 🇪🇸.
-
-& 👈 🎏 🎚 🎭 👆 🤚 ⏮️ **FastAPI**.
-
-& 👆 💪 ✔️ 🔁 & 🔀 🎏 🕰, 👆 🤚 ↕ 🎭 🌘 🌅 💯 ✳ 🛠️ & 🔛 🇷🇪 ⏮️ 🚶, ❔ ✍ 🇪🇸 🔐 🅱 (🌐 👏 💃).
-
-### 🛠️ 👍 🌘 🔁 ❓
-
-😆 ❗ 👈 🚫 🛐 📖.
-
-🛠️ 🎏 🌘 🔁. & ⚫️ 👻 🔛 **🎯** 😐 👈 🔌 📚 ⌛. ↩️ 👈, ⚫️ 🛎 📚 👍 🌘 🔁 🕸 🈸 🛠️. ✋️ 🚫 🌐.
-
-, ⚖ 👈 👅, 🌈 📄 📏 📖:
-
-> 👆 ✔️ 🧹 🦏, 💩 🏠.
-
-*😆, 👈 🎂 📖*.
-
----
-
-📤 🙅♂ ⌛ 👶 🙆, 📚 👷 🔨, 🔛 💗 🥉 🏠.
-
-👆 💪 ✔️ 🔄 🍔 🖼, 🥇 🏠 🧖♂, ⤴️ 👨🍳, ✋️ 👆 🚫 ⌛ 👶 🕳, 🧹 & 🧹, 🔄 🚫🔜 📉 🕳.
-
-⚫️ 🔜 ✊ 🎏 💸 🕰 🏁 ⏮️ ⚖️ 🍵 🔄 (🛠️) & 👆 🔜 ✔️ ⌛ 🎏 💸 👷.
-
-✋️ 👉 💼, 🚥 👆 💪 ✊️ 8️⃣ 👰-🏧/🍳/🔜-🧹, & 🔠 1️⃣ 👫 (➕ 👆) 💪 ✊ 🏒 🏠 🧹 ⚫️, 👆 💪 🌐 👷 **🔗**, ⏮️ ➕ ℹ, & 🏁 🌅 🔜.
-
-👉 😐, 🔠 1️⃣ 🧹 (🔌 👆) 🔜 🕹, 🤸 👫 🍕 👨🏭.
-
-& 🏆 🛠️ 🕰 ✊ ☑ 👷 (↩️ ⌛), & 👷 💻 ⌛ 💽, 👫 🤙 👫 ⚠ "💽 🎁".
-
----
-
-⚠ 🖼 💽 🔗 🛠️ 👜 👈 🚚 🏗 🧪 🏭.
-
-🖼:
-
-* **🎧** ⚖️ **🖼 🏭**.
-* **💻 👓**: 🖼 ✍ 💯 🔅, 🔠 🔅 ✔️ 3️⃣ 💲 / 🎨, 🏭 👈 🛎 🚚 💻 🕳 🔛 📚 🔅, 🌐 🎏 🕰.
-* **🎰 🏫**: ⚫️ 🛎 🚚 📚 "✖" & "🖼" ✖. 💭 🦏 📋 ⏮️ 🔢 & ✖ 🌐 👫 👯♂️ 🎏 🕰.
-* **⏬ 🏫**: 👉 🎧-🏑 🎰 🏫,, 🎏 ✔. ⚫️ 👈 📤 🚫 👁 📋 🔢 ✖, ✋️ 🦏 ⚒ 👫, & 📚 💼, 👆 ⚙️ 🎁 🕹 🏗 & / ⚖️ ⚙️ 👈 🏷.
-
-### 🛠️ ➕ 🔁: 🕸 ➕ 🎰 🏫
-
-⏮️ **FastAPI** 👆 💪 ✊ 📈 🛠️ 👈 📶 ⚠ 🕸 🛠️ (🎏 👑 🧲 ✳).
-
-✋️ 👆 💪 🐄 💰 🔁 & 💾 (✔️ 💗 🛠️ 🏃♂ 🔗) **💽 🎁** ⚖ 💖 👈 🎰 🏫 ⚙️.
-
-👈, ➕ 🙅 👐 👈 🐍 👑 🇪🇸 **💽 🧪**, 🎰 🏫 & ✴️ ⏬ 🏫, ⚒ FastAPI 📶 👍 🏏 💽 🧪 / 🎰 🏫 🕸 🔗 & 🈸 (👪 📚 🎏).
-
-👀 ❔ 🏆 👉 🔁 🏭 👀 📄 🔃 [🛠️](deployment/index.md){.internal-link target=_blank}.
-
-## `async` & `await`
-
-🏛 ⏬ 🐍 ✔️ 📶 🏋️ 🌌 🔬 🔁 📟. 👉 ⚒ ⚫️ 👀 💖 😐 "🔁" 📟 & "⌛" 👆 ▶️️ 🙍.
-
-🕐❔ 📤 🛠️ 👈 🔜 🚚 ⌛ ⏭ 🤝 🏁 & ✔️ 🐕🦺 👉 🆕 🐍 ⚒, 👆 💪 📟 ⚫️ 💖:
-
-```Python
-burgers = await get_burgers(2)
-```
-
-🔑 📥 `await`. ⚫️ 💬 🐍 👈 ⚫️ ✔️ ⌛ ⏸ `get_burgers(2)` 🏁 🔨 🚮 👜 👶 ⏭ ♻ 🏁 `burgers`. ⏮️ 👈, 🐍 🔜 💭 👈 ⚫️ 💪 🚶 & 🕳 🙆 👶 👶 👐 (💖 📨 ➕1️⃣ 📨).
-
-`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`, 🐍 💭 👈, 🔘 👈 🔢, ⚫️ ✔️ 🤔 `await` 🧬, & 👈 ⚫️ 💪 "⏸" ⏸ 🛠️ 👈 🔢 & 🚶 🕳 🙆 👶 ⏭ 👟 🔙.
-
-🕐❔ 👆 💚 🤙 `async def` 🔢, 👆 ✔️ "⌛" ⚫️. , 👉 🏆 🚫 👷:
-
-```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 🔜 💭 ❔ ▶️️ 👜.
-
-✋️ 🚥 👆 💚 ⚙️ `async` / `await` 🍵 FastAPI, 👆 💪 ⚫️ 👍.
-
-### ✍ 👆 👍 🔁 📟
-
-💃 (& **FastAPI**) ⚓️ 🔛 AnyIO, ❔ ⚒ ⚫️ 🔗 ⏮️ 👯♂️ 🐍 🐩 🗃 ✳ & 🎻.
-
-🎯, 👆 💪 🔗 ⚙️ AnyIO 👆 🏧 🛠️ ⚙️ 💼 👈 🚚 🌅 🏧 ⚓ 👆 👍 📟.
-
-& 🚥 👆 🚫 ⚙️ FastAPI, 👆 💪 ✍ 👆 👍 🔁 🈸 ⏮️ AnyIO 🏆 🔗 & 🤚 🚮 💰 (✅ *📊 🛠️*).
-
-### 🎏 📨 🔁 📟
-
-👉 👗 ⚙️ `async` & `await` 📶 🆕 🇪🇸.
-
-✋️ ⚫️ ⚒ 👷 ⏮️ 🔁 📟 📚 ⏩.
-
-👉 🎏 ❕ (⚖️ 🌖 🌓) 🔌 ⏳ 🏛 ⏬ 🕸 (🖥 & ✳).
-
-✋️ ⏭ 👈, 🚚 🔁 📟 🌖 🏗 & ⚠.
-
-⏮️ ⏬ 🐍, 👆 💪 ✔️ ⚙️ 🧵 ⚖️ 🐁. ✋️ 📟 🌌 🌖 🏗 🤔, ℹ, & 💭 🔃.
-
-⏮️ ⏬ ✳ / 🖥 🕸, 👆 🔜 ✔️ ⚙️ "⏲". ❔ ↘️ "⏲ 🔥😈".
-
-## 🔁
-
-**🔁** 📶 🎀 ⚖ 👜 📨 `async def` 🔢. 🐍 💭 👈 ⚫️ 🕳 💖 🔢 👈 ⚫️ 💪 ▶️ & 👈 ⚫️ 🔜 🔚 ☝, ✋️ 👈 ⚫️ 5️⃣📆 ⏸ ⏸ 🔘 💁♂️, 🕐❔ 📤 `await` 🔘 ⚫️.
-
-✋️ 🌐 👉 🛠️ ⚙️ 🔁 📟 ⏮️ `async` & `await` 📚 🕰 🔬 ⚙️ "🔁". ⚫️ ⭐ 👑 🔑 ⚒ 🚶, "🔁".
-
-## 🏁
-
-➡️ 👀 🎏 🔤 ⚪️➡️ 🔛:
-
-> 🏛 ⏬ 🐍 ✔️ 🐕🦺 **"🔁 📟"** ⚙️ 🕳 🤙 **"🔁"**, ⏮️ **`async` & `await`** ❕.
-
-👈 🔜 ⚒ 🌅 🔑 🔜. 👶
-
-🌐 👈 ⚫️❔ 🏋️ FastAPI (🔘 💃) & ⚫️❔ ⚒ ⚫️ ✔️ ✅ 🎆 🎭.
-
-## 📶 📡 ℹ
-
-/// warning
-
-👆 💪 🎲 🚶 👉.
-
-👉 📶 📡 ℹ ❔ **FastAPI** 👷 🔘.
-
-🚥 👆 ✔️ 📡 💡 (🈶-🏋, 🧵, 🍫, ♒️.) & 😟 🔃 ❔ FastAPI 🍵 `async def` 🆚 😐 `def`, 🚶 ⤴️.
-
-///
-
-### ➡ 🛠️ 🔢
-
-🕐❔ 👆 📣 *➡ 🛠️ 🔢* ⏮️ 😐 `def` ↩️ `async def`, ⚫️ 🏃 🔢 🧵 👈 ⤴️ ⌛, ↩️ ➖ 🤙 🔗 (⚫️ 🔜 🍫 💽).
-
-🚥 👆 👟 ⚪️➡️ ➕1️⃣ 🔁 🛠️ 👈 🔨 🚫 👷 🌌 🔬 🔛 & 👆 ⚙️ ⚖ 🙃 📊-🕴 *➡ 🛠️ 🔢* ⏮️ ✅ `def` 🤪 🎭 📈 (🔃 1️⃣0️⃣0️⃣ 💓), 🙏 🗒 👈 **FastAPI** ⭐ 🔜 🔄. 👫 💼, ⚫️ 👻 ⚙️ `async def` 🚥 👆 *➡ 🛠️ 🔢* ⚙️ 📟 👈 🎭 🚧 👤/🅾.
-
-, 👯♂️ ⚠, 🤞 👈 **FastAPI** 🔜 [⏩](index.md#_15){.internal-link target=_blank} 🌘 (⚖️ 🌘 ⭐) 👆 ⏮️ 🛠️.
-
-### 🔗
-
-🎏 ✔ [🔗](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/em/docs/benchmarks.md b/docs/em/docs/benchmarks.md
deleted file mode 100644
index 003c3f62d..000000000
--- a/docs/em/docs/benchmarks.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# 📇
-
-🔬 🇸🇲 📇 🎦 **FastAPI** 🈸 🏃♂ 🔽 Uvicorn 1️⃣ ⏩ 🐍 🛠️ 💪, 🕴 🔛 💃 & Uvicorn 👫 (⚙️ 🔘 FastAPI). (*)
-
-✋️ 🕐❔ ✅ 📇 & 🔺 👆 🔜 ✔️ 📄 🤯.
-
-## 📇 & 🚅
-
-🕐❔ 👆 ✅ 📇, ⚫️ ⚠ 👀 📚 🧰 🎏 🆎 🔬 🌓.
-
-🎯, 👀 Uvicorn, 💃 & FastAPI 🔬 👯♂️ (👪 📚 🎏 🧰).
-
-🙅 ⚠ ❎ 🧰, 👍 🎭 ⚫️ 🔜 🤚. & 🏆 📇 🚫 💯 🌖 ⚒ 🚚 🧰.
-
-🔗 💖:
-
-* **Uvicorn**: 🔫 💽
- * **💃**: (⚙️ Uvicorn) 🕸 🕸
- * **FastAPI**: (⚙️ 💃) 🛠️ 🕸 ⏮️ 📚 🌖 ⚒ 🏗 🔗, ⏮️ 💽 🔬, ♒️.
-
-* **Uvicorn**:
- * 🔜 ✔️ 🏆 🎭, ⚫️ 🚫 ✔️ 🌅 ➕ 📟 ↖️ ⚪️➡️ 💽 ⚫️.
- * 👆 🚫🔜 ✍ 🈸 Uvicorn 🔗. 👈 🔜 ⛓ 👈 👆 📟 🔜 ✔️ 🔌 🌖 ⚖️ 🌘, 🌘, 🌐 📟 🚚 💃 (⚖️ **FastAPI**). & 🚥 👆 👈, 👆 🏁 🈸 🔜 ✔️ 🎏 🌥 ✔️ ⚙️ 🛠️ & 📉 👆 📱 📟 & 🐛.
- * 🚥 👆 ⚖ Uvicorn, 🔬 ⚫️ 🛡 👸, Hypercorn, ✳, ♒️. 🈸 💽.
-* **💃**:
- * 🔜 ✔️ ⏭ 🏆 🎭, ⏮️ Uvicorn. 👐, 💃 ⚙️ Uvicorn 🏃. , ⚫️ 🎲 💪 🕴 🤚 "🐌" 🌘 Uvicorn ✔️ 🛠️ 🌅 📟.
- * ✋️ ⚫️ 🚚 👆 🧰 🏗 🙅 🕸 🈸, ⏮️ 🕹 ⚓️ 🔛 ➡, ♒️.
- * 🚥 👆 ⚖ 💃, 🔬 ⚫️ 🛡 🤣, 🏺, ✳, ♒️. 🕸 🛠️ (⚖️ 🕸).
-* **FastAPI**:
- * 🎏 🌌 👈 💃 ⚙️ Uvicorn & 🚫🔜 ⏩ 🌘 ⚫️, **FastAPI** ⚙️ 💃, ⚫️ 🚫🔜 ⏩ 🌘 ⚫️.
- * FastAPI 🚚 🌅 ⚒ 🔛 🔝 💃. ⚒ 👈 👆 🌖 🕧 💪 🕐❔ 🏗 🔗, 💖 💽 🔬 & 🛠️. & ⚙️ ⚫️, 👆 🤚 🏧 🧾 🆓 (🏧 🧾 🚫 🚮 🌥 🏃♂ 🈸, ⚫️ 🏗 🔛 🕴).
- * 🚥 👆 🚫 ⚙️ FastAPI & ⚙️ 💃 🔗 (⚖️ ➕1️⃣ 🧰, 💖 🤣, 🏺, 🆘, ♒️) 👆 🔜 ✔️ 🛠️ 🌐 💽 🔬 & 🛠️ 👆. , 👆 🏁 🈸 🔜 ✔️ 🎏 🌥 🚥 ⚫️ 🏗 ⚙️ FastAPI. & 📚 💼, 👉 💽 🔬 & 🛠️ 🦏 💸 📟 ✍ 🈸.
- * , ⚙️ FastAPI 👆 ♻ 🛠️ 🕰, 🐛, ⏸ 📟, & 👆 🔜 🎲 🤚 🎏 🎭 (⚖️ 👍) 👆 🔜 🚥 👆 🚫 ⚙️ ⚫️ (👆 🔜 ✔️ 🛠️ ⚫️ 🌐 👆 📟).
- * 🚥 👆 ⚖ FastAPI, 🔬 ⚫️ 🛡 🕸 🈸 🛠️ (⚖️ ⚒ 🧰) 👈 🚚 💽 🔬, 🛠️ & 🧾, 💖 🏺-apispec, NestJS, ♨, ♒️. 🛠️ ⏮️ 🛠️ 🏧 💽 🔬, 🛠️ & 🧾.
diff --git a/docs/em/docs/deployment/concepts.md b/docs/em/docs/deployment/concepts.md
deleted file mode 100644
index bbb017277..000000000
--- a/docs/em/docs/deployment/concepts.md
+++ /dev/null
@@ -1,323 +0,0 @@
-# 🛠️ 🔧
-
-🕐❔ 🛠️ **FastAPI** 🈸, ⚖️ 🤙, 🙆 🆎 🕸 🛠️, 📤 📚 🔧 👈 👆 🎲 💅 🔃, & ⚙️ 👫 👆 💪 🔎 **🏆 ☑** 🌌 **🛠️ 👆 🈸**.
-
-⚠ 🔧:
-
-* 💂♂ - 🇺🇸🔍
-* 🏃♂ 🔛 🕴
-* ⏏
-* 🧬 (🔢 🛠️ 🏃)
-* 💾
-* ⏮️ 🔁 ⏭ ▶️
-
-👥 🔜 👀 ❔ 👫 🔜 📉 **🛠️**.
-
-🔚, 🏆 🎯 💪 **🍦 👆 🛠️ 👩💻** 🌌 👈 **🔐**, **❎ 📉**, & ⚙️ **📊 ℹ** (🖼 🛰 💽/🕹 🎰) ♻ 💪. 👶
-
-👤 🔜 💬 👆 🍖 🌖 🔃 👫 **🔧** 📥, & 👈 🔜 🤞 🤝 👆 **🤔** 👆 🔜 💪 💭 ❔ 🛠️ 👆 🛠️ 📶 🎏 🌐, 🎲 **🔮** 🕐 👈 🚫 🔀.
-
-🤔 👫 🔧, 👆 🔜 💪 **🔬 & 🔧** 🏆 🌌 🛠️ **👆 👍 🔗**.
-
-⏭ 📃, 👤 🔜 🤝 👆 🌅 **🧱 🍮** 🛠️ FastAPI 🈸.
-
-✋️ 🔜, ➡️ ✅ 👉 ⚠ **⚛ 💭**. 👫 🔧 ✔ 🙆 🎏 🆎 🕸 🛠️. 👶
-
-## 💂♂ - 🇺🇸🔍
-
-[⏮️ 📃 🔃 🇺🇸🔍](https.md){.internal-link target=_blank} 👥 🇭🇲 🔃 ❔ 🇺🇸🔍 🚚 🔐 👆 🛠️.
-
-👥 👀 👈 🇺🇸🔍 🛎 🚚 🦲 **🔢** 👆 🈸 💽, **🤝 ❎ 🗳**.
-
-& 📤 ✔️ 🕳 🈚 **♻ 🇺🇸🔍 📄**, ⚫️ 💪 🎏 🦲 ⚖️ ⚫️ 💪 🕳 🎏.
-
-### 🖼 🧰 🇺🇸🔍
-
-🧰 👆 💪 ⚙️ 🤝 ❎ 🗳:
-
-* Traefik
- * 🔁 🍵 📄 🔕 👶
-* 📥
- * 🔁 🍵 📄 🔕 👶
-* 👌
- * ⏮️ 🔢 🦲 💖 Certbot 📄 🔕
-* ✳
- * ⏮️ 🔢 🦲 💖 Certbot 📄 🔕
-* Kubernetes ⏮️ 🚧 🕹 💖 👌
- * ⏮️ 🔢 🦲 💖 🛂-👨💼 📄 🔕
-* 🍵 🔘 ☁ 🐕🦺 🍕 👫 🐕🦺 (✍ 🔛 👶)
-
-➕1️⃣ 🎛 👈 👆 💪 ⚙️ **☁ 🐕🦺** 👈 🔨 🌖 👷 ✅ ⚒ 🆙 🇺🇸🔍. ⚫️ 💪 ✔️ 🚫 ⚖️ 🈚 👆 🌅, ♒️. ✋️ 👈 💼, 👆 🚫🔜 ✔️ ⚒ 🆙 🤝 ❎ 🗳 👆.
-
-👤 🔜 🎦 👆 🧱 🖼 ⏭ 📃.
-
----
-
-⤴️ ⏭ 🔧 🤔 🌐 🔃 📋 🏃 👆 ☑ 🛠️ (✅ Uvicorn).
-
-## 📋 & 🛠️
-
-👥 🔜 💬 📚 🔃 🏃 "**🛠️**", ⚫️ ⚠ ✔️ ☯ 🔃 ⚫️❔ ⚫️ ⛓, & ⚫️❔ 🔺 ⏮️ 🔤 "**📋**".
-
-### ⚫️❔ 📋
-
-🔤 **📋** 🛎 ⚙️ 🔬 📚 👜:
-
-* **📟** 👈 👆 ✍, **🐍 📁**.
-* **📁** 👈 💪 **🛠️** 🏃♂ ⚙️, 🖼: `python`, `python.exe` ⚖️ `uvicorn`.
-* 🎯 📋 ⏪ ⚫️ **🏃♂** 🔛 🏗 ⚙️, ⚙️ 💽, & ♻ 👜 🔛 💾. 👉 🤙 **🛠️**.
-
-### ⚫️❔ 🛠️
-
-🔤 **🛠️** 🛎 ⚙️ 🌖 🎯 🌌, 🕴 🔗 👜 👈 🏃 🏃♂ ⚙️ (💖 🏁 ☝ 🔛):
-
-* 🎯 📋 ⏪ ⚫️ **🏃♂** 🔛 🏃♂ ⚙️.
- * 👉 🚫 🔗 📁, 🚫 📟, ⚫️ 🔗 **🎯** 👜 👈 ➖ **🛠️** & 🔄 🏃♂ ⚙️.
-* 🙆 📋, 🙆 📟, **💪 🕴 👜** 🕐❔ ⚫️ ➖ **🛠️**. , 🕐❔ 📤 **🛠️ 🏃**.
-* 🛠️ 💪 **❎** (⚖️ "💥") 👆, ⚖️ 🏃♂ ⚙️. 👈 ☝, ⚫️ ⛔️ 🏃/➖ 🛠️, & ⚫️ 💪 **🙅♂ 📏 👜**.
-* 🔠 🈸 👈 👆 ✔️ 🏃 🔛 👆 💻 ✔️ 🛠️ ⛅ ⚫️, 🔠 🏃♂ 📋, 🔠 🚪, ♒️. & 📤 🛎 📚 🛠️ 🏃 **🎏 🕰** ⏪ 💻 🔛.
-* 📤 💪 **💗 🛠️** **🎏 📋** 🏃 🎏 🕰.
-
-🚥 👆 ✅ 👅 "📋 👨💼" ⚖️ "⚙️ 🖥" (⚖️ 🎏 🧰) 👆 🏃♂ ⚙️, 👆 🔜 💪 👀 📚 👈 🛠️ 🏃♂.
-
-& , 🖼, 👆 🔜 🎲 👀 👈 📤 💗 🛠️ 🏃 🎏 🖥 📋 (🦎, 💄, 📐, ♒️). 👫 🛎 🏃 1️⃣ 🛠️ 📍 📑, ➕ 🎏 ➕ 🛠️.
-
-
-
----
-
-🔜 👈 👥 💭 🔺 🖖 ⚖ **🛠️** & **📋**, ➡️ 😣 💬 🔃 🛠️.
-
-## 🏃♂ 🔛 🕴
-
-🌅 💼, 🕐❔ 👆 ✍ 🕸 🛠️, 👆 💚 ⚫️ **🕧 🏃♂**, ➡, 👈 👆 👩💻 💪 🕧 🔐 ⚫️. 👉 ↗️, 🚥 👆 ✔️ 🎯 🤔 ⚫️❔ 👆 💚 ⚫️ 🏃 🕴 🎯 ⚠, ✋️ 🌅 🕰 👆 💚 ⚫️ 🕧 🏃♂ & **💪**.
-
-### 🛰 💽
-
-🕐❔ 👆 ⚒ 🆙 🛰 💽 (☁ 💽, 🕹 🎰, ♒️.) 🙅 👜 👆 💪 🏃 Uvicorn (⚖️ 🎏) ❎, 🎏 🌌 👆 🕐❔ 🛠️ 🌐.
-
-& ⚫️ 🔜 👷 & 🔜 ⚠ **⏮️ 🛠️**.
-
-✋️ 🚥 👆 🔗 💽 💸, **🏃♂ 🛠️** 🔜 🎲 ☠️.
-
-& 🚥 💽 ⏏ (🖼 ⏮️ ℹ, ⚖️ 🛠️ ⚪️➡️ ☁ 🐕🦺) 👆 🎲 **🏆 🚫 👀 ⚫️**. & ↩️ 👈, 👆 🏆 🚫 💭 👈 👆 ✔️ ⏏ 🛠️ ❎. , 👆 🛠️ 🔜 🚧 ☠️. 👶
-
-### 🏃 🔁 🔛 🕴
-
-🏢, 👆 🔜 🎲 💚 💽 📋 (✅ Uvicorn) ▶️ 🔁 🔛 💽 🕴, & 🍵 💪 🙆 **🗿 🏥**, ✔️ 🛠️ 🕧 🏃 ⏮️ 👆 🛠️ (✅ Uvicorn 🏃♂ 👆 FastAPI 📱).
-
-### 🎏 📋
-
-🏆 👉, 👆 🔜 🛎 ✔️ **🎏 📋** 👈 🔜 ⚒ 💭 👆 🈸 🏃 🔛 🕴. & 📚 💼, ⚫️ 🔜 ⚒ 💭 🎏 🦲 ⚖️ 🈸 🏃, 🖼, 💽.
-
-### 🖼 🧰 🏃 🕴
-
-🖼 🧰 👈 💪 👉 👨🏭:
-
-* ☁
-* Kubernetes
-* ☁ ✍
-* ☁ 🐝 📳
-* ✳
-* 👨💻
-* 🍵 🔘 ☁ 🐕🦺 🍕 👫 🐕🦺
-* 🎏...
-
-👤 🔜 🤝 👆 🌅 🧱 🖼 ⏭ 📃.
-
-## ⏏
-
-🎏 ⚒ 💭 👆 🈸 🏃 🔛 🕴, 👆 🎲 💚 ⚒ 💭 ⚫️ **⏏** ⏮️ ❌.
-
-### 👥 ⚒ ❌
-
-👥, 🗿, ⚒ **❌**, 🌐 🕰. 🖥 🌖 *🕧* ✔️ **🐛** 🕵♂ 🎏 🥉. 👶
-
-& 👥 👩💻 🚧 📉 📟 👥 🔎 👈 🐛 & 👥 🛠️ 🆕 ⚒ (🎲 ❎ 🆕 🐛 💁♂️ 👶).
-
-### 🤪 ❌ 🔁 🍵
-
-🕐❔ 🏗 🕸 🔗 ⏮️ FastAPI, 🚥 📤 ❌ 👆 📟, FastAPI 🔜 🛎 🔌 ⚫️ 👁 📨 👈 ⏲ ❌. 🛡
-
-👩💻 🔜 🤚 **5️⃣0️⃣0️⃣ 🔗 💽 ❌** 👈 📨, ✋️ 🈸 🔜 😣 👷 ⏭ 📨 ↩️ 💥 🍕.
-
-### 🦏 ❌ - 💥
-
-👐, 📤 5️⃣📆 💼 🌐❔ 👥 ✍ 📟 👈 **💥 🎂 🈸** ⚒ Uvicorn & 🐍 💥. 👶
-
-& , 👆 🔜 🎲 🚫 💚 🈸 🚧 ☠️ ↩️ 📤 ❌ 1️⃣ 🥉, 👆 🎲 💚 ⚫️ **😣 🏃** 🌘 *➡ 🛠️* 👈 🚫 💔.
-
-### ⏏ ⏮️ 💥
-
-✋️ 👈 💼 ⏮️ 🤙 👎 ❌ 👈 💥 🏃♂ **🛠️**, 👆 🔜 💚 🔢 🦲 👈 🈚 **🔁** 🛠️, 🌘 👩❤👨 🕰...
-
-/// tip
-
-...👐 🚥 🎂 🈸 **💥 ⏪** ⚫️ 🎲 🚫 ⚒ 🔑 🚧 🔁 ⚫️ ♾. ✋️ 📚 💼, 👆 🔜 🎲 👀 ⚫️ ⏮️ 🛠️, ⚖️ 🌘 ▶️️ ⏮️ 🛠️.
-
-➡️ 🎯 🔛 👑 💼, 🌐❔ ⚫️ 💪 💥 🍕 🎯 💼 **🔮**, & ⚫️ ⚒ 🔑 ⏏ ⚫️.
-
-///
-
-👆 🔜 🎲 💚 ✔️ 👜 🈚 🔁 👆 🈸 **🔢 🦲**, ↩️ 👈 ☝, 🎏 🈸 ⏮️ Uvicorn & 🐍 ⏪ 💥, 📤 🕳 🎏 📟 🎏 📱 👈 💪 🕳 🔃 ⚫️.
-
-### 🖼 🧰 ⏏ 🔁
-
-🏆 💼, 🎏 🧰 👈 ⚙️ **🏃 📋 🔛 🕴** ⚙️ 🍵 🏧 **⏏**.
-
-🖼, 👉 💪 🍵:
-
-* ☁
-* Kubernetes
-* ☁ ✍
-* ☁ 🐝 📳
-* ✳
-* 👨💻
-* 🍵 🔘 ☁ 🐕🦺 🍕 👫 🐕🦺
-* 🎏...
-
-## 🧬 - 🛠️ & 💾
-
-⏮️ FastAPI 🈸, ⚙️ 💽 📋 💖 Uvicorn, 🏃♂ ⚫️ 🕐 **1️⃣ 🛠️** 💪 🍦 💗 👩💻 🔁.
-
-✋️ 📚 💼, 👆 🔜 💚 🏃 📚 👨🏭 🛠️ 🎏 🕰.
-
-### 💗 🛠️ - 👨🏭
-
-🚥 👆 ✔️ 🌅 👩💻 🌘 ⚫️❔ 👁 🛠️ 💪 🍵 (🖼 🚥 🕹 🎰 🚫 💁♂️ 🦏) & 👆 ✔️ **💗 🐚** 💽 💽, ⤴️ 👆 💪 ✔️ **💗 🛠️** 🏃♂ ⏮️ 🎏 🈸 🎏 🕰, & 📎 🌐 📨 👪 👫.
-
-🕐❔ 👆 🏃 **💗 🛠️** 🎏 🛠️ 📋, 👫 🛎 🤙 **👨🏭**.
-
-### 👨🏭 🛠️ & ⛴
-
-💭 ⚪️➡️ 🩺 [🔃 🇺🇸🔍](https.md){.internal-link target=_blank} 👈 🕴 1️⃣ 🛠️ 💪 👂 🔛 1️⃣ 🌀 ⛴ & 📢 📢 💽 ❓
-
-👉 ☑.
-
-, 💪 ✔️ **💗 🛠️** 🎏 🕰, 📤 ✔️ **👁 🛠️ 👂 🔛 ⛴** 👈 ⤴️ 📶 📻 🔠 👨🏭 🛠️ 🌌.
-
-### 💾 📍 🛠️
-
-🔜, 🕐❔ 📋 📐 👜 💾, 🖼, 🎰 🏫 🏷 🔢, ⚖️ 🎚 ⭕ 📁 🔢, 🌐 👈 **🍴 👄 💾 (💾)** 💽.
-
-& 💗 🛠️ 🛎 **🚫 💰 🙆 💾**. 👉 ⛓ 👈 🔠 🏃 🛠️ ✔️ 🚮 👍 👜, 🔢, & 💾. & 🚥 👆 😩 ⭕ 💸 💾 👆 📟, **🔠 🛠️** 🔜 🍴 🌓 💸 💾.
-
-### 💽 💾
-
-🖼, 🚥 👆 📟 📐 🎰 🏫 🏷 ⏮️ **1️⃣ 💾 📐**, 🕐❔ 👆 🏃 1️⃣ 🛠️ ⏮️ 👆 🛠️, ⚫️ 🔜 🍴 🌘 1️⃣ 💾 💾. & 🚥 👆 ▶️ **4️⃣ 🛠️** (4️⃣ 👨🏭), 🔠 🔜 🍴 1️⃣ 💾 💾. 🌐, 👆 🛠️ 🔜 🍴 **4️⃣ 💾 💾**.
-
-& 🚥 👆 🛰 💽 ⚖️ 🕹 🎰 🕴 ✔️ 3️⃣ 💾 💾, 🔄 📐 🌅 🌘 4️⃣ 💾 💾 🔜 🤕 ⚠. 👶
-
-### 💗 🛠️ - 🖼
-
-👉 🖼, 📤 **👨💼 🛠️** 👈 ▶️ & 🎛 2️⃣ **👨🏭 🛠️**.
-
-👉 👨💼 🛠️ 🔜 🎲 1️⃣ 👂 🔛 **⛴** 📢. & ⚫️ 🔜 📶 🌐 📻 👨🏭 🛠️.
-
-👈 👨🏭 🛠️ 🔜 🕐 🏃♂ 👆 🈸, 👫 🔜 🎭 👑 📊 📨 **📨** & 📨 **📨**, & 👫 🔜 📐 🕳 👆 🚮 🔢 💾.
-
-
-
-& ↗️, 🎏 🎰 🔜 🎲 ✔️ **🎏 🛠️** 🏃 👍, ↖️ ⚪️➡️ 👆 🈸.
-
-😌 ℹ 👈 🌐 **💽 ⚙️** 🔠 🛠️ 💪 **🪀** 📚 🤭 🕰, ✋️ **💾 (💾)** 🛎 🚧 🌖 ⚖️ 🌘 **⚖**.
-
-🚥 👆 ✔️ 🛠️ 👈 🔨 ⭐ 💸 📊 🔠 🕰 & 👆 ✔️ 📚 👩💻, ⤴️ **💽 🛠️** 🔜 🎲 *⚖* (↩️ 🕧 🔜 🆙 & 🔽 🔜).
-
-### 🖼 🧬 🧰 & 🎛
-
-📤 💪 📚 🎯 🏆 👉, & 👤 🔜 💬 👆 🌅 🔃 🎯 🎛 ⏭ 📃, 🖼 🕐❔ 💬 🔃 ☁ & 📦.
-
-👑 ⚛ 🤔 👈 📤 ✔️ **👁** 🦲 🚚 **⛴** **📢 📢**. & ⤴️ ⚫️ ✔️ ✔️ 🌌 **📶** 📻 🔁 **🛠️/👨🏭**.
-
-📥 💪 🌀 & 🎛:
-
-* **🐁** 🛠️ **Uvicorn 👨🏭**
- * 🐁 🔜 **🛠️ 👨💼** 👂 🔛 **📢** & **⛴**, 🧬 🔜 ✔️ **💗 Uvicorn 👨🏭 🛠️**
-* **Uvicorn** 🛠️ **Uvicorn 👨🏭**
- * 1️⃣ Uvicorn **🛠️ 👨💼** 🔜 👂 🔛 **📢** & **⛴**, & ⚫️ 🔜 ▶️ **💗 Uvicorn 👨🏭 🛠️**
-* **Kubernetes** & 🎏 📎 **📦 ⚙️**
- * 🕳 **☁** 🧽 🔜 👂 🔛 **📢** & **⛴**. 🧬 🔜 ✔️ **💗 📦**, 🔠 ⏮️ **1️⃣ Uvicorn 🛠️** 🏃♂
-* **☁ 🐕🦺** 👈 🍵 👉 👆
- * ☁ 🐕🦺 🔜 🎲 **🍵 🧬 👆**. ⚫️ 🔜 🎲 ➡️ 👆 🔬 **🛠️ 🏃**, ⚖️ **📦 🖼** ⚙️, 🙆 💼, ⚫️ 🔜 🌅 🎲 **👁 Uvicorn 🛠️**, & ☁ 🐕🦺 🔜 🈚 🔁 ⚫️.
-
-/// tip
-
-🚫 😟 🚥 👫 🏬 🔃 **📦**, ☁, ⚖️ Kubernetes 🚫 ⚒ 📚 🔑.
-
-👤 🔜 💬 👆 🌅 🔃 📦 🖼, ☁, Kubernetes, ♒️. 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
-
-///
-
-## ⏮️ 🔁 ⏭ ▶️
-
-📤 📚 💼 🌐❔ 👆 💚 🎭 📶 **⏭ ▶️** 👆 🈸.
-
-🖼, 👆 💪 💚 🏃 **💽 🛠️**.
-
-✋️ 🌅 💼, 👆 🔜 💚 🎭 👉 🔁 🕴 **🕐**.
-
-, 👆 🔜 💚 ✔️ **👁 🛠️** 🎭 👈 **⏮️ 🔁**, ⏭ ▶️ 🈸.
-
-& 👆 🔜 ✔️ ⚒ 💭 👈 ⚫️ 👁 🛠️ 🏃 👈 ⏮️ 🔁 ** 🚥 ⏮️, 👆 ▶️ **💗 🛠️** (💗 👨🏭) 🈸 ⚫️. 🚥 👈 🔁 🏃 **💗 🛠️**, 👫 🔜 **❎** 👷 🏃♂ ⚫️ 🔛 **🔗**, & 🚥 📶 🕳 💎 💖 💽 🛠️, 👫 💪 🤕 ⚔ ⏮️ 🔠 🎏.
-
-↗️, 📤 💼 🌐❔ 📤 🙅♂ ⚠ 🏃 ⏮️ 🔁 💗 🕰, 👈 💼, ⚫️ 📚 ⏩ 🍵.
-
-/// tip
-
-, ✔️ 🤯 👈 ⚓️ 🔛 👆 🖥, 💼 👆 **5️⃣📆 🚫 💪 🙆 ⏮️ 🔁** ⏭ ▶️ 👆 🈸.
-
-👈 💼, 👆 🚫🔜 ✔️ 😟 🔃 🙆 👉. 🤷
-
-///
-
-### 🖼 ⏮️ 🔁 🎛
-
-👉 🔜 **🪀 🙇** 🔛 🌌 👆 **🛠️ 👆 ⚙️**, & ⚫️ 🔜 🎲 🔗 🌌 👆 ▶️ 📋, 🚚 ⏏, ♒️.
-
-📥 💪 💭:
-
-* "🕑 📦" Kubernetes 👈 🏃 ⏭ 👆 📱 📦
-* 🎉 ✍ 👈 🏃 ⏮️ 🔁 & ⤴️ ▶️ 👆 🈸
- * 👆 🔜 💪 🌌 ▶️/⏏ *👈* 🎉 ✍, 🔍 ❌, ♒️.
-
-/// tip
-
-👤 🔜 🤝 👆 🌅 🧱 🖼 🔨 👉 ⏮️ 📦 🔮 📃: [FastAPI 📦 - ☁](docker.md){.internal-link target=_blank}.
-
-///
-
-## ℹ 🛠️
-
-👆 💽(Ⓜ) () **ℹ**, 👆 💪 🍴 ⚖️ **⚙️**, ⏮️ 👆 📋, 📊 🕰 🔛 💽, & 💾 💾 💪.
-
-❔ 🌅 ⚙️ ℹ 👆 💚 😩/♻ ❓ ⚫️ 💪 ⏩ 💭 "🚫 🌅", ✋️ 🌌, 👆 🔜 🎲 💚 🍴 **🌅 💪 🍵 💥**.
-
-🚥 👆 💸 3️⃣ 💽 ✋️ 👆 ⚙️ 🕴 🐥 🍖 👫 💾 & 💽, 👆 🎲 **🗑 💸** 👶, & 🎲 **🗑 💽 🔦 🏋️** 👶, ♒️.
-
-👈 💼, ⚫️ 💪 👻 ✔️ 🕴 2️⃣ 💽 & ⚙️ ↕ 🌐 👫 ℹ (💽, 💾, 💾, 🕸 💿, ♒️).
-
-🔛 🎏 ✋, 🚥 👆 ✔️ 2️⃣ 💽 & 👆 ⚙️ **1️⃣0️⃣0️⃣ 💯 👫 💽 & 💾**, ☝ 1️⃣ 🛠️ 🔜 💭 🌅 💾, & 💽 🔜 ✔️ ⚙️ 💾 "💾" (❔ 💪 💯 🕰 🐌), ⚖️ **💥**. ⚖️ 1️⃣ 🛠️ 💪 💪 📊 & 🔜 ✔️ ⌛ ⏭ 💽 🆓 🔄.
-
-👉 💼, ⚫️ 🔜 👍 🤚 **1️⃣ ➕ 💽** & 🏃 🛠️ 🔛 ⚫️ 👈 👫 🌐 ✔️ **🥃 💾 & 💽 🕰**.
-
-📤 🤞 👈 🤔 👆 ✔️ **🌵** ⚙️ 👆 🛠️. 🎲 ⚫️ 🚶 🦠, ⚖️ 🎲 🎏 🐕🦺 ⚖️ 🤖 ▶️ ⚙️ ⚫️. & 👆 💪 💚 ✔️ ➕ ℹ 🔒 👈 💼.
-
-👆 💪 🚮 **❌ 🔢** 🎯, 🖼, 🕳 **🖖 5️⃣0️⃣ 💯 9️⃣0️⃣ 💯** ℹ 🛠️. ☝ 👈 📚 🎲 👑 👜 👆 🔜 💚 ⚖ & ⚙️ ⚒ 👆 🛠️.
-
-👆 💪 ⚙️ 🙅 🧰 💖 `htop` 👀 💽 & 💾 ⚙️ 👆 💽 ⚖️ 💸 ⚙️ 🔠 🛠️. ⚖️ 👆 💪 ⚙️ 🌖 🏗 ⚖ 🧰, ❔ 5️⃣📆 📎 🤭 💽, ♒️.
-
-## 🌃
-
-👆 ✔️ 👂 📥 👑 🔧 👈 👆 🔜 🎲 💪 ✔️ 🤯 🕐❔ 🤔 ❔ 🛠️ 👆 🈸:
-
-* 💂♂ - 🇺🇸🔍
-* 🏃♂ 🔛 🕴
-* ⏏
-* 🧬 (🔢 🛠️ 🏃)
-* 💾
-* ⏮️ 🔁 ⏭ ▶️
-
-🤔 👉 💭 & ❔ ✔ 👫 🔜 🤝 👆 🤔 💪 ✊ 🙆 🚫 🕐❔ 🛠️ & 🛠️ 👆 🛠️. 👶
-
-⏭ 📄, 👤 🔜 🤝 👆 🌅 🧱 🖼 💪 🎛 👆 💪 ⏩. 👶
diff --git a/docs/em/docs/deployment/docker.md b/docs/em/docs/deployment/docker.md
deleted file mode 100644
index 2152f1a0e..000000000
--- a/docs/em/docs/deployment/docker.md
+++ /dev/null
@@ -1,731 +0,0 @@
-# FastAPI 📦 - ☁
-
-🕐❔ 🛠️ FastAPI 🈸 ⚠ 🎯 🏗 **💾 📦 🖼**. ⚫️ 🛎 🔨 ⚙️ **☁**. 👆 💪 ⤴️ 🛠️ 👈 📦 🖼 1️⃣ 👩❤👨 💪 🌌.
-
-⚙️ 💾 📦 ✔️ 📚 📈 ✅ **💂♂**, **🔬**, **🦁**, & 🎏.
-
-/// tip
-
-🏃 & ⏪ 💭 👉 💩 ❓ 🦘 [`Dockerfile` 🔛 👶](#fastapi).
-
-///
-
-
-
-### 🤝 🤝 ▶️
-
-🖥 🔜 ⤴️ 🔗 ⏮️ 👈 📢 📢 🔛 **⛴ 4️⃣4️⃣3️⃣** (🇺🇸🔍 ⛴).
-
-🥇 🍕 📻 🛠️ 🔗 🖖 👩💻 & 💽 & 💭 🔐 🔑 👫 🔜 ⚙️, ♒️.
-
-
-
-👉 🔗 🖖 👩💻 & 💽 🛠️ 🤝 🔗 🤙 **🤝 🤝**.
-
-### 🤝 ⏮️ 👲 ↔
-
-**🕴 1️⃣ 🛠️** 💽 💪 👂 🔛 🎯 **⛴** 🎯 **📢 📢**. 📤 💪 🎏 🛠️ 👂 🔛 🎏 ⛴ 🎏 📢 📢, ✋️ 🕴 1️⃣ 🔠 🌀 📢 📢 & ⛴.
-
-🤝 (🇺🇸🔍) ⚙️ 🎯 ⛴ `443` 🔢. 👈 ⛴ 👥 🔜 💪.
-
-🕴 1️⃣ 🛠️ 💪 👂 🔛 👉 ⛴, 🛠️ 👈 🔜 ⚫️ 🔜 **🤝 ❎ 🗳**.
-
-🤝 ❎ 🗳 🔜 ✔️ 🔐 1️⃣ ⚖️ 🌅 **🤝 📄** (🇺🇸🔍 📄).
-
-⚙️ **👲 ↔** 🔬 🔛, 🤝 ❎ 🗳 🔜 ✅ ❔ 🤝 (🇺🇸🔍) 📄 💪 ⚫️ 🔜 ⚙️ 👉 🔗, ⚙️ 1️⃣ 👈 🏏 🆔 📈 👩💻.
-
-👉 💼, ⚫️ 🔜 ⚙️ 📄 `someapp.example.com`.
-
-
-
-👩💻 ⏪ **💙** 👨💼 👈 🏗 👈 🤝 📄 (👉 💼 ➡️ 🗜, ✋️ 👥 🔜 👀 🔃 👈 ⏪), ⚫️ 💪 **✔** 👈 📄 ☑.
-
-⤴️, ⚙️ 📄, 👩💻 & 🤝 ❎ 🗳 **💭 ❔ 🗜** 🎂 **🕸 📻**. 👉 🏁 **🤝 🤝** 🍕.
-
-⏮️ 👉, 👩💻 & 💽 ✔️ **🗜 🕸 🔗**, 👉 ⚫️❔ 🤝 🚚. & ⤴️ 👫 💪 ⚙️ 👈 🔗 ▶️ ☑ **🇺🇸🔍 📻**.
-
-& 👈 ⚫️❔ **🇺🇸🔍** , ⚫️ ✅ **🇺🇸🔍** 🔘 **🔐 🤝 🔗** ↩️ 😁 (💽) 🕸 🔗.
-
-/// tip
-
-👀 👈 🔐 📻 🔨 **🕸 🎚**, 🚫 🇺🇸🔍 🎚.
-
-///
-
-### 🇺🇸🔍 📨
-
-🔜 👈 👩💻 & 💽 (🎯 🖥 & 🤝 ❎ 🗳) ✔️ **🗜 🕸 🔗**, 👫 💪 ▶️ **🇺🇸🔍 📻**.
-
-, 👩💻 📨 **🇺🇸🔍 📨**. 👉 🇺🇸🔍 📨 🔘 🗜 🤝 🔗.
-
-
-
-### 🗜 📨
-
-🤝 ❎ 🗳 🔜 ⚙️ 🔐 ✔ **🗜 📨**, & 🔜 📶 **✅ (🗜) 🇺🇸🔍 📨** 🛠️ 🏃 🈸 (🖼 🛠️ ⏮️ Uvicorn 🏃♂ FastAPI 🈸).
-
-
-
-### 🇺🇸🔍 📨
-
-🈸 🔜 🛠️ 📨 & 📨 **✅ (💽) 🇺🇸🔍 📨** 🤝 ❎ 🗳.
-
-
-
-### 🇺🇸🔍 📨
-
-🤝 ❎ 🗳 🔜 ⤴️ **🗜 📨** ⚙️ ⚛ ✔ ⏭ (👈 ▶️ ⏮️ 📄 `someapp.example.com`), & 📨 ⚫️ 🔙 🖥.
-
-⏭, 🖥 🔜 ✔ 👈 📨 ☑ & 🗜 ⏮️ ▶️️ 🔐 🔑, ♒️. ⚫️ 🔜 ⤴️ **🗜 📨** & 🛠️ ⚫️.
-
-
-
-👩💻 (🖥) 🔜 💭 👈 📨 👟 ⚪️➡️ ☑ 💽 ↩️ ⚫️ ⚙️ ⚛ 👫 ✔ ⚙️ **🇺🇸🔍 📄** ⏭.
-
-### 💗 🈸
-
-🎏 💽 (⚖️ 💽), 📤 💪 **💗 🈸**, 🖼, 🎏 🛠️ 📋 ⚖️ 💽.
-
-🕴 1️⃣ 🛠️ 💪 🚚 🎯 📢 & ⛴ (🤝 ❎ 🗳 👆 🖼) ✋️ 🎏 🈸/🛠️ 💪 🏃 🔛 💽(Ⓜ) 💁♂️, 📏 👫 🚫 🔄 ⚙️ 🎏 **🌀 📢 📢 & ⛴**.
-
-
-
-👈 🌌, 🤝 ❎ 🗳 💪 🍵 🇺🇸🔍 & 📄 **💗 🆔**, 💗 🈸, & ⤴️ 📶 📨 ▶️️ 🈸 🔠 💼.
-
-### 📄 🔕
-
-☝ 🔮, 🔠 📄 🔜 **🕛** (🔃 3️⃣ 🗓️ ⏮️ 🏗 ⚫️).
-
-& ⤴️, 📤 🔜 ➕1️⃣ 📋 (💼 ⚫️ ➕1️⃣ 📋, 💼 ⚫️ 💪 🎏 🤝 ❎ 🗳) 👈 🔜 💬 ➡️ 🗜, & ♻ 📄(Ⓜ).
-
-
-
-**🤝 📄** **🔗 ⏮️ 🆔 📛**, 🚫 ⏮️ 📢 📢.
-
-, ♻ 📄, 🔕 📋 💪 **🎦** 🛃 (➡️ 🗜) 👈 ⚫️ 👐 **"👍" & 🎛 👈 🆔**.
-
-👈, & 🏗 🎏 🈸 💪, 📤 📚 🌌 ⚫️ 💪 ⚫️. 🌟 🌌:
-
-* **🔀 🏓 ⏺**.
- * 👉, 🔕 📋 💪 🐕🦺 🔗 🏓 🐕🦺,, ⚓️ 🔛 🏓 🐕🦺 👆 ⚙️, 👉 5️⃣📆 ⚖️ 💪 🚫 🎛.
-* **🏃 💽** (🌘 ⏮️ 📄 🛠️ 🛠️) 🔛 📢 📢 📢 🔗 ⏮️ 🆔.
- * 👥 💬 🔛, 🕴 1️⃣ 🛠️ 💪 👂 🔛 🎯 📢 & ⛴.
- * 👉 1️⃣ 🤔 ⚫️❔ ⚫️ 📶 ⚠ 🕐❔ 🎏 🤝 ❎ 🗳 ✊ 💅 📄 🔕 🛠️.
- * ⏪, 👆 💪 ✔️ ⛔️ 🤝 ❎ 🗳 😖, ▶️ 🔕 📋 📎 📄, ⤴️ 🔗 👫 ⏮️ 🤝 ❎ 🗳, & ⤴️ ⏏ 🤝 ❎ 🗳. 👉 🚫 💯, 👆 📱(Ⓜ) 🔜 🚫 💪 ⏮️ 🕰 👈 🤝 ❎ 🗳 📆.
-
-🌐 👉 🔕 🛠️, ⏪ 🍦 📱, 1️⃣ 👑 🤔 ⚫️❔ 👆 🔜 💚 ✔️ **🎏 ⚙️ 🍵 🇺🇸🔍** ⏮️ 🤝 ❎ 🗳 ↩️ ⚙️ 🤝 📄 ⏮️ 🈸 💽 🔗 (✅ Uvicorn).
-
-## 🌃
-
-✔️ **🇺🇸🔍** 📶 ⚠, & **🎯** 🏆 💼. 🌅 🎯 👆 👩💻 ✔️ 🚮 🤭 🇺🇸🔍 🔃 **🤔 👉 🔧** & ❔ 👫 👷.
-
-✋️ 🕐 👆 💭 🔰 ℹ **🇺🇸🔍 👩💻** 👆 💪 💪 🌀 & 🔗 🎏 🧰 ℹ 👆 🛠️ 🌐 🙅 🌌.
-
-⏭ 📃, 👤 🔜 🎦 👆 📚 🧱 🖼 ❔ ⚒ 🆙 **🇺🇸🔍** **FastAPI** 🈸. 👶
diff --git a/docs/em/docs/deployment/index.md b/docs/em/docs/deployment/index.md
deleted file mode 100644
index 9bcf427b6..000000000
--- a/docs/em/docs/deployment/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# 🛠️
-
-🛠️ **FastAPI** 🈸 📶 ⏩.
-
-## ⚫️❔ 🔨 🛠️ ⛓
-
-**🛠️** 🈸 ⛓ 🎭 💪 📶 ⚒ ⚫️ **💪 👩💻**.
-
-**🕸 🛠️**, ⚫️ 🛎 🔌 🚮 ⚫️ **🛰 🎰**, ⏮️ **💽 📋** 👈 🚚 👍 🎭, ⚖, ♒️, 👈 👆 **👩💻** 💪 **🔐** 🈸 ♻ & 🍵 🔁 ⚖️ ⚠.
-
-👉 🔅 **🛠️** ▶️, 🌐❔ 👆 🕧 🔀 📟, 💔 ⚫️ & ♻ ⚫️, ⛔️ & 🔁 🛠️ 💽, ♒️.
-
-## 🛠️ 🎛
-
-📤 📚 🌌 ⚫️ ⚓️ 🔛 👆 🎯 ⚙️ 💼 & 🧰 👈 👆 ⚙️.
-
-👆 💪 **🛠️ 💽** 👆 ⚙️ 🌀 🧰, 👆 💪 ⚙️ **☁ 🐕🦺** 👈 🔨 🍕 👷 👆, ⚖️ 🎏 💪 🎛.
-
-👤 🔜 🎦 👆 👑 🔧 👆 🔜 🎲 ✔️ 🤯 🕐❔ 🛠️ **FastAPI** 🈸 (👐 🌅 ⚫️ ✔ 🙆 🎏 🆎 🕸 🈸).
-
-👆 🔜 👀 🌖 ℹ ✔️ 🤯 & ⚒ ⚫️ ⏭ 📄. 👶
diff --git a/docs/em/docs/deployment/manually.md b/docs/em/docs/deployment/manually.md
deleted file mode 100644
index 8ebe00c7c..000000000
--- a/docs/em/docs/deployment/manually.md
+++ /dev/null
@@ -1,159 +0,0 @@
-# 🏃 💽 ❎ - Uvicorn
-
-👑 👜 👆 💪 🏃 **FastAPI** 🈸 🛰 💽 🎰 🔫 💽 📋 💖 **Uvicorn**.
-
-📤 3️⃣ 👑 🎛:
-
-* Uvicorn: ↕ 🎭 🔫 💽.
-* Hypercorn: 🔫 💽 🔗 ⏮️ 🇺🇸🔍/2️⃣ & 🎻 👪 🎏 ⚒.
-* 👸: 🔫 💽 🏗 ✳ 📻.
-
-## 💽 🎰 & 💽 📋
-
-📤 🤪 ℹ 🔃 📛 ✔️ 🤯. 👶
-
-🔤 "**💽**" 🛎 ⚙️ 🔗 👯♂️ 🛰/☁ 💻 (⚛ ⚖️ 🕹 🎰) & 📋 👈 🏃♂ 🔛 👈 🎰 (✅ Uvicorn).
-
-✔️ 👈 🤯 🕐❔ 👆 ✍ "💽" 🏢, ⚫️ 💪 🔗 1️⃣ 📚 2️⃣ 👜.
-
-🕐❔ 🔗 🛰 🎰, ⚫️ ⚠ 🤙 ⚫️ **💽**, ✋️ **🎰**, **💾** (🕹 🎰), **🕸**. 👈 🌐 🔗 🆎 🛰 🎰, 🛎 🏃♂ 💾, 🌐❔ 👆 🏃 📋.
-
-## ❎ 💽 📋
-
-👆 💪 ❎ 🔫 🔗 💽 ⏮️:
-
-//// tab | Uvicorn
-
-* Uvicorn, 🌩-⏩ 🔫 💽, 🏗 🔛 uvloop & httptool.
-
-- -**FastAPI** 🚫🔜 🔀 🚥 🚫 ⏮️ 👷 🎏. - -📤 ✔️ 📚 🧰 ✍ ⏭ 👈 ✔️ ℹ 😮 🚮 🏗. - -👤 ✔️ ❎ 🏗 🆕 🛠️ 📚 1️⃣2️⃣🗓️. 🥇 👤 🔄 ❎ 🌐 ⚒ 📔 **FastAPI** ⚙️ 📚 🎏 🛠️, 🔌-🔌, & 🧰. - -✋️ ☝, 📤 🙅♂ 🎏 🎛 🌘 🏗 🕳 👈 🚚 🌐 👫 ⚒, ✊ 🏆 💭 ⚪️➡️ ⏮️ 🧰, & 🌀 👫 🏆 🌌 💪, ⚙️ 🇪🇸 ⚒ 👈 ➖🚫 💪 ⏭ (🐍 3️⃣.6️⃣ ➕ 🆎 🔑). - -- -## 🔬 - -⚙️ 🌐 ⏮️ 🎛 👤 ✔️ 🤞 💡 ⚪️➡️ 🌐 👫, ✊ 💭, & 🌀 👫 🏆 🌌 👤 💪 🔎 👤 & 🏉 👩💻 👤 ✔️ 👷 ⏮️. - -🖼, ⚫️ 🆑 👈 🎲 ⚫️ 🔜 ⚓️ 🔛 🐩 🐍 🆎 🔑. - -, 🏆 🎯 ⚙️ ⏪ ♻ 🐩. - -, ⏭ ▶️ 📟 **FastAPI**, 👤 💸 📚 🗓️ 🎓 🔌 🗄, 🎻 🔗, Oauth2️⃣, ♒️. 🎯 👫 💛, 🔀, & 🔺. - -## 🔧 - -⤴️ 👤 💸 🕰 🔧 👩💻 "🛠️" 👤 💚 ✔️ 👩💻 (👩💻 ⚙️ FastAPI). - -👤 💯 📚 💭 🏆 🌟 🐍 👨🎨: 🗒, 🆚 📟, 🎠 🧢 👨🎨. - -🏁 🐍 👩💻 🔬, 👈 📔 🔃 8️⃣0️⃣ 💯 👩💻. - -⚫️ ⛓ 👈 **FastAPI** 🎯 💯 ⏮️ 👨🎨 ⚙️ 8️⃣0️⃣ 💯 🐍 👩💻. & 🏆 🎏 👨🎨 😑 👷 ➡, 🌐 🚮 💰 🔜 👷 🌖 🌐 👨🎨. - -👈 🌌 👤 💪 🔎 🏆 🌌 📉 📟 ❎ 🌅 💪, ✔️ 🛠️ 🌐, 🆎 & ❌ ✅, ♒️. - -🌐 🌌 👈 🚚 🏆 🛠️ 💡 🌐 👩💻. - -## 📄 - -⏮️ 🔬 📚 🎛, 👤 💭 👈 👤 🔜 ⚙️ **Pydantic** 🚮 📈. - -⤴️ 👤 📉 ⚫️, ⚒ ⚫️ 🍕 🛠️ ⏮️ 🎻 🔗, 🐕🦺 🎏 🌌 🔬 ⚛ 📄, & 📉 👨🎨 🐕🦺 (🆎 ✅, ✍) ⚓️ 🔛 💯 📚 👨🎨. - -⏮️ 🛠️, 👤 📉 **💃**, 🎏 🔑 📄. - -## 🛠️ - -🕰 👤 ▶️ 🏗 **FastAPI** ⚫️, 🏆 🍖 ⏪ 🥉, 🔧 🔬, 📄 & 🧰 🔜, & 💡 🔃 🐩 & 🔧 🆑 & 🍋. - -## 🔮 - -👉 ☝, ⚫️ ⏪ 🆑 👈 **FastAPI** ⏮️ 🚮 💭 ➖ ⚠ 📚 👫👫. - -⚫️ 💆♂ 👐 🤭 ⏮️ 🎛 ♣ 📚 ⚙️ 💼 👍. - -📚 👩💻 & 🏉 ⏪ 🪀 🔛 **FastAPI** 👫 🏗 (🔌 👤 & 👇 🏉). - -✋️, 📤 📚 📈 & ⚒ 👟. - -**FastAPI** ✔️ 👑 🔮 ⤴️. - -& [👆 ℹ](help-fastapi.md){.internal-link target=_blank} 📉 👍. diff --git a/docs/em/docs/how-to/conditional-openapi.md b/docs/em/docs/how-to/conditional-openapi.md deleted file mode 100644 index e47ea0c35..000000000 --- a/docs/em/docs/how-to/conditional-openapi.md +++ /dev/null @@ -1,56 +0,0 @@ -# 🎲 🗄 - -🚥 👆 💪, 👆 💪 ⚙️ ⚒ & 🌐 🔢 🔗 🗄 ✔ ⚓️ 🔛 🌐, & ❎ ⚫️ 🍕. - -## 🔃 💂♂, 🔗, & 🩺 - -🕵♂ 👆 🧾 👩💻 🔢 🏭 *🚫🔜 🚫* 🌌 🛡 👆 🛠️. - -👈 🚫 🚮 🙆 ➕ 💂♂ 👆 🛠️, *➡ 🛠️* 🔜 💪 🌐❔ 👫. - -🚥 📤 💂♂ ⚠ 👆 📟, ⚫️ 🔜 🔀. - -🕵♂ 🧾 ⚒ ⚫️ 🌅 ⚠ 🤔 ❔ 🔗 ⏮️ 👆 🛠️, & 💪 ⚒ ⚫️ 🌅 ⚠ 👆 ℹ ⚫️ 🏭. ⚫️ 💪 🤔 🎯 📨 💂♂ 🔘 🌌. - -🚥 👆 💚 🔐 👆 🛠️, 📤 📚 👍 👜 👆 💪, 🖼: - -* ⚒ 💭 👆 ✔️ 👍 🔬 Pydantic 🏷 👆 📨 💪 & 📨. -* 🔗 🙆 ✔ ✔ & 🔑 ⚙️ 🔗. -* 🙅 🏪 🔢 🔐, 🕴 🔐#️⃣. -* 🛠️ & ⚙️ 👍-💭 🔐 🧰, 💖 🇸🇲 & 🥙 🤝, ♒️. -* 🚮 🌅 🧽 ✔ 🎛 ⏮️ Oauth2️⃣ ↔ 🌐❔ 💪. -* ...♒️. - -👐, 👆 5️⃣📆 ✔️ 📶 🎯 ⚙️ 💼 🌐❔ 👆 🤙 💪 ❎ 🛠️ 🩺 🌐 (✅ 🏭) ⚖️ ⚓️ 🔛 📳 ⚪️➡️ 🌐 🔢. - -## 🎲 🗄 ⚪️➡️ ⚒ & 🇨🇻 { - -👆 💪 💪 ⚙️ 🎏 Pydantic ⚒ 🔗 👆 🏗 🗄 & 🩺 ⚜. - -🖼: - -{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *} - -📥 👥 📣 ⚒ `openapi_url` ⏮️ 🎏 🔢 `"/openapi.json"`. - -& ⤴️ 👥 ⚙️ ⚫️ 🕐❔ 🏗 `FastAPI` 📱. - -⤴️ 👆 💪 ❎ 🗄 (✅ 🎚 🩺) ⚒ 🌐 🔢 `OPENAPI_URL` 🛁 🎻, 💖: - -
diff --git a/docs/em/docs/how-to/graphql.md b/docs/em/docs/how-to/graphql.md
deleted file mode 100644
index 083e9ebd2..000000000
--- a/docs/em/docs/how-to/graphql.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# 🕹
-
-**FastAPI** ⚓️ 🔛 **🔫** 🐩, ⚫️ 📶 ⏩ 🛠️ 🙆 **🕹** 🗃 🔗 ⏮️ 🔫.
-
-👆 💪 🌀 😐 FastAPI *➡ 🛠️* ⏮️ 🕹 🔛 🎏 🈸.
-
-/// tip
-
-**🕹** ❎ 📶 🎯 ⚙️ 💼.
-
-⚫️ ✔️ **📈** & **⚠** 🕐❔ 🔬 ⚠ **🕸 🔗**.
-
-⚒ 💭 👆 🔬 🚥 **💰** 👆 ⚙️ 💼 ⚖ **👐**. 👶
-
-///
-
-## 🕹 🗃
-
-📥 **🕹** 🗃 👈 ✔️ **🔫** 🐕🦺. 👆 💪 ⚙️ 👫 ⏮️ **FastAPI**:
-
-* 🍓 👶
- * ⏮️ 🩺 FastAPI
-* 👸
- * ⏮️ 🩺 FastAPI
-* 🍟
- * ⏮️ 🍟 🔫 🚚 🔫 🛠️
-* ⚗
- * ⏮️ 💃-Graphene3️⃣
-
-## 🕹 ⏮️ 🍓
-
-🚥 👆 💪 ⚖️ 💚 👷 ⏮️ **🕹**, **🍓** **👍** 🗃 ⚫️ ✔️ 🔧 🔐 **FastAPI** 🔧, ⚫️ 🌐 ⚓️ 🔛 **🆎 ✍**.
-
-⚓️ 🔛 👆 ⚙️ 💼, 👆 5️⃣📆 💖 ⚙️ 🎏 🗃, ✋️ 🚥 👆 💭 👤, 👤 🔜 🎲 🤔 👆 🔄 **🍓**.
-
-📥 🤪 🎮 ❔ 👆 💪 🛠️ 🍓 ⏮️ FastAPI:
-
-{* ../../docs_src/graphql/tutorial001.py hl[3,22,25:26] *}
-
-👆 💪 💡 🌅 🔃 🍓 🍓 🧾.
-
-& 🩺 🔃 🍓 ⏮️ FastAPI.
-
-## 🗝 `GraphQLApp` ⚪️➡️ 💃
-
-⏮️ ⏬ 💃 🔌 `GraphQLApp` 🎓 🛠️ ⏮️ ⚗.
-
-⚫️ 😢 ⚪️➡️ 💃, ✋️ 🚥 👆 ✔️ 📟 👈 ⚙️ ⚫️, 👆 💪 💪 **↔** 💃-Graphene3️⃣, 👈 📔 🎏 ⚙️ 💼 & ✔️ **🌖 🌓 🔢**.
-
-/// tip
-
-🚥 👆 💪 🕹, 👤 🔜 👍 👆 ✅ 👅 🍓, ⚫️ ⚓️ 🔛 🆎 ✍ ↩️ 🛃 🎓 & 🆎.
-
-///
-
-## 💡 🌅
-
-👆 💪 💡 🌅 🔃 **🕹** 🛂 🕹 🧾.
-
-👆 💪 ✍ 🌅 🔃 🔠 👈 🗃 🔬 🔛 👫 🔗.
diff --git a/docs/em/docs/index.md b/docs/em/docs/index.md
deleted file mode 100644
index fac4ba91a..000000000
--- a/docs/em/docs/index.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# FastAPI
-
-
-
-
-
-
- FastAPI 🛠️, ↕ 🎭, ⏩ 💡, ⏩ 📟, 🔜 🏭 -
- - ---- - -**🧾**: https://fastapi.tiangolo.com - -**ℹ 📟**: https://github.com/fastapi/fastapi - ---- - -FastAPI 🏛, ⏩ (↕-🎭), 🕸 🛠️ 🏗 🛠️ ⏮️ 🐍 3️⃣.8️⃣ ➕ ⚓️ 🔛 🐩 🐍 🆎 🔑. - -🔑 ⚒: - -* **⏩**: 📶 ↕ 🎭, 🔛 🇷🇪 ⏮️ **✳** & **🚶** (👏 💃 & Pydantic). [1️⃣ ⏩ 🐍 🛠️ 💪](#_15). -* **⏩ 📟**: 📈 🚅 🛠️ ⚒ 🔃 2️⃣0️⃣0️⃣ 💯 3️⃣0️⃣0️⃣ 💯. * -* **👩❤👨 🐛**: 📉 🔃 4️⃣0️⃣ 💯 🗿 (👩💻) 📉 ❌. * -* **🏋️**: 👑 👨🎨 🐕🦺. 🛠️ 🌐. 🌘 🕰 🛠️. -* **⏩**: 🔧 ⏩ ⚙️ & 💡. 🌘 🕰 👂 🩺. -* **📏**: 📉 📟 ❎. 💗 ⚒ ⚪️➡️ 🔠 🔢 📄. 👩❤👨 🐛. -* **🏋️**: 🤚 🏭-🔜 📟. ⏮️ 🏧 🎓 🧾. -* **🐩-⚓️**: ⚓️ 🔛 (& 🍕 🔗 ⏮️) 📂 🐩 🔗: 🗄 (⏪ 💭 🦁) & 🎻 🔗. - -* ⚖ ⚓️ 🔛 💯 🔛 🔗 🛠️ 🏉, 🏗 🏭 🈸. - -## 💰 - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-🚥 👆 🏗 ✳ 📱 ⚙️ 📶 ↩️ 🕸 🛠️, ✅ 👅 **🏎**.
-
-**🏎** FastAPI 🐥 👪. & ⚫️ 🎯 **FastAPI 🇳🇨**. 👶 👶 👶
-
-## 📄
-
-🐍 3️⃣.7️⃣ ➕
-
-FastAPI 🧍 🔛 ⌚ 🐘:
-
-* 💃 🕸 🍕.
-* Pydantic 📊 🍕.
-
-## 👷♂
-
-async def...uvicorn main:app --reload...email-validator - 📧 🔬.
-
-⚙️ 💃:
-
-* httpx - ✔ 🚥 👆 💚 ⚙️ `TestClient`.
-* jinja2 - ✔ 🚥 👆 💚 ⚙️ 🔢 📄 📳.
-* python-multipart - ✔ 🚥 👆 💚 🐕🦺 📨 "✍", ⏮️ `request.form()`.
-* itsdangerous - ✔ `SessionMiddleware` 🐕🦺.
-* pyyaml - ✔ 💃 `SchemaGenerator` 🐕🦺 (👆 🎲 🚫 💪 ⚫️ ⏮️ FastAPI).
-
-⚙️ FastAPI / 💃:
-
-* uvicorn - 💽 👈 📐 & 🍦 👆 🈸.
-* orjson - ✔ 🚥 👆 💚 ⚙️ `ORJSONResponse`.
-* ujson - ✔ 🚥 👆 💚 ⚙️ `UJSONResponse`.
-
-👆 💪 ❎ 🌐 👫 ⏮️ `pip install "fastapi[all]"`.
-
-## 🛂
-
-👉 🏗 ® 🔽 ⚖ 🇩🇪 🛂.
diff --git a/docs/em/docs/project-generation.md b/docs/em/docs/project-generation.md
deleted file mode 100644
index ef6a21821..000000000
--- a/docs/em/docs/project-generation.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# 🏗 ⚡ - 📄
-
-👆 💪 ⚙️ 🏗 🚂 🤚 ▶️, ⚫️ 🔌 📚 ▶️ ⚒ 🆙, 💂♂, 💽 & 🛠️ 🔗 ⏪ ⌛ 👆.
-
-🏗 🚂 🔜 🕧 ✔️ 📶 🙃 🖥 👈 👆 🔜 ℹ & 🛠️ 👆 👍 💪, ✋️ ⚫️ 💪 👍 ▶️ ☝ 👆 🏗.
-
-## 🌕 📚 FastAPI ✳
-
-📂: https://github.com/tiangolo/full-stack-fastapi-postgresql
-
-### 🌕 📚 FastAPI ✳ - ⚒
-
-* 🌕 **☁** 🛠️ (☁ 🧢).
-* ☁ 🐝 📳 🛠️.
-* **☁ ✍** 🛠️ & 🛠️ 🇧🇿 🛠️.
-* **🏭 🔜** 🐍 🕸 💽 ⚙️ Uvicorn & 🐁.
-* 🐍 **FastAPI** 👩💻:
- * **⏩**: 📶 ↕ 🎭, 🔛 🇷🇪 ⏮️ **✳** & **🚶** (👏 💃 & Pydantic).
- * **🏋️**: 👑 👨🎨 🐕🦺. 🛠️ 🌐. 🌘 🕰 🛠️.
- * **⏩**: 🔧 ⏩ ⚙️ & 💡. 🌘 🕰 👂 🩺.
- * **📏**: 📉 📟 ❎. 💗 ⚒ ⚪️➡️ 🔠 🔢 📄.
- * **🏋️**: 🤚 🏭-🔜 📟. ⏮️ 🏧 🎓 🧾.
- * **🐩-⚓️**: ⚓️ 🔛 (& 🍕 🔗 ⏮️) 📂 🐩 🔗: 🗄 & 🎻 🔗.
- * **📚 🎏 ⚒** 🔌 🏧 🔬, 🛠️, 🎓 🧾, 🤝 ⏮️ Oauth2️⃣ 🥙 🤝, ♒️.
-* **🔐 🔐** 🔁 🔢.
-* **🥙 🤝** 🤝.
-* **🇸🇲** 🏷 (🔬 🏺 ↔, 👫 💪 ⚙️ ⏮️ 🥒 👨🏭 🔗).
-* 🔰 ▶️ 🏷 👩💻 (🔀 & ❎ 👆 💪).
-* **⚗** 🛠️.
-* **⚜** (✖️ 🇨🇳 ℹ 🤝).
-* **🥒** 👨🏭 👈 💪 🗄 & ⚙️ 🏷 & 📟 ⚪️➡️ 🎂 👩💻 🍕.
-* 🎂 👩💻 💯 ⚓️ 🔛 **✳**, 🛠️ ⏮️ ☁, 👆 💪 💯 🌕 🛠️ 🔗, 🔬 🔛 💽. ⚫️ 🏃 ☁, ⚫️ 💪 🏗 🆕 💽 🏪 ⚪️➡️ 🖌 🔠 🕰 (👆 💪 ⚙️ ✳, ✳, ✳, ⚖️ ⚫️❔ 👆 💚, & 💯 👈 🛠️ 👷).
-* ⏩ 🐍 🛠️ ⏮️ **📂 💾** 🛰 ⚖️-☁ 🛠️ ⏮️ ↔ 💖 ⚛ ⚗ ⚖️ 🎙 🎙 📟 📂.
-* **🎦** 🕸:
- * 🏗 ⏮️ 🎦 ✳.
- * **🥙 🤝** 🚚.
- * 💳 🎑.
- * ⏮️ 💳, 👑 🕹 🎑.
- * 👑 🕹 ⏮️ 👩💻 🏗 & 📕.
- * 👤 👩💻 📕.
- * **🇷🇪**.
- * **🎦-📻**.
- * **Vuetify** 🌹 🧽 🔧 🦲.
- * **📕**.
- * ☁ 💽 ⚓️ 🔛 **👌** (📶 🤾 🎆 ⏮️ 🎦-📻).
- * ☁ 👁-▶️ 🏗, 👆 🚫 💪 🖊 ⚖️ 💕 ✍ 📟.
- * 🕸 💯 🏃 🏗 🕰 (💪 🔕 💁♂️).
- * ⚒ 🔧 💪, ⚫️ 👷 👅 📦, ✋️ 👆 💪 🏤-🏗 ⏮️ 🎦 ✳ ⚖️ ✍ ⚫️ 👆 💪, & 🏤-⚙️ ⚫️❔ 👆 💚.
-* ** *️⃣ ** ✳ 💽, 👆 💪 🔀 ⚫️ ⚙️ 📁 & ✳ 💪.
-* **🥀** 🥒 👨🏭 ⚖.
-* 📐 ⚖ 🖖 🕸 & 👩💻 ⏮️ **Traefik**, 👆 💪 ✔️ 👯♂️ 🔽 🎏 🆔, 👽 ➡, ✋️ 🍦 🎏 📦.
-* Traefik 🛠️, ✅ ➡️ 🗜 **🇺🇸🔍** 📄 🏧 ⚡.
-* ✳ **🆑** (🔁 🛠️), 🔌 🕸 & 👩💻 🔬.
-
-## 🌕 📚 FastAPI 🗄
-
-📂: https://github.com/tiangolo/full-stack-fastapi-couchbase
-
-👶 👶 **⚠** 👶 👶
-
-🚥 👆 ▶️ 🆕 🏗 ⚪️➡️ 🖌, ✅ 🎛 📥.
-
-🖼, 🏗 🚂 🌕 📚 FastAPI ✳ 💪 👍 🎛, ⚫️ 🎯 🚧 & ⚙️. & ⚫️ 🔌 🌐 🆕 ⚒ & 📈.
-
-👆 🆓 ⚙️ 🗄-⚓️ 🚂 🚥 👆 💚, ⚫️ 🔜 🎲 👷 👌, & 🚥 👆 ⏪ ✔️ 🏗 🏗 ⏮️ ⚫️ 👈 👌 👍 (& 👆 🎲 ⏪ ℹ ⚫️ ♣ 👆 💪).
-
-👆 💪 ✍ 🌅 🔃 ⚫️ 🩺 🏦.
-
-## 🌕 📚 FastAPI ✳
-
-...💪 👟 ⏪, ⚓️ 🔛 👇 🕰 🚚 & 🎏 ⚖. 👶 👶
-
-## 🎰 🏫 🏷 ⏮️ 🌈 & FastAPI
-
-📂: https://github.com/microsoft/cookiecutter-spacy-fastapi
-
-### 🎰 🏫 🏷 ⏮️ 🌈 & FastAPI - ⚒
-
-* **🌈** 🕜 🏷 🛠️.
-* **☁ 🧠 🔎** 📨 📁 🏗.
-* **🏭 🔜** 🐍 🕸 💽 ⚙️ Uvicorn & 🐁.
-* **☁ 👩💻** Kubernetes (🦲) 🆑/💿 🛠️ 🏗.
-* **🤸♂** 💪 ⚒ 1️⃣ 🌈 🏗 🇪🇸 ⏮️ 🏗 🖥.
-* **💪 🏧** 🎏 🏷 🛠️ (Pytorch, 🇸🇲), 🚫 🌈.
diff --git a/docs/em/docs/python-types.md b/docs/em/docs/python-types.md
deleted file mode 100644
index d2af23bb9..000000000
--- a/docs/em/docs/python-types.md
+++ /dev/null
@@ -1,542 +0,0 @@
-# 🐍 🆎 🎶
-
-🐍 ✔️ 🐕🦺 📦 "🆎 🔑".
-
-👫 **"🆎 🔑"** 🎁 ❕ 👈 ✔ 📣 🆎 🔢.
-
-📣 🆎 👆 🔢, 👨🎨 & 🧰 💪 🤝 👆 👍 🐕🦺.
-
-👉 **⏩ 🔰 / ↗️** 🔃 🐍 🆎 🔑. ⚫️ 📔 🕴 💯 💪 ⚙️ 👫 ⏮️ **FastAPI**... ❔ 🤙 📶 🐥.
-
-**FastAPI** 🌐 ⚓️ 🔛 👫 🆎 🔑, 👫 🤝 ⚫️ 📚 📈 & 💰.
-
-✋️ 🚥 👆 🙅 ⚙️ **FastAPI**, 👆 🔜 💰 ⚪️➡️ 🏫 🍖 🔃 👫.
-
-/// note
-
-🚥 👆 🐍 🕴, & 👆 ⏪ 💭 🌐 🔃 🆎 🔑, 🚶 ⏭ 📃.
-
-///
-
-## 🎯
-
-➡️ ▶️ ⏮️ 🙅 🖼:
-
-```Python
-{!../../docs_src/python_types/tutorial001.py!}
-```
-
-🤙 👉 📋 🔢:
-
-```
-John Doe
-```
-
-🔢 🔨 📄:
-
-* ✊ `first_name` & `last_name`.
-* 🗜 🥇 🔤 🔠 1️⃣ ↖ 💼 ⏮️ `title()`.
-* 🔢 👫 ⏮️ 🚀 🖕.
-
-```Python hl_lines="2"
-{!../../docs_src/python_types/tutorial001.py!}
-```
-
-### ✍ ⚫️
-
-⚫️ 📶 🙅 📋.
-
-✋️ 🔜 🌈 👈 👆 ✍ ⚫️ ⚪️➡️ 🖌.
-
-☝ 👆 🔜 ✔️ ▶️ 🔑 🔢, 👆 ✔️ 🔢 🔜...
-
-✋️ ⤴️ 👆 ✔️ 🤙 "👈 👩🔬 👈 🗜 🥇 🔤 ↖ 💼".
-
-⚫️ `upper`❓ ⚫️ `uppercase`❓ `first_uppercase`❓ `capitalize`❓
-
-⤴️, 👆 🔄 ⏮️ 🗝 👩💻 👨👧👦, 👨🎨 ✍.
-
-👆 🆎 🥇 🔢 🔢, `first_name`, ⤴️ ❣ (`.`) & ⤴️ 🎯 `Ctrl+Space` ⏲ 🛠️.
-
-✋️, 😞, 👆 🤚 🕳 ⚠:
-
-
-
-### 🚮 🆎
-
-➡️ 🔀 👁 ⏸ ⚪️➡️ ⏮️ ⏬.
-
-👥 🔜 🔀 ⚫️❔ 👉 🧬, 🔢 🔢, ⚪️➡️:
-
-```Python
- first_name, last_name
-```
-
-:
-
-```Python
- first_name: str, last_name: str
-```
-
-👈 ⚫️.
-
-👈 "🆎 🔑":
-
-```Python hl_lines="1"
-{!../../docs_src/python_types/tutorial002.py!}
-```
-
-👈 🚫 🎏 📣 🔢 💲 💖 🔜 ⏮️:
-
-```Python
- first_name="john", last_name="doe"
-```
-
-⚫️ 🎏 👜.
-
-👥 ⚙️ ❤ (`:`), 🚫 🌓 (`=`).
-
-& ❎ 🆎 🔑 🛎 🚫 🔀 ⚫️❔ 🔨 ⚪️➡️ ⚫️❔ 🔜 🔨 🍵 👫.
-
-✋️ 🔜, 🌈 👆 🔄 🖕 🏗 👈 🔢, ✋️ ⏮️ 🆎 🔑.
-
-🎏 ☝, 👆 🔄 ⏲ 📋 ⏮️ `Ctrl+Space` & 👆 👀:
-
-
-
-⏮️ 👈, 👆 💪 📜, 👀 🎛, ⏭ 👆 🔎 1️⃣ 👈 "💍 🔔":
-
-
-
-## 🌅 🎯
-
-✅ 👉 🔢, ⚫️ ⏪ ✔️ 🆎 🔑:
-
-```Python hl_lines="1"
-{!../../docs_src/python_types/tutorial003.py!}
-```
-
-↩️ 👨🎨 💭 🆎 🔢, 👆 🚫 🕴 🤚 🛠️, 👆 🤚 ❌ ✅:
-
-
-
-🔜 👆 💭 👈 👆 ✔️ 🔧 ⚫️, 🗜 `age` 🎻 ⏮️ `str(age)`:
-
-```Python hl_lines="2"
-{!../../docs_src/python_types/tutorial004.py!}
-```
-
-## 📣 🆎
-
-👆 👀 👑 🥉 📣 🆎 🔑. 🔢 🔢.
-
-👉 👑 🥉 👆 🔜 ⚙️ 👫 ⏮️ **FastAPI**.
-
-### 🙅 🆎
-
-👆 💪 📣 🌐 🐩 🐍 🆎, 🚫 🕴 `str`.
-
-👆 💪 ⚙️, 🖼:
-
-* `int`
-* `float`
-* `bool`
-* `bytes`
-
-```Python hl_lines="1"
-{!../../docs_src/python_types/tutorial005.py!}
-```
-
-### 💊 🆎 ⏮️ 🆎 🔢
-
-📤 📊 📊 👈 💪 🔌 🎏 💲, 💖 `dict`, `list`, `set` & `tuple`. & 🔗 💲 💪 ✔️ 👫 👍 🆎 💁♂️.
-
-👉 🆎 👈 ✔️ 🔗 🆎 🤙 "**💊**" 🆎. & ⚫️ 💪 📣 👫, ⏮️ 👫 🔗 🆎.
-
-📣 👈 🆎 & 🔗 🆎, 👆 💪 ⚙️ 🐩 🐍 🕹 `typing`. ⚫️ 🔀 🎯 🐕🦺 👫 🆎 🔑.
-
-#### 🆕 ⏬ 🐍
-
-❕ ⚙️ `typing` **🔗** ⏮️ 🌐 ⏬, ⚪️➡️ 🐍 3️⃣.6️⃣ ⏪ 🕐, ✅ 🐍 3️⃣.9️⃣, 🐍 3️⃣.1️⃣0️⃣, ♒️.
-
-🐍 🏧, **🆕 ⏬** 👟 ⏮️ 📉 🐕🦺 👉 🆎 ✍ & 📚 💼 👆 🏆 🚫 💪 🗄 & ⚙️ `typing` 🕹 📣 🆎 ✍.
-
-🚥 👆 💪 ⚒ 🌖 ⏮️ ⏬ 🐍 👆 🏗, 👆 🔜 💪 ✊ 📈 👈 ➕ 🦁. 👀 🖼 🔛.
-
-#### 📇
-
-🖼, ➡️ 🔬 🔢 `list` `str`.
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-⚪️➡️ `typing`, 🗄 `List` (⏮️ 🔠 `L`):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
-
-🆎, 🚮 `List` 👈 👆 🗄 ⚪️➡️ `typing`.
-
-📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.9️⃣ & 🔛
-
-📣 🔢, ⏮️ 🎏 ❤ (`:`) ❕.
-
-🆎, 🚮 `list`.
-
-📇 🆎 👈 🔌 🔗 🆎, 👆 🚮 👫 ⬜ 🗜:
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
-
-/// info
-
-👈 🔗 🆎 ⬜ 🗜 🤙 "🆎 🔢".
-
-👉 💼, `str` 🆎 🔢 🚶♀️ `List` (⚖️ `list` 🐍 3️⃣.9️⃣ & 🔛).
-
-///
-
-👈 ⛓: "🔢 `items` `list`, & 🔠 🏬 👉 📇 `str`".
-
-/// tip
-
-🚥 👆 ⚙️ 🐍 3️⃣.9️⃣ ⚖️ 🔛, 👆 🚫 ✔️ 🗄 `List` ⚪️➡️ `typing`, 👆 💪 ⚙️ 🎏 🥔 `list` 🆎 ↩️.
-
-///
-
-🔨 👈, 👆 👨🎨 💪 🚚 🐕🦺 ⏪ 🏭 🏬 ⚪️➡️ 📇:
-
-
-
-🍵 🆎, 👈 🌖 💪 🏆.
-
-👀 👈 🔢 `item` 1️⃣ 🔣 📇 `items`.
-
-& , 👨🎨 💭 ⚫️ `str`, & 🚚 🐕🦺 👈.
-
-#### 🔢 & ⚒
-
-👆 🔜 🎏 📣 `tuple`Ⓜ & `set`Ⓜ:
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial007.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.9️⃣ & 🔛
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial007_py39.py!}
-```
-
-////
-
-👉 ⛓:
-
-* 🔢 `items_t` `tuple` ⏮️ 3️⃣ 🏬, `int`, ➕1️⃣ `int`, & `str`.
-* 🔢 `items_s` `set`, & 🔠 🚮 🏬 🆎 `bytes`.
-
-#### #️⃣
-
-🔬 `dict`, 👆 🚶♀️ 2️⃣ 🆎 🔢, 🎏 ❕.
-
-🥇 🆎 🔢 🔑 `dict`.
-
-🥈 🆎 🔢 💲 `dict`:
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.9️⃣ & 🔛
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial008_py39.py!}
-```
-
-////
-
-👉 ⛓:
-
-* 🔢 `prices` `dict`:
- * 🔑 👉 `dict` 🆎 `str` (➡️ 💬, 📛 🔠 🏬).
- * 💲 👉 `dict` 🆎 `float` (➡️ 💬, 🔖 🔠 🏬).
-
-#### 🇪🇺
-
-👆 💪 📣 👈 🔢 💪 🙆 **📚 🆎**, 🖼, `int` ⚖️ `str`.
-
-🐍 3️⃣.6️⃣ & 🔛 (✅ 🐍 3️⃣.1️⃣0️⃣) 👆 💪 ⚙️ `Union` 🆎 ⚪️➡️ `typing` & 🚮 🔘 ⬜ 🗜 💪 🆎 🚫.
-
-🐍 3️⃣.1️⃣0️⃣ 📤 **🎛 ❕** 🌐❔ 👆 💪 🚮 💪 🆎 👽 ⏸ ⏸ (`|`).
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial008b_py310.py!}
-```
-
-////
-
-👯♂️ 💼 👉 ⛓ 👈 `item` 💪 `int` ⚖️ `str`.
-
-#### 🎲 `None`
-
-👆 💪 📣 👈 💲 💪 ✔️ 🆎, 💖 `str`, ✋️ 👈 ⚫️ 💪 `None`.
-
-🐍 3️⃣.6️⃣ & 🔛 (✅ 🐍 3️⃣.1️⃣0️⃣) 👆 💪 📣 ⚫️ 🏭 & ⚙️ `Optional` ⚪️➡️ `typing` 🕹.
-
-```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
-```
-
-⚙️ `Optional[str]` ↩️ `str` 🔜 ➡️ 👨🎨 ℹ 👆 🔍 ❌ 🌐❔ 👆 💪 🤔 👈 💲 🕧 `str`, 🕐❔ ⚫️ 💪 🤙 `None` 💁♂️.
-
-`Optional[Something]` 🤙 ⌨ `Union[Something, None]`, 👫 🌓.
-
-👉 ⛓ 👈 🐍 3️⃣.1️⃣0️⃣, 👆 💪 ⚙️ `Something | None`:
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛 - 🎛
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial009_py310.py!}
-```
-
-////
-
-#### ⚙️ `Union` ⚖️ `Optional`
-
-🚥 👆 ⚙️ 🐍 ⏬ 🔛 3️⃣.1️⃣0️⃣, 📥 💁♂ ⚪️➡️ 👇 📶 **🤔** ☝ 🎑:
-
-* 👶 ❎ ⚙️ `Optional[SomeType]`
-* ↩️ 👶 **⚙️ `Union[SomeType, None]`** 👶.
-
-👯♂️ 🌓 & 🔘 👫 🎏, ✋️ 👤 🔜 👍 `Union` ↩️ `Optional` ↩️ 🔤 "**📦**" 🔜 😑 🔑 👈 💲 📦, & ⚫️ 🤙 ⛓ "⚫️ 💪 `None`", 🚥 ⚫️ 🚫 📦 & ✔.
-
-👤 💭 `Union[SomeType, None]` 🌖 🔑 🔃 ⚫️❔ ⚫️ ⛓.
-
-⚫️ 🔃 🔤 & 📛. ✋️ 👈 🔤 💪 📉 ❔ 👆 & 👆 🤽♂ 💭 🔃 📟.
-
-🖼, ➡️ ✊ 👉 🔢:
-
-```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009c.py!}
-```
-
-🔢 `name` 🔬 `Optional[str]`, ✋️ ⚫️ **🚫 📦**, 👆 🚫🔜 🤙 🔢 🍵 🔢:
-
-```Python
-say_hi() # Oh, no, this throws an error! 😱
-```
-
-`name` 🔢 **✔** (🚫 *📦*) ↩️ ⚫️ 🚫 ✔️ 🔢 💲. , `name` 🚫 `None` 💲:
-
-```Python
-say_hi(name=None) # This works, None is valid 🎉
-```
-
-👍 📰, 🕐 👆 🔛 🐍 3️⃣.1️⃣0️⃣ 👆 🏆 🚫 ✔️ 😟 🔃 👈, 👆 🔜 💪 🎯 ⚙️ `|` 🔬 🇪🇺 🆎:
-
-```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009c_py310.py!}
-```
-
-& ⤴️ 👆 🏆 🚫 ✔️ 😟 🔃 📛 💖 `Optional` & `Union`. 👶
-
-#### 💊 🆎
-
-👉 🆎 👈 ✊ 🆎 🔢 ⬜ 🗜 🤙 **💊 🆎** ⚖️ **💊**, 🖼:
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...& 🎏.
-
-////
-
-//// tab | 🐍 3️⃣.9️⃣ & 🔛
-
-👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
- & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
-
-* `Union`
-* `Optional`
-* ...& 🎏.
-
-////
-
-//// tab | 🐍 3️⃣.1️⃣0️⃣ & 🔛
-
-👆 💪 ⚙️ 🎏 💽 🆎 💊 (⏮️ ⬜ 🗜 & 🆎 🔘):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
- & 🎏 ⏮️ 🐍 3️⃣.6️⃣, ⚪️➡️ `typing` 🕹:
-
-* `Union`
-* `Optional` (🎏 ⏮️ 🐍 3️⃣.6️⃣)
-* ...& 🎏.
-
-🐍 3️⃣.1️⃣0️⃣, 🎛 ⚙️ 💊 `Union` & `Optional`, 👆 💪 ⚙️ ⏸ ⏸ (`|`) 📣 🇪🇺 🆎.
-
-////
-
-### 🎓 🆎
-
-👆 💪 📣 🎓 🆎 🔢.
-
-➡️ 💬 👆 ✔️ 🎓 `Person`, ⏮️ 📛:
-
-```Python hl_lines="1-3"
-{!../../docs_src/python_types/tutorial010.py!}
-```
-
-⤴️ 👆 💪 📣 🔢 🆎 `Person`:
-
-```Python hl_lines="6"
-{!../../docs_src/python_types/tutorial010.py!}
-```
-
-& ⤴️, 🔄, 👆 🤚 🌐 👨🎨 🐕🦺:
-
-
-
-## Pydantic 🏷
-
-Pydantic 🐍 🗃 🎭 📊 🔬.
-
-👆 📣 "💠" 💽 🎓 ⏮️ 🔢.
-
-& 🔠 🔢 ✔️ 🆎.
-
-⤴️ 👆 ✍ 👐 👈 🎓 ⏮️ 💲 & ⚫️ 🔜 ✔ 💲, 🗜 👫 ☑ 🆎 (🚥 👈 💼) & 🤝 👆 🎚 ⏮️ 🌐 💽.
-
-& 👆 🤚 🌐 👨🎨 🐕🦺 ⏮️ 👈 📉 🎚.
-
-🖼 ⚪️➡️ 🛂 Pydantic 🩺:
-
-//// tab | 🐍 3️⃣.6️⃣ & 🔛
-
-```Python
-{!> ../../docs_src/python_types/tutorial011.py!}
-```
-
-////
-
-//// tab | 🐍 3️⃣.9️⃣ & 🔛
-
-```Python
-{!> ../../docs_src/python_types/tutorial011_py39.py!}
-```
-
-////
-
-//// 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 🩺 🔃 ✔ 📦 🏑.
-
-///
-
-## 🆎 🔑 **FastAPI**
-
-**FastAPI** ✊ 📈 👫 🆎 🔑 📚 👜.
-
-⏮️ **FastAPI** 👆 📣 🔢 ⏮️ 🆎 🔑 & 👆 🤚:
-
-* **👨🎨 🐕🦺**.
-* **🆎 ✅**.
-
-...and **FastAPI** uses the same declarations :
-
-* **🔬 📄**: ⚪️➡️ 📨 ➡ 🔢, 🔢 🔢, 🎚, 💪, 🔗, ♒️.
-* **🗜 💽**: ⚪️➡️ 📨 🚚 🆎.
-* **✔ 💽**: 👟 ⚪️➡️ 🔠 📨:
- * 🏭 **🏧 ❌** 📨 👩💻 🕐❔ 📊 ❌.
-* **📄** 🛠️ ⚙️ 🗄:
- * ❔ ⤴️ ⚙️ 🏧 🎓 🧾 👩💻 🔢.
-
-👉 5️⃣📆 🌐 🔊 📝. 🚫 😟. 👆 🔜 👀 🌐 👉 🎯 [🔰 - 👩💻 🦮](tutorial/index.md){.internal-link target=_blank}.
-
-⚠ 👜 👈 ⚙️ 🐩 🐍 🆎, 👁 🥉 (↩️ ❎ 🌖 🎓, 👨🎨, ♒️), **FastAPI** 🔜 📚 👷 👆.
-
-/// info
-
-🚥 👆 ⏪ 🚶 🔘 🌐 🔰 & 👟 🔙 👀 🌅 🔃 🆎, 👍 ℹ "🎮 🎼" ⚪️➡️ `mypy`.
-
-///
diff --git a/docs/em/docs/tutorial/background-tasks.md b/docs/em/docs/tutorial/background-tasks.md
deleted file mode 100644
index aed60c754..000000000
--- a/docs/em/docs/tutorial/background-tasks.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# 🖥 📋
-
-👆 💪 🔬 🖥 📋 🏃 *⏮️* 🛬 📨.
-
-👉 ⚠ 🛠️ 👈 💪 🔨 ⏮️ 📨, ✋️ 👈 👩💻 🚫 🤙 ✔️ ⌛ 🛠️ 🏁 ⏭ 📨 📨.
-
-👉 🔌, 🖼:
-
-* 📧 📨 📨 ⏮️ 🎭 🎯:
- * 🔗 📧 💽 & 📨 📧 😑 "🐌" (📚 🥈), 👆 💪 📨 📨 ▶️️ ↖️ & 📨 📧 📨 🖥.
-* 🏭 💽:
- * 🖼, ➡️ 💬 👆 📨 📁 👈 🔜 🚶 🔘 🐌 🛠️, 👆 💪 📨 📨 "🚫" (🇺🇸🔍 2️⃣0️⃣2️⃣) & 🛠️ ⚫️ 🖥.
-
-## ⚙️ `BackgroundTasks`
-
-🥇, 🗄 `BackgroundTasks` & 🔬 🔢 👆 *➡ 🛠️ 🔢* ⏮️ 🆎 📄 `BackgroundTasks`:
-
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
-
-**FastAPI** 🔜 ✍ 🎚 🆎 `BackgroundTasks` 👆 & 🚶♀️ ⚫️ 👈 🔢.
-
-## ✍ 📋 🔢
-
-✍ 🔢 🏃 🖥 📋.
-
-⚫️ 🐩 🔢 👈 💪 📨 🔢.
-
-⚫️ 💪 `async def` ⚖️ 😐 `def` 🔢, **FastAPI** 🔜 💭 ❔ 🍵 ⚫️ ☑.
-
-👉 💼, 📋 🔢 🔜 ✍ 📁 (⚖ 📨 📧).
-
-& ✍ 🛠️ 🚫 ⚙️ `async` & `await`, 👥 🔬 🔢 ⏮️ 😐 `def`:
-
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
-
-## 🚮 🖥 📋
-
-🔘 👆 *➡ 🛠️ 🔢*, 🚶♀️ 👆 📋 🔢 *🖥 📋* 🎚 ⏮️ 👩🔬 `.add_task()`:
-
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
-
-`.add_task()` 📨 ❌:
-
-* 📋 🔢 🏃 🖥 (`write_notification`).
-* 🙆 🔁 ❌ 👈 🔜 🚶♀️ 📋 🔢 ✔ (`email`).
-* 🙆 🇨🇻 ❌ 👈 🔜 🚶♀️ 📋 🔢 (`message="some notification"`).
-
-## 🔗 💉
-
-⚙️ `BackgroundTasks` 👷 ⏮️ 🔗 💉 ⚙️, 👆 💪 📣 🔢 🆎 `BackgroundTasks` 💗 🎚: *➡ 🛠️ 🔢*, 🔗 (☑), 🎧-🔗, ♒️.
-
-**FastAPI** 💭 ⚫️❔ 🔠 💼 & ❔ 🏤-⚙️ 🎏 🎚, 👈 🌐 🖥 📋 🔗 👯♂️ & 🏃 🖥 ⏮️:
-
-{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
-
-👉 🖼, 📧 🔜 ✍ `log.txt` 📁 *⏮️* 📨 📨.
-
-🚥 📤 🔢 📨, ⚫️ 🔜 ✍ 🕹 🖥 📋.
-
-& ⤴️ ➕1️⃣ 🖥 📋 🏗 *➡ 🛠️ 🔢* 🔜 ✍ 📧 ⚙️ `email` ➡ 🔢.
-
-## 📡 ℹ
-
-🎓 `BackgroundTasks` 👟 🔗 ⚪️➡️ `starlette.background`.
-
-⚫️ 🗄/🔌 🔗 🔘 FastAPI 👈 👆 💪 🗄 ⚫️ ⚪️➡️ `fastapi` & ❎ 😫 🗄 🎛 `BackgroundTask` (🍵 `s` 🔚) ⚪️➡️ `starlette.background`.
-
-🕴 ⚙️ `BackgroundTasks` (& 🚫 `BackgroundTask`), ⚫️ ⤴️ 💪 ⚙️ ⚫️ *➡ 🛠️ 🔢* 🔢 & ✔️ **FastAPI** 🍵 🎂 👆, 💖 🕐❔ ⚙️ `Request` 🎚 🔗.
-
-⚫️ 💪 ⚙️ `BackgroundTask` 😞 FastAPI, ✋️ 👆 ✔️ ✍ 🎚 👆 📟 & 📨 💃 `Response` 🔌 ⚫️.
-
-👆 💪 👀 🌖 ℹ 💃 🛂 🩺 🖥 📋.
-
-## ⚠
-
-🚥 👆 💪 🎭 🏋️ 🖥 📊 & 👆 🚫 🎯 💪 ⚫️ 🏃 🎏 🛠️ (🖼, 👆 🚫 💪 💰 💾, 🔢, ♒️), 👆 💪 💰 ⚪️➡️ ⚙️ 🎏 🦏 🧰 💖 🥒.
-
-👫 😑 🚚 🌖 🏗 📳, 📧/👨🏭 📤 👨💼, 💖 ✳ ⚖️ ✳, ✋️ 👫 ✔ 👆 🏃 🖥 📋 💗 🛠️, & ✴️, 💗 💽.
-
-✋️ 🚥 👆 💪 🔐 🔢 & 🎚 ⚪️➡️ 🎏 **FastAPI** 📱, ⚖️ 👆 💪 🎭 🤪 🖥 📋 (💖 📨 📧 📨), 👆 💪 🎯 ⚙️ `BackgroundTasks`.
-
-## 🌃
-
-🗄 & ⚙️ `BackgroundTasks` ⏮️ 🔢 *➡ 🛠️ 🔢* & 🔗 🚮 🖥 📋.
diff --git a/docs/em/docs/tutorial/bigger-applications.md b/docs/em/docs/tutorial/bigger-applications.md
deleted file mode 100644
index 78a321ae6..000000000
--- a/docs/em/docs/tutorial/bigger-applications.md
+++ /dev/null
@@ -1,530 +0,0 @@
-# 🦏 🈸 - 💗 📁
-
-🚥 👆 🏗 🈸 ⚖️ 🕸 🛠️, ⚫️ 🛎 💼 👈 👆 💪 🚮 🌐 🔛 👁 📁.
-
-**FastAPI** 🚚 🏪 🧰 📊 👆 🈸 ⏪ 🚧 🌐 💪.
-
-/// info
-
-🚥 👆 👟 ⚪️➡️ 🏺, 👉 🔜 🌓 🏺 📗.
-
-///
-
-## 🖼 📁 📊
-
-➡️ 💬 👆 ✔️ 📁 📊 💖 👉:
-
-```
-.
-├── app
-│ ├── __init__.py
-│ ├── main.py
-│ ├── dependencies.py
-│ └── routers
-│ │ ├── __init__.py
-│ │ ├── items.py
-│ │ └── users.py
-│ └── internal
-│ ├── __init__.py
-│ └── admin.py
-```
-
-/// tip
-
-📤 📚 `__init__.py` 📁: 1️⃣ 🔠 📁 ⚖️ 📁.
-
-👉 ⚫️❔ ✔ 🏭 📟 ⚪️➡️ 1️⃣ 📁 🔘 ➕1️⃣.
-
-🖼, `app/main.py` 👆 💪 ✔️ ⏸ 💖:
-
-```
-from app.routers import items
-```
-
-///
-
-* `app` 📁 🔌 🌐. & ⚫️ ✔️ 🛁 📁 `app/__init__.py`, ⚫️ "🐍 📦" (🗃 "🐍 🕹"): `app`.
-* ⚫️ 🔌 `app/main.py` 📁. ⚫️ 🔘 🐍 📦 (📁 ⏮️ 📁 `__init__.py`), ⚫️ "🕹" 👈 📦: `app.main`.
-* 📤 `app/dependencies.py` 📁, 💖 `app/main.py`, ⚫️ "🕹": `app.dependencies`.
-* 📤 📁 `app/routers/` ⏮️ ➕1️⃣ 📁 `__init__.py`, ⚫️ "🐍 📦": `app.routers`.
-* 📁 `app/routers/items.py` 🔘 📦, `app/routers/`,, ⚫️ 🔁: `app.routers.items`.
-* 🎏 ⏮️ `app/routers/users.py`, ⚫️ ➕1️⃣ 🔁: `app.routers.users`.
-* 📤 📁 `app/internal/` ⏮️ ➕1️⃣ 📁 `__init__.py`, ⚫️ ➕1️⃣ "🐍 📦": `app.internal`.
-* & 📁 `app/internal/admin.py` ➕1️⃣ 🔁: `app.internal.admin`.
-
-
-
-🎏 📁 📊 ⏮️ 🏤:
-
-```
-.
-├── app # "app" is a Python package
-│ ├── __init__.py # this file makes "app" a "Python package"
-│ ├── main.py # "main" module, e.g. import app.main
-│ ├── dependencies.py # "dependencies" module, e.g. import app.dependencies
-│ └── routers # "routers" is a "Python subpackage"
-│ │ ├── __init__.py # makes "routers" a "Python subpackage"
-│ │ ├── items.py # "items" submodule, e.g. import app.routers.items
-│ │ └── users.py # "users" submodule, e.g. import app.routers.users
-│ └── internal # "internal" is a "Python subpackage"
-│ ├── __init__.py # makes "internal" a "Python subpackage"
-│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
-```
-
-## `APIRouter`
-
-➡️ 💬 📁 💡 🚚 👩💻 🔁 `/app/routers/users.py`.
-
-👆 💚 ✔️ *➡ 🛠️* 🔗 👆 👩💻 👽 ⚪️➡️ 🎂 📟, 🚧 ⚫️ 🏗.
-
-✋️ ⚫️ 🍕 🎏 **FastAPI** 🈸/🕸 🛠️ (⚫️ 🍕 🎏 "🐍 📦").
-
-👆 💪 ✍ *➡ 🛠️* 👈 🕹 ⚙️ `APIRouter`.
-
-### 🗄 `APIRouter`
-
-👆 🗄 ⚫️ & ✍ "👐" 🎏 🌌 👆 🔜 ⏮️ 🎓 `FastAPI`:
-
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
-
-### *➡ 🛠️* ⏮️ `APIRouter`
-
-& ⤴️ 👆 ⚙️ ⚫️ 📣 👆 *➡ 🛠️*.
-
-⚙️ ⚫️ 🎏 🌌 👆 🔜 ⚙️ `FastAPI` 🎓:
-
-```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
-
-👆 💪 💭 `APIRouter` "🐩 `FastAPI`" 🎓.
-
-🌐 🎏 🎛 🐕🦺.
-
-🌐 🎏 `parameters`, `responses`, `dependencies`, `tags`, ♒️.
-
-/// tip
-
-👉 🖼, 🔢 🤙 `router`, ✋️ 👆 💪 📛 ⚫️ 👐 👆 💚.
-
-///
-
-👥 🔜 🔌 👉 `APIRouter` 👑 `FastAPI` 📱, ✋️ 🥇, ➡️ ✅ 🔗 & ➕1️⃣ `APIRouter`.
-
-## 🔗
-
-👥 👀 👈 👥 🔜 💪 🔗 ⚙️ 📚 🥉 🈸.
-
-👥 🚮 👫 👫 👍 `dependencies` 🕹 (`app/dependencies.py`).
-
-👥 🔜 🔜 ⚙️ 🙅 🔗 ✍ 🛃 `X-Token` 🎚:
-
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!../../docs_src/bigger_applications/app/dependencies.py!}
-```
-
-/// tip
-
-👥 ⚙️ 💭 🎚 📉 👉 🖼.
-
-✋️ 🎰 💼 👆 🔜 🤚 👍 🏁 ⚙️ 🛠️ [💂♂ 🚙](security/index.md){.internal-link target=_blank}.
-
-///
-
-## ➕1️⃣ 🕹 ⏮️ `APIRouter`
-
-➡️ 💬 👆 ✔️ 🔗 💡 🚚 "🏬" ⚪️➡️ 👆 🈸 🕹 `app/routers/items.py`.
-
-👆 ✔️ *➡ 🛠️* :
-
-* `/items/`
-* `/items/{item_id}`
-
-⚫️ 🌐 🎏 📊 ⏮️ `app/routers/users.py`.
-
-✋️ 👥 💚 🙃 & 📉 📟 🍖.
-
-👥 💭 🌐 *➡ 🛠️* 👉 🕹 ✔️ 🎏:
-
-* ➡ `prefix`: `/items`.
-* `tags`: (1️⃣ 🔖: `items`).
-* ➕ `responses`.
-* `dependencies`: 👫 🌐 💪 👈 `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`.
-
-👥 💪 🚮 📇 `tags` & ➕ `responses` 👈 🔜 ✔ 🌐 *➡ 🛠️* 🔌 👉 📻.
-
-& 👥 💪 🚮 📇 `dependencies` 👈 🔜 🚮 🌐 *➡ 🛠️* 📻 & 🔜 🛠️/❎ 🔠 📨 ⚒ 👫.
-
-/// tip
-
-🗒 👈, 🌅 💖 [🔗 *➡ 🛠️ 👨🎨*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 🙅♂ 💲 🔜 🚶♀️ 👆 *➡ 🛠️ 🔢*.
-
-///
-
-🔚 🏁 👈 🏬 ➡ 🔜:
-
-* `/items/`
-* `/items/{item_id}`
-
-...👥 🎯.
-
-* 👫 🔜 ™ ⏮️ 📇 🔖 👈 🔌 👁 🎻 `"items"`.
- * 👫 "🔖" ✴️ ⚠ 🏧 🎓 🧾 ⚙️ (⚙️ 🗄).
-* 🌐 👫 🔜 🔌 🔁 `responses`.
-* 🌐 👫 *➡ 🛠️* 🔜 ✔️ 📇 `dependencies` 🔬/🛠️ ⏭ 👫.
- * 🚥 👆 📣 🔗 🎯 *➡ 🛠️*, **👫 🔜 🛠️ 💁♂️**.
- * 📻 🔗 🛠️ 🥇, ⤴️ [`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️⃣ 👫.
-
-///
-
-/// 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
-from .dependencies import get_token_header
-```
-
-🔜 ⛓:
-
-* ▶️ 🎏 📦 👈 👉 🕹 (📁 `app/routers/items.py`) 🖖 (📁 `app/routers/`)...
-* 🔎 🕹 `dependencies` (👽 📁 `app/routers/dependencies.py`)...
-* & ⚪️➡️ ⚫️, 🗄 🔢 `get_token_header`.
-
-✋️ 👈 📁 🚫 🔀, 👆 🔗 📁 `app/dependencies.py`.
-
-💭 ❔ 👆 📱/📁 📊 👀 💖:
-
-
-
----
-
-2️⃣ ❣ `..`, 💖:
-
-```Python
-from ..dependencies import get_token_header
-```
-
-⛓:
-
-* ▶️ 🎏 📦 👈 👉 🕹 (📁 `app/routers/items.py`) 🖖 (📁 `app/routers/`)...
-* 🚶 👪 📦 (📁 `app/`)...
-* & 📤, 🔎 🕹 `dependencies` (📁 `app/dependencies.py`)...
-* & ⚪️➡️ ⚫️, 🗄 🔢 `get_token_header`.
-
-👈 👷 ☑ ❗ 👶
-
----
-
-🎏 🌌, 🚥 👥 ✔️ ⚙️ 3️⃣ ❣ `...`, 💖:
-
-```Python
-from ...dependencies import get_token_header
-```
-
-that 🔜 ⛓:
-
-* ▶️ 🎏 📦 👈 👉 🕹 (📁 `app/routers/items.py`) 🖖 (📁 `app/routers/`)...
-* 🚶 👪 📦 (📁 `app/`)...
-* ⤴️ 🚶 👪 👈 📦 (📤 🙅♂ 👪 📦, `app` 🔝 🎚 👶)...
-* & 📤, 🔎 🕹 `dependencies` (📁 `app/dependencies.py`)...
-* & ⚪️➡️ ⚫️, 🗄 🔢 `get_token_header`.
-
-👈 🔜 🔗 📦 🔛 `app/`, ⏮️ 🚮 👍 📁 `__init__.py`, ♒️. ✋️ 👥 🚫 ✔️ 👈. , 👈 🔜 🚮 ❌ 👆 🖼. 👶
-
-✋️ 🔜 👆 💭 ❔ ⚫️ 👷, 👆 💪 ⚙️ ⚖ 🗄 👆 👍 📱 🙅♂ 🤔 ❔ 🏗 👫. 👶
-
-### 🚮 🛃 `tags`, `responses`, & `dependencies`
-
-👥 🚫 ❎ 🔡 `/items` 🚫 `tags=["items"]` 🔠 *➡ 🛠️* ↩️ 👥 🚮 👫 `APIRouter`.
-
-✋️ 👥 💪 🚮 _🌅_ `tags` 👈 🔜 ✔ 🎯 *➡ 🛠️*, & ➕ `responses` 🎯 👈 *➡ 🛠️*:
-
-```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
-
-/// tip
-
-👉 🏁 ➡ 🛠️ 🔜 ✔️ 🌀 🔖: `["items", "custom"]`.
-
- & ⚫️ 🔜 ✔️ 👯♂️ 📨 🧾, 1️⃣ `404` & 1️⃣ `403`.
-
-///
-
-## 👑 `FastAPI`
-
-🔜, ➡️ 👀 🕹 `app/main.py`.
-
-📥 🌐❔ 👆 🗄 & ⚙️ 🎓 `FastAPI`.
-
-👉 🔜 👑 📁 👆 🈸 👈 👔 🌐 👯♂️.
-
-& 🏆 👆 ⚛ 🔜 🔜 🖖 🚮 👍 🎯 🕹, 👑 📁 🔜 🙅.
-
-### 🗄 `FastAPI`
-
-👆 🗄 & ✍ `FastAPI` 🎓 🛎.
-
-& 👥 💪 📣 [🌐 🔗](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!}
-```
-
-### 🗄 `APIRouter`
-
-🔜 👥 🗄 🎏 🔁 👈 ✔️ `APIRouter`Ⓜ:
-
-```Python hl_lines="5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
-
-📁 `app/routers/users.py` & `app/routers/items.py` 🔁 👈 🍕 🎏 🐍 📦 `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`). 👉 🎏 1️⃣ 👥 ✍ 📁 `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
-```
-
-💡 🌅 🔃 🐍 📦 & 🕹, ✍ 🛂 🐍 🧾 🔃 🕹.
-
-///
-
-### ❎ 📛 💥
-
-👥 🏭 🔁 `items` 🔗, ↩️ 🏭 🚮 🔢 `router`.
-
-👉 ↩️ 👥 ✔️ ➕1️⃣ 🔢 📛 `router` 🔁 `users`.
-
-🚥 👥 ✔️ 🗄 1️⃣ ⏮️ 🎏, 💖:
-
-```Python
-from .routers.items import router
-from .routers.users import router
-```
-
-`router` ⚪️➡️ `users` 🔜 📁 1️⃣ ⚪️➡️ `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`, 👥 💚 🔐 ⚫️ ⏮️ `dependencies` 👥 ⏪ ✔️ 👉 🏗, & 👥 💚 🔌 `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`Ⓜ 🚫 "🗻", 👫 🚫 👽 ⚪️➡️ 🎂 🈸.
-
-👉 ↩️ 👥 💚 🔌 👫 *➡ 🛠️* 🗄 🔗 & 👩💻 🔢.
-
-👥 🚫🔜 ❎ 👫 & "🗻" 👫 ➡ 🎂, *➡ 🛠️* "🖖" (🏤-✍), 🚫 🔌 🔗.
-
-///
-
-## ✅ 🏧 🛠️ 🩺
-
-🔜, 🏃 `uvicorn`, ⚙️ 🕹 `app.main` & 🔢 `app`:
-
-
-
-## 🔌 🎏 📻 💗 🕰 ⏮️ 🎏 `prefix`
-
-👆 💪 ⚙️ `.include_router()` 💗 🕰 ⏮️ *🎏* 📻 ⚙️ 🎏 🔡.
-
-👉 💪 ⚠, 🖼, 🎦 🎏 🛠️ 🔽 🎏 🔡, ✅ `/api/v1` & `/api/latest`.
-
-👉 🏧 ⚙️ 👈 👆 5️⃣📆 🚫 🤙 💪, ✋️ ⚫️ 📤 💼 👆.
-
-## 🔌 `APIRouter` ➕1️⃣
-
-🎏 🌌 👆 💪 🔌 `APIRouter` `FastAPI` 🈸, 👆 💪 🔌 `APIRouter` ➕1️⃣ `APIRouter` ⚙️:
-
-```Python
-router.include_router(other_router)
-```
-
-⚒ 💭 👆 ⚫️ ⏭ 🔌 `router` `FastAPI` 📱, 👈 *➡ 🛠️* ⚪️➡️ `other_router` 🔌.
diff --git a/docs/em/docs/tutorial/body-fields.md b/docs/em/docs/tutorial/body-fields.md
deleted file mode 100644
index f202284b5..000000000
--- a/docs/em/docs/tutorial/body-fields.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# 💪 - 🏑
-
-🎏 🌌 👆 💪 📣 🌖 🔬 & 🗃 *➡ 🛠️ 🔢* 🔢 ⏮️ `Query`, `Path` & `Body`, 👆 💪 📣 🔬 & 🗃 🔘 Pydantic 🏷 ⚙️ Pydantic `Field`.
-
-## 🗄 `Field`
-
-🥇, 👆 ✔️ 🗄 ⚫️:
-
-{* ../../docs_src/body_fields/tutorial001.py hl[4] *}
-
-/// warning
-
-👀 👈 `Field` 🗄 🔗 ⚪️➡️ `pydantic`, 🚫 ⚪️➡️ `fastapi` 🌐 🎂 (`Query`, `Path`, `Body`, ♒️).
-
-///
-
-## 📣 🏷 🔢
-
-👆 💪 ⤴️ ⚙️ `Field` ⏮️ 🏷 🔢:
-
-{* ../../docs_src/body_fields/tutorial001.py hl[11:14] *}
-
-`Field` 👷 🎏 🌌 `Query`, `Path` & `Body`, ⚫️ ✔️ 🌐 🎏 🔢, ♒️.
-
-/// note | 📡 ℹ
-
-🤙, `Query`, `Path` & 🎏 👆 🔜 👀 ⏭ ✍ 🎚 🏿 ⚠ `Param` 🎓, ❔ ⚫️ 🏿 Pydantic `FieldInfo` 🎓.
-
- & Pydantic `Field` 📨 👐 `FieldInfo` 👍.
-
-`Body` 📨 🎚 🏿 `FieldInfo` 🔗. & 📤 🎏 👆 🔜 👀 ⏪ 👈 🏿 `Body` 🎓.
-
-💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-
-///
-
-/// tip
-
-👀 ❔ 🔠 🏷 🔢 ⏮️ 🆎, 🔢 💲 & `Field` ✔️ 🎏 📊 *➡ 🛠️ 🔢* 🔢, ⏮️ `Field` ↩️ `Path`, `Query` & `Body`.
-
-///
-
-## 🚮 ➕ ℹ
-
-👆 💪 📣 ➕ ℹ `Field`, `Query`, `Body`, ♒️. & ⚫️ 🔜 🔌 🏗 🎻 🔗.
-
-👆 🔜 💡 🌅 🔃 ❎ ➕ ℹ ⏪ 🩺, 🕐❔ 🏫 📣 🖼.
-
-/// warning
-
-➕ 🔑 🚶♀️ `Field` 🔜 🎁 📉 🗄 🔗 👆 🈸.
-👫 🔑 5️⃣📆 🚫 🎯 🍕 🗄 🔧, 🗄 🧰, 🖼 [🗄 💳](https://validator.swagger.io/), 5️⃣📆 🚫 👷 ⏮️ 👆 🏗 🔗.
-
-///
-
-## 🌃
-
-👆 💪 ⚙️ Pydantic `Field` 📣 ➕ 🔬 & 🗃 🏷 🔢.
-
-👆 💪 ⚙️ ➕ 🇨🇻 ❌ 🚶♀️ 🌖 🎻 🔗 🗃.
diff --git a/docs/em/docs/tutorial/body-multiple-params.md b/docs/em/docs/tutorial/body-multiple-params.md
deleted file mode 100644
index 3a2f2bd54..000000000
--- a/docs/em/docs/tutorial/body-multiple-params.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# 💪 - 💗 🔢
-
-🔜 👈 👥 ✔️ 👀 ❔ ⚙️ `Path` & `Query`, ➡️ 👀 🌅 🏧 ⚙️ 📨 💪 📄.
-
-## 🌀 `Path`, `Query` & 💪 🔢
-
-🥇, ↗️, 👆 💪 🌀 `Path`, `Query` & 📨 💪 🔢 📄 ➡ & **FastAPI** 🔜 💭 ⚫️❔.
-
-& 👆 💪 📣 💪 🔢 📦, ⚒ 🔢 `None`:
-
-{* ../../docs_src/body_multiple_params/tutorial001.py hl[19:21] *}
-
-/// note
-
-👀 👈, 👉 💼, `item` 👈 🔜 ✊ ⚪️➡️ 💪 📦. ⚫️ ✔️ `None` 🔢 💲.
-
-///
-
-## 💗 💪 🔢
-
-⏮️ 🖼, *➡ 🛠️* 🔜 ⌛ 🎻 💪 ⏮️ 🔢 `Item`, 💖:
-
-```JSON
-{
- "name": "Foo",
- "description": "The pretender",
- "price": 42.0,
- "tax": 3.2
-}
-```
-
-✋️ 👆 💪 📣 💗 💪 🔢, ✅ `item` & `user`:
-
-{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *}
-
-👉 💼, **FastAPI** 🔜 👀 👈 📤 🌅 🌘 1️⃣ 💪 🔢 🔢 (2️⃣ 🔢 👈 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`.
-
-⚫️ 🔜 🎭 🔬 ⚗ 💽, & 🔜 📄 ⚫️ 💖 👈 🗄 🔗 & 🏧 🩺.
-
-## ⭐ 💲 💪
-
-🎏 🌌 📤 `Query` & `Path` 🔬 ➕ 💽 🔢 & ➡ 🔢, **FastAPI** 🚚 🌓 `Body`.
-
-🖼, ↔ ⏮️ 🏷, 👆 💪 💭 👈 👆 💚 ✔️ ➕1️⃣ 🔑 `importance` 🎏 💪, 🥈 `item` & `user`.
-
-🚥 👆 📣 ⚫️, ↩️ ⚫️ ⭐ 💲, **FastAPI** 🔜 🤔 👈 ⚫️ 🔢 🔢.
-
-✋️ 👆 💪 💡 **FastAPI** 😥 ⚫️ ➕1️⃣ 💪 🔑 ⚙️ `Body`:
-
-{* ../../docs_src/body_multiple_params/tutorial003.py hl[22] *}
-
-👉 💼, **FastAPI** 🔜 ⌛ 💪 💖:
-
-```JSON
-{
- "item": {
- "name": "Foo",
- "description": "The pretender",
- "price": 42.0,
- "tax": 3.2
- },
- "user": {
- "username": "dave",
- "full_name": "Dave Grohl"
- },
- "importance": 5
-}
-```
-
-🔄, ⚫️ 🔜 🗜 📊 🆎, ✔, 📄, ♒️.
-
-## 💗 💪 = & 🔢
-
-↗️, 👆 💪 📣 🌖 🔢 🔢 🕐❔ 👆 💪, 🌖 🙆 💪 🔢.
-
-, 🔢, ⭐ 💲 🔬 🔢 🔢, 👆 🚫 ✔️ 🎯 🚮 `Query`, 👆 💪:
-
-```Python
-q: Union[str, None] = None
-```
-
-⚖️ 🐍 3️⃣.1️⃣0️⃣ & 🔛:
-
-```Python
-q: str | None = None
-```
-
-🖼:
-
-{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *}
-
-/// info
-
-`Body` ✔️ 🌐 🎏 ➕ 🔬 & 🗃 🔢 `Query`,`Path` & 🎏 👆 🔜 👀 ⏪.
-
-///
-
-## ⏯ 👁 💪 🔢
-
-➡️ 💬 👆 🕴 ✔️ 👁 `item` 💪 🔢 ⚪️➡️ Pydantic 🏷 `Item`.
-
-🔢, **FastAPI** 🔜 ⤴️ ⌛ 🚮 💪 🔗.
-
-✋️ 🚥 👆 💚 ⚫️ ⌛ 🎻 ⏮️ 🔑 `item` & 🔘 ⚫️ 🏷 🎚, ⚫️ 🔨 🕐❔ 👆 📣 ➕ 💪 🔢, 👆 💪 ⚙️ 🎁 `Body` 🔢 `embed`:
-
-```Python
-item: Item = Body(embed=True)
-```
-
-:
-
-{* ../../docs_src/body_multiple_params/tutorial005.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
-}
-```
-
-## 🌃
-
-👆 💪 🚮 💗 💪 🔢 👆 *➡ 🛠️ 🔢*, ✋️ 📨 💪 🕴 ✔️ 👁 💪.
-
-✋️ **FastAPI** 🔜 🍵 ⚫️, 🤝 👆 ☑ 📊 👆 🔢, & ✔ & 📄 ☑ 🔗 *➡ 🛠️*.
-
-👆 💪 📣 ⭐ 💲 📨 🍕 💪.
-
-& 👆 💪 💡 **FastAPI** ⏯ 💪 🔑 🕐❔ 📤 🕴 👁 🔢 📣.
diff --git a/docs/em/docs/tutorial/body-nested-models.md b/docs/em/docs/tutorial/body-nested-models.md
deleted file mode 100644
index 6c8d5a610..000000000
--- a/docs/em/docs/tutorial/body-nested-models.md
+++ /dev/null
@@ -1,247 +0,0 @@
-# 💪 - 🔁 🏷
-
-⏮️ **FastAPI**, 👆 💪 🔬, ✔, 📄, & ⚙️ 🎲 🙇 🐦 🏷 (👏 Pydantic).
-
-## 📇 🏑
-
-👆 💪 🔬 🔢 🏾. 🖼, 🐍 `list`:
-
-{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
-
-👉 🔜 ⚒ `tags` 📇, 👐 ⚫️ 🚫 📣 🆎 🔣 📇.
-
-## 📇 🏑 ⏮️ 🆎 🔢
-
-✋️ 🐍 ✔️ 🎯 🌌 📣 📇 ⏮️ 🔗 🆎, ⚖️ "🆎 🔢":
-
-### 🗄 ⌨ `List`
-
-🐍 3️⃣.9️⃣ & 🔛 👆 💪 ⚙️ 🐩 `list` 📣 👫 🆎 ✍ 👥 🔜 👀 🔛. 👶
-
-✋️ 🐍 ⏬ ⏭ 3️⃣.9️⃣ (3️⃣.6️⃣ & 🔛), 👆 🥇 💪 🗄 `List` ⚪️➡️ 🐩 🐍 `typing` 🕹:
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
-### 📣 `list` ⏮️ 🆎 🔢
-
-📣 🆎 👈 ✔️ 🆎 🔢 (🔗 🆎), 💖 `list`, `dict`, `tuple`:
-
-* 🚥 👆 🐍 ⏬ 🔅 🌘 3️⃣.9️⃣, 🗄 👫 🌓 ⏬ ⚪️➡️ `typing` 🕹
-* 🚶♀️ 🔗 🆎(Ⓜ) "🆎 🔢" ⚙️ ⬜ 🗜: `[` & `]`
-
-🐍 3️⃣.9️⃣ ⚫️ 🔜:
-
-```Python
-my_list: list[str]
-```
-
-⏬ 🐍 ⏭ 3️⃣.9️⃣, ⚫️ 🔜:
-
-```Python
-from typing import List
-
-my_list: List[str]
-```
-
-👈 🌐 🐩 🐍 ❕ 🆎 📄.
-
-⚙️ 👈 🎏 🐩 ❕ 🏷 🔢 ⏮️ 🔗 🆎.
-
-, 👆 🖼, 👥 💪 ⚒ `tags` 🎯 "📇 🎻":
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
-
-## ⚒ 🆎
-
-✋️ ⤴️ 👥 💭 🔃 ⚫️, & 🤔 👈 🔖 🚫🔜 🚫 🔁, 👫 🔜 🎲 😍 🎻.
-
-& 🐍 ✔️ 🎁 💽 🆎 ⚒ 😍 🏬, `set`.
-
-⤴️ 👥 💪 📣 `tags` ⚒ 🎻:
-
-{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
-
-⏮️ 👉, 🚥 👆 📨 📨 ⏮️ ❎ 📊, ⚫️ 🔜 🗜 ⚒ 😍 🏬.
-
-& 🕐❔ 👆 🔢 👈 📊, 🚥 ℹ ✔️ ❎, ⚫️ 🔜 🔢 ⚒ 😍 🏬.
-
-& ⚫️ 🔜 ✍ / 📄 ➡️ 💁♂️.
-
-## 🐦 🏷
-
-🔠 🔢 Pydantic 🏷 ✔️ 🆎.
-
-✋️ 👈 🆎 💪 ⚫️ ➕1️⃣ Pydantic 🏷.
-
-, 👆 💪 📣 🙇 🐦 🎻 "🎚" ⏮️ 🎯 🔢 📛, 🆎 & 🔬.
-
-🌐 👈, 🎲 🐦.
-
-### 🔬 📊
-
-🖼, 👥 💪 🔬 `Image` 🏷:
-
-{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
-
-### ⚙️ 📊 🆎
-
-& ⤴️ 👥 💪 ⚙️ ⚫️ 🆎 🔢:
-
-{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
-
-👉 🔜 ⛓ 👈 **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` 🏑, 👥 💪 📣 ⚫️ ↩️ `str`, Pydantic `HttpUrl`:
-
-{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
-
-🎻 🔜 ✅ ☑ 📛, & 📄 🎻 🔗 / 🗄 ✅.
-
-## 🔢 ⏮️ 📇 📊
-
-👆 💪 ⚙️ Pydantic 🏷 🏾 `list`, `set`, ♒️:
-
-{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
-
-👉 🔜 ⌛ (🗜, ✔, 📄, ♒️) 🎻 💪 💖:
-
-```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.py hl[9,14,20,23,27] *}
-
-/// info
-
-👀 ❔ `Offer` ✔️ 📇 `Item`Ⓜ, ❔ 🔄 ✔️ 📦 📇 `Image`Ⓜ
-
-///
-
-## 💪 😁 📇
-
-🚥 🔝 🎚 💲 🎻 💪 👆 ⌛ 🎻 `array` (🐍 `list`), 👆 💪 📣 🆎 🔢 🔢, 🎏 Pydantic 🏷:
-
-```Python
-images: List[Image]
-```
-
-⚖️ 🐍 3️⃣.9️⃣ & 🔛:
-
-```Python
-images: list[Image]
-```
-
-:
-
-{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
-
-## 👨🎨 🐕🦺 🌐
-
-& 👆 🤚 👨🎨 🐕🦺 🌐.
-
-🏬 🔘 📇:
-
-
-
-👆 🚫 🚫 🤚 👉 😇 👨🎨 🐕🦺 🚥 👆 👷 🔗 ⏮️ `dict` ↩️ Pydantic 🏷.
-
-✋️ 👆 🚫 ✔️ 😟 🔃 👫 👯♂️, 📨 #️⃣ 🗜 🔁 & 👆 🔢 🗜 🔁 🎻 💁♂️.
-
-## 💪 ❌ `dict`Ⓜ
-
-👆 💪 📣 💪 `dict` ⏮️ 🔑 🆎 & 💲 🎏 🆎.
-
-🍵 ✔️ 💭 ⏪ ⚫️❔ ☑ 🏑/🔢 📛 (🔜 💼 ⏮️ Pydantic 🏷).
-
-👉 🔜 ⚠ 🚥 👆 💚 📨 🔑 👈 👆 🚫 ⏪ 💭.
-
----
-
-🎏 ⚠ 💼 🕐❔ 👆 💚 ✔️ 🔑 🎏 🆎, ✅ `int`.
-
-👈 ⚫️❔ 👥 🔜 👀 📥.
-
-👉 💼, 👆 🔜 🚫 🙆 `dict` 📏 ⚫️ ✔️ `int` 🔑 ⏮️ `float` 💲:
-
-{* ../../docs_src/body_nested_models/tutorial009.py hl[9] *}
-
-/// tip
-
-✔️ 🤯 👈 🎻 🕴 🐕🦺 `str` 🔑.
-
-✋️ Pydantic ✔️ 🏧 💽 🛠️.
-
-👉 ⛓ 👈, ✋️ 👆 🛠️ 👩💻 💪 🕴 📨 🎻 🔑, 📏 👈 🎻 🔌 😁 🔢, Pydantic 🔜 🗜 👫 & ✔ 👫.
-
- & `dict` 👆 📨 `weights` 🔜 🤙 ✔️ `int` 🔑 & `float` 💲.
-
-///
-
-## 🌃
-
-⏮️ **FastAPI** 👆 ✔️ 🔆 💪 🚚 Pydantic 🏷, ⏪ 🚧 👆 📟 🙅, 📏 & 😍.
-
-✋️ ⏮️ 🌐 💰:
-
-* 👨🎨 🐕🦺 (🛠️ 🌐 ❗)
-* 💽 🛠️ (.Ⓜ.. ✍ / 🛠️)
-* 💽 🔬
-* 🔗 🧾
-* 🏧 🩺
diff --git a/docs/em/docs/tutorial/body-updates.md b/docs/em/docs/tutorial/body-updates.md
deleted file mode 100644
index 7e2fbfaf7..000000000
--- a/docs/em/docs/tutorial/body-updates.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# 💪 - ℹ
-
-## ℹ ❎ ⏮️ `PUT`
-
-ℹ 🏬 👆 💪 ⚙️ 🇺🇸🔍 `PUT` 🛠️.
-
-👆 💪 ⚙️ `jsonable_encoder` 🗜 🔢 💽 📊 👈 💪 🏪 🎻 (✅ ⏮️ ☁ 💽). 🖼, 🏭 `datetime` `str`.
-
-{* ../../docs_src/body_updates/tutorial001.py hl[30:35] *}
-
-`PUT` ⚙️ 📨 💽 👈 🔜 ❎ ♻ 💽.
-
-### ⚠ 🔃 ❎
-
-👈 ⛓ 👈 🚥 👆 💚 ℹ 🏬 `bar` ⚙️ `PUT` ⏮️ 💪 ⚗:
-
-```Python
-{
- "name": "Barz",
- "price": 3,
- "description": None,
-}
-```
-
-↩️ ⚫️ 🚫 🔌 ⏪ 🏪 🔢 `"tax": 20.2`, 🔢 🏷 🔜 ✊ 🔢 💲 `"tax": 10.5`.
-
-& 📊 🔜 🖊 ⏮️ 👈 "🆕" `tax` `10.5`.
-
-## 🍕 ℹ ⏮️ `PATCH`
-
-👆 💪 ⚙️ 🇺🇸🔍 `PATCH` 🛠️ *🍕* ℹ 💽.
-
-👉 ⛓ 👈 👆 💪 📨 🕴 💽 👈 👆 💚 ℹ, 🍂 🎂 🐣.
-
-/// note
-
-`PATCH` 🌘 🛎 ⚙️ & 💭 🌘 `PUT`.
-
- & 📚 🏉 ⚙️ 🕴 `PUT`, 🍕 ℹ.
-
-👆 **🆓** ⚙️ 👫 👐 👆 💚, **FastAPI** 🚫 🚫 🙆 🚫.
-
-✋️ 👉 🦮 🎦 👆, 🌖 ⚖️ 🌘, ❔ 👫 🎯 ⚙️.
-
-///
-
-### ⚙️ Pydantic `exclude_unset` 🔢
-
-🚥 👆 💚 📨 🍕 ℹ, ⚫️ 📶 ⚠ ⚙️ 🔢 `exclude_unset` Pydantic 🏷 `.dict()`.
-
-💖 `item.dict(exclude_unset=True)`.
-
-👈 🔜 🏗 `dict` ⏮️ 🕴 💽 👈 ⚒ 🕐❔ 🏗 `item` 🏷, 🚫 🔢 💲.
-
-⤴️ 👆 💪 ⚙️ 👉 🏗 `dict` ⏮️ 🕴 💽 👈 ⚒ (📨 📨), 🚫 🔢 💲:
-
-{* ../../docs_src/body_updates/tutorial002.py hl[34] *}
-
-### ⚙️ Pydantic `update` 🔢
-
-🔜, 👆 💪 ✍ 📁 ♻ 🏷 ⚙️ `.copy()`, & 🚶♀️ `update` 🔢 ⏮️ `dict` ⚗ 💽 ℹ.
-
-💖 `stored_item_model.copy(update=update_data)`:
-
-{* ../../docs_src/body_updates/tutorial002.py hl[35] *}
-
-### 🍕 ℹ 🌃
-
-📄, ✔ 🍕 ℹ 👆 🔜:
-
-* (⚗) ⚙️ `PATCH` ↩️ `PUT`.
-* 🗃 🏪 💽.
-* 🚮 👈 💽 Pydantic 🏷.
-* 🏗 `dict` 🍵 🔢 💲 ⚪️➡️ 🔢 🏷 (⚙️ `exclude_unset`).
- * 👉 🌌 👆 💪 ℹ 🕴 💲 🤙 ⚒ 👩💻, ↩️ 🔐 💲 ⏪ 🏪 ⏮️ 🔢 💲 👆 🏷.
-* ✍ 📁 🏪 🏷, 🛠️ ⚫️ 🔢 ⏮️ 📨 🍕 ℹ (⚙️ `update` 🔢).
-* 🗜 📁 🏷 🕳 👈 💪 🏪 👆 💽 (🖼, ⚙️ `jsonable_encoder`).
- * 👉 ⭐ ⚙️ 🏷 `.dict()` 👩🔬 🔄, ✋️ ⚫️ ⚒ 💭 (& 🗜) 💲 💽 🆎 👈 💪 🗜 🎻, 🖼, `datetime` `str`.
-* 🖊 💽 👆 💽.
-* 📨 ℹ 🏷.
-
-{* ../../docs_src/body_updates/tutorial002.py hl[30:37] *}
-
-/// tip
-
-👆 💪 🤙 ⚙️ 👉 🎏 ⚒ ⏮️ 🇺🇸🔍 `PUT` 🛠️.
-
-✋️ 🖼 📥 ⚙️ `PATCH` ↩️ ⚫️ ✍ 👫 ⚙️ 💼.
-
-///
-
-/// note
-
-👀 👈 🔢 🏷 ✔.
-
-, 🚥 👆 💚 📨 🍕 ℹ 👈 💪 🚫 🌐 🔢, 👆 💪 ✔️ 🏷 ⏮️ 🌐 🔢 ™ 📦 (⏮️ 🔢 💲 ⚖️ `None`).
-
-🔬 ⚪️➡️ 🏷 ⏮️ 🌐 📦 💲 **ℹ** & 🏷 ⏮️ ✔ 💲 **🏗**, 👆 💪 ⚙️ 💭 🔬 [➕ 🏷](extra-models.md){.internal-link target=_blank}.
-
-///
diff --git a/docs/em/docs/tutorial/body.md b/docs/em/docs/tutorial/body.md
deleted file mode 100644
index 09e1d7cca..000000000
--- a/docs/em/docs/tutorial/body.md
+++ /dev/null
@@ -1,162 +0,0 @@
-# 📨 💪
-
-🕐❔ 👆 💪 📨 📊 ⚪️➡️ 👩💻 (➡️ 💬, 🖥) 👆 🛠️, 👆 📨 ⚫️ **📨 💪**.
-
-**📨** 💪 📊 📨 👩💻 👆 🛠️. **📨** 💪 💽 👆 🛠️ 📨 👩💻.
-
-👆 🛠️ 🌖 🕧 ✔️ 📨 **📨** 💪. ✋️ 👩💻 🚫 🎯 💪 📨 **📨** 💪 🌐 🕰.
-
-📣 **📨** 💪, 👆 ⚙️ Pydantic 🏷 ⏮️ 🌐 👫 🏋️ & 💰.
-
-/// info
-
-📨 💽, 👆 🔜 ⚙️ 1️⃣: `POST` (🌅 ⚠), `PUT`, `DELETE` ⚖️ `PATCH`.
-
-📨 💪 ⏮️ `GET` 📨 ✔️ ⚠ 🎭 🔧, 👐, ⚫️ 🐕🦺 FastAPI, 🕴 📶 🏗/😕 ⚙️ 💼.
-
-⚫️ 🚫, 🎓 🩺 ⏮️ 🦁 🎚 🏆 🚫 🎦 🧾 💪 🕐❔ ⚙️ `GET`, & 🗳 🖕 💪 🚫 🐕🦺 ⚫️.
-
-///
-
-## 🗄 Pydantic `BaseModel`
-
-🥇, 👆 💪 🗄 `BaseModel` ⚪️➡️ `pydantic`:
-
-{* ../../docs_src/body/tutorial001.py hl[4] *}
-
-## ✍ 👆 💽 🏷
-
-⤴️ 👆 📣 👆 💽 🏷 🎓 👈 😖 ⚪️➡️ `BaseModel`.
-
-⚙️ 🐩 🐍 🆎 🌐 🔢:
-
-{* ../../docs_src/body/tutorial001.py hl[7:11] *}
-
-🎏 🕐❔ 📣 🔢 🔢, 🕐❔ 🏷 🔢 ✔️ 🔢 💲, ⚫️ 🚫 ✔. ⏪, ⚫️ ✔. ⚙️ `None` ⚒ ⚫️ 📦.
-
-🖼, 👉 🏷 🔛 📣 🎻 "`object`" (⚖️ 🐍 `dict`) 💖:
-
-```JSON
-{
- "name": "Foo",
- "description": "An optional description",
- "price": 45.2,
- "tax": 3.5
-}
-```
-
-... `description` & `tax` 📦 (⏮️ 🔢 💲 `None`), 👉 🎻 "`object`" 🔜 ☑:
-
-```JSON
-{
- "name": "Foo",
- "price": 45.2
-}
-```
-
-## 📣 ⚫️ 🔢
-
-🚮 ⚫️ 👆 *➡ 🛠️*, 📣 ⚫️ 🎏 🌌 👆 📣 ➡ & 🔢 🔢:
-
-{* ../../docs_src/body/tutorial001.py hl[18] *}
-
-...& 📣 🚮 🆎 🏷 👆 ✍, `Item`.
-
-## 🏁
-
-⏮️ 👈 🐍 🆎 📄, **FastAPI** 🔜:
-
-* ✍ 💪 📨 🎻.
-* 🗜 🔗 🆎 (🚥 💪).
-* ✔ 💽.
- * 🚥 💽 ❌, ⚫️ 🔜 📨 👌 & 🆑 ❌, ☠️ ⚫️❔ 🌐❔ & ⚫️❔ ❌ 📊.
-* 🤝 👆 📨 📊 🔢 `item`.
- * 👆 📣 ⚫️ 🔢 🆎 `Item`, 👆 🔜 ✔️ 🌐 👨🎨 🐕🦺 (🛠️, ♒️) 🌐 🔢 & 👫 🆎.
-* 🏗 🎻 🔗 🔑 👆 🏷, 👆 💪 ⚙️ 👫 🙆 🙆 👆 💖 🚥 ⚫️ ⚒ 🔑 👆 🏗.
-* 👈 🔗 🔜 🍕 🏗 🗄 🔗, & ⚙️ 🏧 🧾 ⚜.
-
-## 🏧 🩺
-
-🎻 🔗 👆 🏷 🔜 🍕 👆 🗄 🏗 🔗, & 🔜 🎦 🎓 🛠️ 🩺:
-
-
-
-& 🔜 ⚙️ 🛠️ 🩺 🔘 🔠 *➡ 🛠️* 👈 💪 👫:
-
-
-
-## 👨🎨 🐕🦺
-
-👆 👨🎨, 🔘 👆 🔢 👆 🔜 🤚 🆎 🔑 & 🛠️ 🌐 (👉 🚫🔜 🔨 🚥 👆 📨 `dict` ↩️ Pydantic 🏷):
-
-
-
-👆 🤚 ❌ ✅ ❌ 🆎 🛠️:
-
-
-
-👉 🚫 🤞, 🎂 🛠️ 🏗 🤭 👈 🔧.
-
-& ⚫️ 🙇 💯 🔧 🌓, ⏭ 🙆 🛠️, 🚚 ⚫️ 🔜 👷 ⏮️ 🌐 👨🎨.
-
-📤 🔀 Pydantic ⚫️ 🐕🦺 👉.
-
-⏮️ 🖼 ✊ ⏮️ 🎙 🎙 📟.
-
-✋️ 👆 🔜 🤚 🎏 👨🎨 🐕🦺 ⏮️ 🗒 & 🌅 🎏 🐍 👨🎨:
-
-
-
-/// tip
-
-🚥 👆 ⚙️ 🗒 👆 👨🎨, 👆 💪 ⚙️ Pydantic 🗒 📁.
-
-⚫️ 📉 👨🎨 🐕🦺 Pydantic 🏷, ⏮️:
-
-* 🚘-🛠️
-* 🆎 ✅
-* 🛠️
-* 🔎
-* 🔬
-
-///
-
-## ⚙️ 🏷
-
-🔘 🔢, 👆 💪 🔐 🌐 🔢 🏷 🎚 🔗:
-
-{* ../../docs_src/body/tutorial002.py hl[21] *}
-
-## 📨 💪 ➕ ➡ 🔢
-
-👆 💪 📣 ➡ 🔢 & 📨 💪 🎏 🕰.
-
-**FastAPI** 🔜 🤔 👈 🔢 🔢 👈 🏏 ➡ 🔢 🔜 **✊ ⚪️➡️ ➡**, & 👈 🔢 🔢 👈 📣 Pydantic 🏷 🔜 **✊ ⚪️➡️ 📨 💪**.
-
-{* ../../docs_src/body/tutorial003.py hl[17:18] *}
-
-## 📨 💪 ➕ ➡ ➕ 🔢 🔢
-
-👆 💪 📣 **💪**, **➡** & **🔢** 🔢, 🌐 🎏 🕰.
-
-**FastAPI** 🔜 🤔 🔠 👫 & ✊ 📊 ⚪️➡️ ☑ 🥉.
-
-{* ../../docs_src/body/tutorial004.py hl[18] *}
-
-🔢 🔢 🔜 🤔 ⏩:
-
-* 🚥 🔢 📣 **➡**, ⚫️ 🔜 ⚙️ ➡ 🔢.
-* 🚥 🔢 **⭐ 🆎** (💖 `int`, `float`, `str`, `bool`, ♒️) ⚫️ 🔜 🔬 **🔢** 🔢.
-* 🚥 🔢 📣 🆎 **Pydantic 🏷**, ⚫️ 🔜 🔬 📨 **💪**.
-
-/// note
-
-FastAPI 🔜 💭 👈 💲 `q` 🚫 ✔ ↩️ 🔢 💲 `= None`.
-
- `Union` `Union[str, None]` 🚫 ⚙️ FastAPI, ✋️ 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
-
-///
-
-## 🍵 Pydantic
-
-🚥 👆 🚫 💚 ⚙️ Pydantic 🏷, 👆 💪 ⚙️ **💪** 🔢. 👀 🩺 [💪 - 💗 🔢: ⭐ 💲 💪](body-multiple-params.md#_2){.internal-link target=_blank}.
diff --git a/docs/em/docs/tutorial/cookie-params.md b/docs/em/docs/tutorial/cookie-params.md
deleted file mode 100644
index 4699fe2a5..000000000
--- a/docs/em/docs/tutorial/cookie-params.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 🍪 🔢
-
-👆 💪 🔬 🍪 🔢 🎏 🌌 👆 🔬 `Query` & `Path` 🔢.
-
-## 🗄 `Cookie`
-
-🥇 🗄 `Cookie`:
-
-{* ../../docs_src/cookie_params/tutorial001.py hl[3] *}
-
-## 📣 `Cookie` 🔢
-
-⤴️ 📣 🍪 🔢 ⚙️ 🎏 📊 ⏮️ `Path` & `Query`.
-
-🥇 💲 🔢 💲, 👆 💪 🚶♀️ 🌐 ➕ 🔬 ⚖️ ✍ 🔢:
-
-{* ../../docs_src/cookie_params/tutorial001.py hl[9] *}
-
-/// note | 📡 ℹ
-
-`Cookie` "👭" 🎓 `Path` & `Query`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
-
-✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `Cookie` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-
-///
-
-/// info
-
-📣 🍪, 👆 💪 ⚙️ `Cookie`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢.
-
-///
-
-## 🌃
-
-📣 🍪 ⏮️ `Cookie`, ⚙️ 🎏 ⚠ ⚓ `Query` & `Path`.
diff --git a/docs/em/docs/tutorial/cors.md b/docs/em/docs/tutorial/cors.md
deleted file mode 100644
index 44ab4adc5..000000000
--- a/docs/em/docs/tutorial/cors.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# ⚜ (✖️-🇨🇳 ℹ 🤝)
-
-⚜ ⚖️ "✖️-🇨🇳 ℹ 🤝" 🔗 ⚠ 🕐❔ 🕸 🏃♂ 🖥 ✔️ 🕸 📟 👈 🔗 ⏮️ 👩💻, & 👩💻 🎏 "🇨🇳" 🌘 🕸.
-
-## 🇨🇳
-
-🇨🇳 🌀 🛠️ (`http`, `https`), 🆔 (`myapp.com`, `localhost`, `localhost.tiangolo.com`), & ⛴ (`80`, `443`, `8080`).
-
-, 🌐 👫 🎏 🇨🇳:
-
-* `http://localhost`
-* `https://localhost`
-* `http://localhost:8080`
-
-🚥 👫 🌐 `localhost`, 👫 ⚙️ 🎏 🛠️ ⚖️ ⛴,, 👫 🎏 "🇨🇳".
-
-## 🔁
-
-, ➡️ 💬 👆 ✔️ 🕸 🏃 👆 🖥 `http://localhost:8080`, & 🚮 🕸 🔄 🔗 ⏮️ 👩💻 🏃 `http://localhost` (↩️ 👥 🚫 ✔ ⛴, 🖥 🔜 🤔 🔢 ⛴ `80`).
-
-⤴️, 🖥 🔜 📨 🇺🇸🔍 `OPTIONS` 📨 👩💻, & 🚥 👩💻 📨 ☑ 🎚 ✔ 📻 ⚪️➡️ 👉 🎏 🇨🇳 (`http://localhost:8080`) ⤴️ 🖥 🔜 ➡️ 🕸 🕸 📨 🚮 📨 👩💻.
-
-🏆 👉, 👩💻 🔜 ✔️ 📇 "✔ 🇨🇳".
-
-👉 💼, ⚫️ 🔜 ✔️ 🔌 `http://localhost:8080` 🕸 👷 ☑.
-
-## 🃏
-
-⚫️ 💪 📣 📇 `"*"` ("🃏") 💬 👈 🌐 ✔.
-
-✋️ 👈 🔜 🕴 ✔ 🎯 🆎 📻, 🚫 🌐 👈 🔌 🎓: 🍪, ✔ 🎚 💖 📚 ⚙️ ⏮️ 📨 🤝, ♒️.
-
-, 🌐 👷 ☑, ⚫️ 👻 ✔ 🎯 ✔ 🇨🇳.
-
-## ⚙️ `CORSMiddleware`
-
-👆 💪 🔗 ⚫️ 👆 **FastAPI** 🈸 ⚙️ `CORSMiddleware`.
-
-* 🗄 `CORSMiddleware`.
-* ✍ 📇 ✔ 🇨🇳 (🎻).
-* 🚮 ⚫️ "🛠️" 👆 **FastAPI** 🈸.
-
-👆 💪 ✔ 🚥 👆 👩💻 ✔:
-
-* 🎓 (✔ 🎚, 🍪, ♒️).
-* 🎯 🇺🇸🔍 👩🔬 (`POST`, `PUT`) ⚖️ 🌐 👫 ⏮️ 🃏 `"*"`.
-* 🎯 🇺🇸🔍 🎚 ⚖️ 🌐 👫 ⏮️ 🃏 `"*"`.
-
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
-
-🔢 🔢 ⚙️ `CORSMiddleware` 🛠️ 🚫 🔢, 👆 🔜 💪 🎯 🛠️ 🎯 🇨🇳, 👩🔬, ⚖️ 🎚, ✔ 🖥 ✔ ⚙️ 👫 ✖️-🆔 🔑.
-
-📄 ❌ 🐕🦺:
-
-* `allow_origins` - 📇 🇨🇳 👈 🔜 ✔ ⚒ ✖️-🇨🇳 📨. 🤶 Ⓜ. `['https://example.org', 'https://www.example.org']`. 👆 💪 ⚙️ `['*']` ✔ 🙆 🇨🇳.
-* `allow_origin_regex` - 🎻 🎻 🏏 🛡 🇨🇳 👈 🔜 ✔ ⚒ ✖️-🇨🇳 📨. ✅ `'https://.*\.example\.org'`.
-* `allow_methods` - 📇 🇺🇸🔍 👩🔬 👈 🔜 ✔ ✖️-🇨🇳 📨. 🔢 `['GET']`. 👆 💪 ⚙️ `['*']` ✔ 🌐 🐩 👩🔬.
-* `allow_headers` - 📇 🇺🇸🔍 📨 🎚 👈 🔜 🐕🦺 ✖️-🇨🇳 📨. 🔢 `[]`. 👆 💪 ⚙️ `['*']` ✔ 🌐 🎚. `Accept`, `Accept-Language`, `Content-Language` & `Content-Type` 🎚 🕧 ✔ 🙅 ⚜ 📨.
-* `allow_credentials` - 🎦 👈 🍪 🔜 🐕🦺 ✖️-🇨🇳 📨. 🔢 `False`. , `allow_origins` 🚫🔜 ⚒ `['*']` 🎓 ✔, 🇨🇳 🔜 ✔.
-* `expose_headers` - 🎦 🙆 📨 🎚 👈 🔜 ⚒ ♿ 🖥. 🔢 `[]`.
-* `max_age` - ⚒ 🔆 🕰 🥈 🖥 💾 ⚜ 📨. 🔢 `600`.
-
-🛠️ 📨 2️⃣ 🎯 🆎 🇺🇸🔍 📨...
-
-### ⚜ 🛫 📨
-
-👉 🙆 `OPTIONS` 📨 ⏮️ `Origin` & `Access-Control-Request-Method` 🎚.
-
-👉 💼 🛠️ 🔜 🆘 📨 📨 & 📨 ⏮️ ☑ ⚜ 🎚, & 👯♂️ `200` ⚖️ `400` 📨 🎓 🎯.
-
-### 🙅 📨
-
-🙆 📨 ⏮️ `Origin` 🎚. 👉 💼 🛠️ 🔜 🚶♀️ 📨 🔘 😐, ✋️ 🔜 🔌 ☑ ⚜ 🎚 🔛 📨.
-
-## 🌅 ℹ
-
-🌖 ℹ 🔃 ⚜, ✅ 🦎 ⚜ 🧾.
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `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
deleted file mode 100644
index 97e61a763..000000000
--- a/docs/em/docs/tutorial/debugging.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# 🛠️
-
-👆 💪 🔗 🕹 👆 👨🎨, 🖼 ⏮️ 🎙 🎙 📟 ⚖️ 🗒.
-
-## 🤙 `uvicorn`
-
-👆 FastAPI 🈸, 🗄 & 🏃 `uvicorn` 🔗:
-
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
-
-### 🔃 `__name__ == "__main__"`
-
-👑 🎯 `__name__ == "__main__"` ✔️ 📟 👈 🛠️ 🕐❔ 👆 📁 🤙 ⏮️:
-
-
-
----
-
-🚥 👆 ⚙️ 🗒, 👆 💪:
-
-* 📂 "🏃" 🍣.
-* 🖊 🎛 "ℹ...".
-* ⤴️ 🔑 🍣 🎦 🆙.
-* 🖊 📁 ℹ (👉 💼, `main.py`).
-
-⚫️ 🔜 ⤴️ ▶️ 💽 ⏮️ 👆 **FastAPI** 📟, ⛔️ 👆 0️⃣, ♒️.
-
-📥 ❔ ⚫️ 💪 👀:
-
-
diff --git a/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md
deleted file mode 100644
index 41938bc7b..000000000
--- a/docs/em/docs/tutorial/dependencies/classes-as-dependencies.md
+++ /dev/null
@@ -1,180 +0,0 @@
-# 🎓 🔗
-
-⏭ 🤿 ⏬ 🔘 **🔗 💉** ⚙️, ➡️ ♻ ⏮️ 🖼.
-
-## `dict` ⚪️➡️ ⏮️ 🖼
-
-⏮️ 🖼, 👥 🛬 `dict` ⚪️➡️ 👆 🔗 ("☑"):
-
-{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
-
-✋️ ⤴️ 👥 🤚 `dict` 🔢 `commons` *➡ 🛠️ 🔢*.
-
-& 👥 💭 👈 👨🎨 💪 🚫 🚚 📚 🐕🦺 (💖 🛠️) `dict`Ⓜ, ↩️ 👫 💪 🚫 💭 👫 🔑 & 💲 🆎.
-
-👥 💪 👍...
-
-## ⚫️❔ ⚒ 🔗
-
-🆙 🔜 👆 ✔️ 👀 🔗 📣 🔢.
-
-✋️ 👈 🚫 🕴 🌌 📣 🔗 (👐 ⚫️ 🔜 🎲 🌖 ⚠).
-
-🔑 ⚖ 👈 🔗 🔜 "🇧🇲".
-
-"**🇧🇲**" 🐍 🕳 👈 🐍 💪 "🤙" 💖 🔢.
-
-, 🚥 👆 ✔️ 🎚 `something` (👈 💪 _🚫_ 🔢) & 👆 💪 "🤙" ⚫️ (🛠️ ⚫️) 💖:
-
-```Python
-something()
-```
-
-⚖️
-
-```Python
-something(some_argument, some_keyword_argument="foo")
-```
-
-⤴️ ⚫️ "🇧🇲".
-
-## 🎓 🔗
-
-👆 5️⃣📆 👀 👈 ✍ 👐 🐍 🎓, 👆 ⚙️ 👈 🎏 ❕.
-
-🖼:
-
-```Python
-class Cat:
- def __init__(self, name: str):
- self.name = name
-
-
-fluffy = Cat(name="Mr Fluffy")
-```
-
-👉 💼, `fluffy` 👐 🎓 `Cat`.
-
-& ✍ `fluffy`, 👆 "🤙" `Cat`.
-
-, 🐍 🎓 **🇧🇲**.
-
-⤴️, **FastAPI**, 👆 💪 ⚙️ 🐍 🎓 🔗.
-
-⚫️❔ FastAPI 🤙 ✅ 👈 ⚫️ "🇧🇲" (🔢, 🎓 ⚖️ 🕳 🙆) & 🔢 🔬.
-
-🚥 👆 🚶♀️ "🇧🇲" 🔗 **FastAPI**, ⚫️ 🔜 🔬 🔢 👈 "🇧🇲", & 🛠️ 👫 🎏 🌌 🔢 *➡ 🛠️ 🔢*. ✅ 🎧-🔗.
-
-👈 ✔ 🇧🇲 ⏮️ 🙅♂ 🔢 🌐. 🎏 ⚫️ 🔜 *➡ 🛠️ 🔢* ⏮️ 🙅♂ 🔢.
-
-⤴️, 👥 💪 🔀 🔗 "☑" `common_parameters` ⚪️➡️ 🔛 🎓 `CommonQueryParams`:
-
-{* ../../docs_src/dependencies/tutorial002.py hl[11:15] *}
-
-💸 🙋 `__init__` 👩🔬 ⚙️ ✍ 👐 🎓:
-
-{* ../../docs_src/dependencies/tutorial002.py hl[12] *}
-
-...⚫️ ✔️ 🎏 🔢 👆 ⏮️ `common_parameters`:
-
-{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
-
-📚 🔢 ⚫️❔ **FastAPI** 🔜 ⚙️ "❎" 🔗.
-
-👯♂️ 💼, ⚫️ 🔜 ✔️:
-
-* 📦 `q` 🔢 🔢 👈 `str`.
-* `skip` 🔢 🔢 👈 `int`, ⏮️ 🔢 `0`.
-* `limit` 🔢 🔢 👈 `int`, ⏮️ 🔢 `100`.
-
-👯♂️ 💼 💽 🔜 🗜, ✔, 📄 🔛 🗄 🔗, ♒️.
-
-## ⚙️ ⚫️
-
-🔜 👆 💪 📣 👆 🔗 ⚙️ 👉 🎓.
-
-{* ../../docs_src/dependencies/tutorial002.py hl[19] *}
-
-**FastAPI** 🤙 `CommonQueryParams` 🎓. 👉 ✍ "👐" 👈 🎓 & 👐 🔜 🚶♀️ 🔢 `commons` 👆 🔢.
-
-## 🆎 ✍ 🆚 `Depends`
-
-👀 ❔ 👥 ✍ `CommonQueryParams` 🕐 🔛 📟:
-
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
-
-🏁 `CommonQueryParams`,:
-
-```Python
-... = Depends(CommonQueryParams)
-```
-
-...⚫️❔ **FastAPI** 🔜 🤙 ⚙️ 💭 ⚫️❔ 🔗.
-
-⚪️➡️ ⚫️ 👈 FastAPI 🔜 ⚗ 📣 🔢 & 👈 ⚫️❔ FastAPI 🔜 🤙 🤙.
-
----
-
-👉 💼, 🥇 `CommonQueryParams`,:
-
-```Python
-commons: CommonQueryParams ...
-```
-
-...🚫 ✔️ 🙆 🎁 🔑 **FastAPI**. FastAPI 🏆 🚫 ⚙️ ⚫️ 💽 🛠️, 🔬, ♒️. (⚫️ ⚙️ `= Depends(CommonQueryParams)` 👈).
-
-👆 💪 🤙 ✍:
-
-```Python
-commons = Depends(CommonQueryParams)
-```
-
-...:
-
-{* ../../docs_src/dependencies/tutorial003.py hl[19] *}
-
-✋️ 📣 🆎 💡 👈 🌌 👆 👨🎨 🔜 💭 ⚫️❔ 🔜 🚶♀️ 🔢 `commons`, & ⤴️ ⚫️ 💪 ℹ 👆 ⏮️ 📟 🛠️, 🆎 ✅, ♒️:
-
-
-
-## ⌨
-
-✋️ 👆 👀 👈 👥 ✔️ 📟 🔁 📥, ✍ `CommonQueryParams` 🕐:
-
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
-
-**FastAPI** 🚚 ⌨ 👫 💼, 🌐❔ 🔗 *🎯* 🎓 👈 **FastAPI** 🔜 "🤙" ✍ 👐 🎓 ⚫️.
-
-📚 🎯 💼, 👆 💪 📄:
-
-↩️ ✍:
-
-```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
-```
-
-...👆 ✍:
-
-```Python
-commons: CommonQueryParams = Depends()
-```
-
-👆 📣 🔗 🆎 🔢, & 👆 ⚙️ `Depends()` 🚮 "🔢" 💲 (👈 ⏮️ `=`) 👈 🔢 🔢, 🍵 🙆 🔢 `Depends()`, ↩️ ✔️ ✍ 🌕 🎓 *🔄* 🔘 `Depends(CommonQueryParams)`.
-
-🎏 🖼 🔜 ⤴️ 👀 💖:
-
-{* ../../docs_src/dependencies/tutorial004.py hl[19] *}
-
-...& **FastAPI** 🔜 💭 ⚫️❔.
-
-/// tip
-
-🚥 👈 😑 🌅 😨 🌘 👍, 🤷♂ ⚫️, 👆 🚫 *💪* ⚫️.
-
-⚫️ ⌨. ↩️ **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
deleted file mode 100644
index ab144a497..000000000
--- a/docs/em/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# 🔗 ➡ 🛠️ 👨🎨
-
-💼 👆 🚫 🤙 💪 📨 💲 🔗 🔘 👆 *➡ 🛠️ 🔢*.
-
-⚖️ 🔗 🚫 📨 💲.
-
-✋️ 👆 💪 ⚫️ 🛠️/❎.
-
-📚 💼, ↩️ 📣 *➡ 🛠️ 🔢* 🔢 ⏮️ `Depends`, 👆 💪 🚮 `list` `dependencies` *➡ 🛠️ 👨🎨*.
-
-## 🚮 `dependencies` *➡ 🛠️ 👨🎨*
-
-*➡ 🛠️ 👨🎨* 📨 📦 ❌ `dependencies`.
-
-⚫️ 🔜 `list` `Depends()`:
-
-{* ../../docs_src/dependencies/tutorial006.py hl[17] *}
-
-👉 🔗 🔜 🛠️/❎ 🎏 🌌 😐 🔗. ✋️ 👫 💲 (🚥 👫 📨 🙆) 🏆 🚫 🚶♀️ 👆 *➡ 🛠️ 🔢*.
-
-/// tip
-
-👨🎨 ✅ ♻ 🔢 🔢, & 🎦 👫 ❌.
-
-⚙️ 👉 `dependencies` *➡ 🛠️ 👨🎨* 👆 💪 ⚒ 💭 👫 🛠️ ⏪ ❎ 👨🎨/🏭 ❌.
-
-⚫️ 💪 ℹ ❎ 😨 🆕 👩💻 👈 👀 ♻ 🔢 👆 📟 & 💪 💭 ⚫️ 🙃.
-
-///
-
-/// info
-
-👉 🖼 👥 ⚙️ 💭 🛃 🎚 `X-Key` & `X-Token`.
-
-✋️ 🎰 💼, 🕐❔ 🛠️ 💂♂, 👆 🔜 🤚 🌖 💰 ⚪️➡️ ⚙️ 🛠️ [💂♂ 🚙 (⏭ 📃)](../security/index.md){.internal-link target=_blank}.
-
-///
-
-## 🔗 ❌ & 📨 💲
-
-👆 💪 ⚙️ 🎏 🔗 *🔢* 👆 ⚙️ 🛎.
-
-### 🔗 📄
-
-👫 💪 📣 📨 📄 (💖 🎚) ⚖️ 🎏 🎧-🔗:
-
-{* ../../docs_src/dependencies/tutorial006.py hl[6,11] *}
-
-### 🤚 ⚠
-
-👫 🔗 💪 `raise` ⚠, 🎏 😐 🔗:
-
-{* ../../docs_src/dependencies/tutorial006.py hl[8,13] *}
-
-### 📨 💲
-
-& 👫 💪 📨 💲 ⚖️ 🚫, 💲 🏆 🚫 ⚙️.
-
-, 👆 💪 🏤-⚙️ 😐 🔗 (👈 📨 💲) 👆 ⏪ ⚙️ 👱 🙆, & ✋️ 💲 🏆 🚫 ⚙️, 🔗 🔜 🛠️:
-
-{* ../../docs_src/dependencies/tutorial006.py hl[9,14] *}
-
-## 🔗 👪 *➡ 🛠️*
-
-⏪, 🕐❔ 👂 🔃 ❔ 📊 🦏 🈸 ([🦏 🈸 - 💗 📁](../../tutorial/bigger-applications.md){.internal-link target=_blank}), 🎲 ⏮️ 💗 📁, 👆 🔜 💡 ❔ 📣 👁 `dependencies` 🔢 👪 *➡ 🛠️*.
-
-## 🌐 🔗
-
-⏭ 👥 🔜 👀 ❔ 🚮 🔗 🎂 `FastAPI` 🈸, 👈 👫 ✔ 🔠 *➡ 🛠️*.
diff --git a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md
deleted file mode 100644
index 1b37b1cf2..000000000
--- a/docs/em/docs/tutorial/dependencies/dependencies-with-yield.md
+++ /dev/null
@@ -1,232 +0,0 @@
-# 🔗 ⏮️ 🌾
-
-FastAPI 🐕🦺 🔗 👈 ➕ 🔁 ⏮️ 🏁.
-
-👉, ⚙️ `yield` ↩️ `return`, & ✍ ➕ 🔁 ⏮️.
-
-/// tip
-
-⚒ 💭 ⚙️ `yield` 1️⃣ 👁 🕰.
-
-///
-
-/// note | 📡 ℹ
-
-🙆 🔢 👈 ☑ ⚙️ ⏮️:
-
-* `@contextlib.contextmanager` ⚖️
-* `@contextlib.asynccontextmanager`
-
-🔜 ☑ ⚙️ **FastAPI** 🔗.
-
-👐, FastAPI ⚙️ 📚 2️⃣ 👨🎨 🔘.
-
-///
-
-## 💽 🔗 ⏮️ `yield`
-
-🖼, 👆 💪 ⚙️ 👉 ✍ 💽 🎉 & 🔐 ⚫️ ⏮️ 🏁.
-
-🕴 📟 ⏭ & 🔌 `yield` 📄 🛠️ ⏭ 📨 📨:
-
-{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
-
-🌾 💲 ⚫️❔ 💉 🔘 *➡ 🛠️* & 🎏 🔗:
-
-{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
-
-📟 📄 `yield` 📄 🛠️ ⏮️ 📨 ✔️ 🚚:
-
-{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
-
-/// tip
-
-👆 💪 ⚙️ `async` ⚖️ 😐 🔢.
-
-**FastAPI** 🔜 ▶️️ 👜 ⏮️ 🔠, 🎏 ⏮️ 😐 🔗.
-
-///
-
-## 🔗 ⏮️ `yield` & `try`
-
-🚥 👆 ⚙️ `try` 🍫 🔗 ⏮️ `yield`, 👆 🔜 📨 🙆 ⚠ 👈 🚮 🕐❔ ⚙️ 🔗.
-
-🖼, 🚥 📟 ☝ 🖕, ➕1️⃣ 🔗 ⚖️ *➡ 🛠️*, ⚒ 💽 💵 "💾" ⚖️ ✍ 🙆 🎏 ❌, 👆 🔜 📨 ⚠ 👆 🔗.
-
-, 👆 💪 👀 👈 🎯 ⚠ 🔘 🔗 ⏮️ `except SomeException`.
-
-🎏 🌌, 👆 💪 ⚙️ `finally` ⚒ 💭 🚪 📶 🛠️, 🙅♂ 🤔 🚥 📤 ⚠ ⚖️ 🚫.
-
-{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
-
-## 🎧-🔗 ⏮️ `yield`
-
-👆 💪 ✔️ 🎧-🔗 & "🌲" 🎧-🔗 🙆 📐 & 💠, & 🙆 ⚖️ 🌐 👫 💪 ⚙️ `yield`.
-
-**FastAPI** 🔜 ⚒ 💭 👈 "🚪 📟" 🔠 🔗 ⏮️ `yield` 🏃 ☑ ✔.
-
-🖼, `dependency_c` 💪 ✔️ 🔗 🔛 `dependency_b`, & `dependency_b` 🔛 `dependency_a`:
-
-{* ../../docs_src/dependencies/tutorial008.py hl[4,12,20] *}
-
-& 🌐 👫 💪 ⚙️ `yield`.
-
-👉 💼 `dependency_c`, 🛠️ 🚮 🚪 📟, 💪 💲 ⚪️➡️ `dependency_b` (📥 📛 `dep_b`) 💪.
-
-& , 🔄, `dependency_b` 💪 💲 ⚪️➡️ `dependency_a` (📥 📛 `dep_a`) 💪 🚮 🚪 📟.
-
-{* ../../docs_src/dependencies/tutorial008.py hl[16:17,24:25] *}
-
-🎏 🌌, 👆 💪 ✔️ 🔗 ⏮️ `yield` & `return` 🌀.
-
-& 👆 💪 ✔️ 👁 🔗 👈 🚚 📚 🎏 🔗 ⏮️ `yield`, ♒️.
-
-👆 💪 ✔️ 🙆 🌀 🔗 👈 👆 💚.
-
-**FastAPI** 🔜 ⚒ 💭 🌐 🏃 ☑ ✔.
-
-/// note | 📡 ℹ
-
-👉 👷 👏 🐍 🔑 👨💼.
-
-**FastAPI** ⚙️ 👫 🔘 🏆 👉.
-
-///
-
-## 🔗 ⏮️ `yield` & `HTTPException`
-
-👆 👀 👈 👆 💪 ⚙️ 🔗 ⏮️ `yield` & ✔️ `try` 🍫 👈 ✊ ⚠.
-
-⚫️ 5️⃣📆 😋 🤚 `HTTPException` ⚖️ 🎏 🚪 📟, ⏮️ `yield`. ✋️ **⚫️ 🏆 🚫 👷**.
-
-🚪 📟 🔗 ⏮️ `yield` 🛠️ *⏮️* 📨 📨, [⚠ 🐕🦺](../handling-errors.md#_4){.internal-link target=_blank} 🔜 ✔️ ⏪ 🏃. 📤 🕳 😽 ⚠ 🚮 👆 🔗 🚪 📟 (⏮️ `yield`).
-
-, 🚥 👆 🤚 `HTTPException` ⏮️ `yield`, 🔢 (⚖️ 🙆 🛃) ⚠ 🐕🦺 👈 ✊ `HTTPException`Ⓜ & 📨 🇺🇸🔍 4️⃣0️⃣0️⃣ 📨 🏆 🚫 📤 ✊ 👈 ⚠ 🚫🔜.
-
-👉 ⚫️❔ ✔ 🕳 ⚒ 🔗 (✅ 💽 🎉), 🖼, ⚙️ 🖥 📋.
-
-🖥 📋 🏃 *⏮️* 📨 ✔️ 📨. 📤 🙅♂ 🌌 🤚 `HTTPException` ↩️ 📤 🚫 🌌 🔀 📨 👈 *⏪ 📨*.
-
-✋️ 🚥 🖥 📋 ✍ 💽 ❌, 🌘 👆 💪 💾 ⚖️ 😬 🔐 🎉 🔗 ⏮️ `yield`, & 🎲 🕹 ❌ ⚖️ 📄 ⚫️ 🛰 🕵 ⚙️.
-
-🚥 👆 ✔️ 📟 👈 👆 💭 💪 🤚 ⚠, 🏆 😐/"🙃" 👜 & 🚮 `try` 🍫 👈 📄 📟.
-
-🚥 👆 ✔️ 🛃 ⚠ 👈 👆 🔜 💖 🍵 *⏭* 🛬 📨 & 🎲 ❎ 📨, 🎲 🙋♀ `HTTPException`, ✍ [🛃 ⚠ 🐕🦺](../handling-errors.md#_4){.internal-link target=_blank}.
-
-/// tip
-
-👆 💪 🤚 ⚠ 🔌 `HTTPException` *⏭* `yield`. ✋️ 🚫 ⏮️.
-
-///
-
-🔁 🛠️ 🌅 ⚖️ 🌘 💖 👉 📊. 🕰 💧 ⚪️➡️ 🔝 🔝. & 🔠 🏓 1️⃣ 🍕 🔗 ⚖️ 🛠️ 📟.
-
-```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,tasks: Can raise exception for dependency, handled after response is sent
- Note over client,operation: Can raise HTTPException and can change the response
- client ->> dep: Start request
- Note over dep: Run code up to yield
- opt raise
- dep -->> handler: Raise HTTPException
- handler -->> client: HTTP error response
- dep -->> dep: Raise other exception
- end
- dep ->> operation: Run dependency, e.g. DB session
- opt raise
- operation -->> dep: Raise HTTPException
- dep -->> handler: Auto forward exception
- handler -->> client: HTTP error response
- operation -->> dep: Raise other exception
- dep -->> handler: Auto forward exception
- end
- operation ->> client: Return response to client
- Note over client,operation: Response is already sent, can't change it anymore
- opt Tasks
- operation -->> tasks: Send background tasks
- end
- opt Raise other exception
- tasks -->> dep: Raise other exception
- end
- Note over dep: After yield
- opt Handle other exception
- dep -->> dep: Handle exception, can't change response. E.g. close DB session.
- end
-```
-
-/// info
-
-🕴 **1️⃣ 📨** 🔜 📨 👩💻. ⚫️ 💪 1️⃣ ❌ 📨 ⚖️ ⚫️ 🔜 📨 ⚪️➡️ *➡ 🛠️*.
-
-⏮️ 1️⃣ 📚 📨 📨, 🙅♂ 🎏 📨 💪 📨.
-
-///
-
-/// tip
-
-👉 📊 🎦 `HTTPException`, ✋️ 👆 💪 🤚 🙆 🎏 ⚠ ❔ 👆 ✍ [🛃 ⚠ 🐕🦺](../handling-errors.md#_4){.internal-link target=_blank}.
-
-🚥 👆 🤚 🙆 ⚠, ⚫️ 🔜 🚶♀️ 🔗 ⏮️ 🌾, 🔌 `HTTPException`, & ⤴️ **🔄** ⚠ 🐕🦺. 🚥 📤 🙅♂ ⚠ 🐕🦺 👈 ⚠, ⚫️ 🔜 ⤴️ 🍵 🔢 🔗 `ServerErrorMiddleware`, 🛬 5️⃣0️⃣0️⃣ 🇺🇸🔍 👔 📟, ➡️ 👩💻 💭 👈 📤 ❌ 💽.
-
-///
-
-## 🔑 👨💼
-
-### ⚫️❔ "🔑 👨💼"
-
-"🔑 👨💼" 🙆 👈 🐍 🎚 👈 👆 💪 ⚙️ `with` 📄.
-
-🖼, 👆 💪 ⚙️ `with` ✍ 📁:
-
-```Python
-with open("./somefile.txt") as f:
- contents = f.read()
- print(contents)
-```
-
-🔘, `open("./somefile.txt")` ✍ 🎚 👈 🤙 "🔑 👨💼".
-
-🕐❔ `with` 🍫 🏁, ⚫️ ⚒ 💭 🔐 📁, 🚥 📤 ⚠.
-
-🕐❔ 👆 ✍ 🔗 ⏮️ `yield`, **FastAPI** 🔜 🔘 🗜 ⚫️ 🔑 👨💼, & 🌀 ⚫️ ⏮️ 🎏 🔗 🧰.
-
-### ⚙️ 🔑 👨💼 🔗 ⏮️ `yield`
-
-/// warning
-
-👉, 🌅 ⚖️ 🌘, "🏧" 💭.
-
-🚥 👆 ▶️ ⏮️ **FastAPI** 👆 💪 💚 🚶 ⚫️ 🔜.
-
-///
-
-🐍, 👆 💪 ✍ 🔑 👨💼 🏗 🎓 ⏮️ 2️⃣ 👩🔬: `__enter__()` & `__exit__()`.
-
-👆 💪 ⚙️ 👫 🔘 **FastAPI** 🔗 ⏮️ `yield` ⚙️
-`with` ⚖️ `async with` 📄 🔘 🔗 🔢:
-
-{* ../../docs_src/dependencies/tutorial010.py hl[1:9,13] *}
-
-/// tip
-
-➕1️⃣ 🌌 ✍ 🔑 👨💼 ⏮️:
-
-* `@contextlib.contextmanager` ⚖️
-* `@contextlib.asynccontextmanager`
-
-⚙️ 👫 🎀 🔢 ⏮️ 👁 `yield`.
-
-👈 ⚫️❔ **FastAPI** ⚙️ 🔘 🔗 ⏮️ `yield`.
-
-✋️ 👆 🚫 ✔️ ⚙️ 👨🎨 FastAPI 🔗 (& 👆 🚫🔜 🚫).
-
-FastAPI 🔜 ⚫️ 👆 🔘.
-
-///
diff --git a/docs/em/docs/tutorial/dependencies/global-dependencies.md b/docs/em/docs/tutorial/dependencies/global-dependencies.md
deleted file mode 100644
index 5a22e5f1c..000000000
--- a/docs/em/docs/tutorial/dependencies/global-dependencies.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# 🌐 🔗
-
-🆎 🈸 👆 💪 💚 🚮 🔗 🎂 🈸.
-
-🎏 🌌 👆 💪 [🚮 `dependencies` *➡ 🛠️ 👨🎨*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 👆 💪 🚮 👫 `FastAPI` 🈸.
-
-👈 💼, 👫 🔜 ✔ 🌐 *➡ 🛠️* 🈸:
-
-{* ../../docs_src/dependencies/tutorial012.py hl[15] *}
-
-& 🌐 💭 📄 🔃 [❎ `dependencies` *➡ 🛠️ 👨🎨*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} ✔, ✋️ 👉 💼, 🌐 *➡ 🛠️* 📱.
-
-## 🔗 👪 *➡ 🛠️*
-
-⏪, 🕐❔ 👂 🔃 ❔ 📊 🦏 🈸 ([🦏 🈸 - 💗 📁](../../tutorial/bigger-applications.md){.internal-link target=_blank}), 🎲 ⏮️ 💗 📁, 👆 🔜 💡 ❔ 📣 👁 `dependencies` 🔢 👪 *➡ 🛠️*.
diff --git a/docs/em/docs/tutorial/dependencies/index.md b/docs/em/docs/tutorial/dependencies/index.md
deleted file mode 100644
index ce87d9ee4..000000000
--- a/docs/em/docs/tutorial/dependencies/index.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# 🔗
-
-**FastAPI** ✔️ 📶 🏋️ ✋️ 🏋️ **🔗 💉** ⚙️.
-
-⚫️ 🏗 📶 🙅 ⚙️, & ⚒ ⚫️ 📶 ⏩ 🙆 👩💻 🛠️ 🎏 🦲 ⏮️ **FastAPI**.
-
-## ⚫️❔ "🔗 💉"
-
-**"🔗 💉"** ⛓, 📋, 👈 📤 🌌 👆 📟 (👉 💼, 👆 *➡ 🛠️ 🔢*) 📣 👜 👈 ⚫️ 🚚 👷 & ⚙️: "🔗".
-
-& ⤴️, 👈 ⚙️ (👉 💼 **FastAPI**) 🔜 ✊ 💅 🔨 ⚫️❔ 💪 🚚 👆 📟 ⏮️ 📚 💪 🔗 ("💉" 🔗).
-
-👉 📶 ⚠ 🕐❔ 👆 💪:
-
-* ✔️ 💰 ⚛ (🎏 📟 ⚛ 🔄 & 🔄).
-* 💰 💽 🔗.
-* 🛠️ 💂♂, 🤝, 🔑 📄, ♒️.
-* & 📚 🎏 👜...
-
-🌐 👫, ⏪ 📉 📟 🔁.
-
-## 🥇 🔁
-
-➡️ 👀 📶 🙅 🖼. ⚫️ 🔜 🙅 👈 ⚫️ 🚫 📶 ⚠, 🔜.
-
-✋️ 👉 🌌 👥 💪 🎯 🔛 ❔ **🔗 💉** ⚙️ 👷.
-
-### ✍ 🔗, ⚖️ "☑"
-
-➡️ 🥇 🎯 🔛 🔗.
-
-⚫️ 🔢 👈 💪 ✊ 🌐 🎏 🔢 👈 *➡ 🛠️ 🔢* 💪 ✊:
-
-{* ../../docs_src/dependencies/tutorial001.py hl[8:11] *}
-
-👈 ⚫️.
-
-**2️⃣ ⏸**.
-
-& ⚫️ ✔️ 🎏 💠 & 📊 👈 🌐 👆 *➡ 🛠️ 🔢* ✔️.
-
-👆 💪 💭 ⚫️ *➡ 🛠️ 🔢* 🍵 "👨🎨" (🍵 `@app.get("/some-path")`).
-
-& ⚫️ 💪 📨 🕳 👆 💚.
-
-👉 💼, 👉 🔗 ⌛:
-
-* 📦 🔢 🔢 `q` 👈 `str`.
-* 📦 🔢 🔢 `skip` 👈 `int`, & 🔢 `0`.
-* 📦 🔢 🔢 `limit` 👈 `int`, & 🔢 `100`.
-
-& ⤴️ ⚫️ 📨 `dict` ⚗ 📚 💲.
-
-### 🗄 `Depends`
-
-{* ../../docs_src/dependencies/tutorial001.py hl[3] *}
-
-### 📣 🔗, "⚓️"
-
-🎏 🌌 👆 ⚙️ `Body`, `Query`, ♒️. ⏮️ 👆 *➡ 🛠️ 🔢* 🔢, ⚙️ `Depends` ⏮️ 🆕 🔢:
-
-{* ../../docs_src/dependencies/tutorial001.py hl[15,20] *}
-
-👐 👆 ⚙️ `Depends` 🔢 👆 🔢 🎏 🌌 👆 ⚙️ `Body`, `Query`, ♒️, `Depends` 👷 👄 🎏.
-
-👆 🕴 🤝 `Depends` 👁 🔢.
-
-👉 🔢 🔜 🕳 💖 🔢.
-
-& 👈 🔢 ✊ 🔢 🎏 🌌 👈 *➡ 🛠️ 🔢* .
-
-/// tip
-
-👆 🔜 👀 ⚫️❔ 🎏 "👜", ↖️ ⚪️➡️ 🔢, 💪 ⚙️ 🔗 ⏭ 📃.
-
-///
-
-🕐❔ 🆕 📨 🛬, **FastAPI** 🔜 ✊ 💅:
-
-* 🤙 👆 🔗 ("☑") 🔢 ⏮️ ☑ 🔢.
-* 🤚 🏁 ⚪️➡️ 👆 🔢.
-* 🛠️ 👈 🏁 🔢 👆 *➡ 🛠️ 🔢*.
-
-```mermaid
-graph TB
-
-common_parameters(["common_parameters"])
-read_items["/items/"]
-read_users["/users/"]
-
-common_parameters --> read_items
-common_parameters --> read_users
-```
-
-👉 🌌 👆 ✍ 🔗 📟 🕐 & **FastAPI** ✊ 💅 🤙 ⚫️ 👆 *➡ 🛠️*.
-
-/// check
-
-👀 👈 👆 🚫 ✔️ ✍ 🎁 🎓 & 🚶♀️ ⚫️ 👱 **FastAPI** "®" ⚫️ ⚖️ 🕳 🎏.
-
-👆 🚶♀️ ⚫️ `Depends` & **FastAPI** 💭 ❔ 🎂.
-
-///
-
-## `async` ⚖️ 🚫 `async`
-
-🔗 🔜 🤙 **FastAPI** (🎏 👆 *➡ 🛠️ 🔢*), 🎏 🚫 ✔ ⏪ 🔬 👆 🔢.
-
-👆 💪 ⚙️ `async def` ⚖️ 😐 `def`.
-
-& 👆 💪 📣 🔗 ⏮️ `async def` 🔘 😐 `def` *➡ 🛠️ 🔢*, ⚖️ `def` 🔗 🔘 `async def` *➡ 🛠️ 🔢*, ♒️.
-
-⚫️ 🚫 🤔. **FastAPI** 🔜 💭 ⚫️❔.
-
-/// note
-
-🚥 👆 🚫 💭, ✅ [🔁: *"🏃 ❓" *](../../async.md){.internal-link target=_blank} 📄 🔃 `async` & `await` 🩺.
-
-///
-
-## 🛠️ ⏮️ 🗄
-
-🌐 📨 📄, 🔬 & 📄 👆 🔗 (& 🎧-🔗) 🔜 🛠️ 🎏 🗄 🔗.
-
-, 🎓 🩺 🔜 ✔️ 🌐 ℹ ⚪️➡️ 👫 🔗 💁♂️:
-
-
-
-## 🙅 ⚙️
-
-🚥 👆 👀 ⚫️, *➡ 🛠️ 🔢* 📣 ⚙️ 🕐❔ *➡* & *🛠️* 🏏, & ⤴️ **FastAPI** ✊ 💅 🤙 🔢 ⏮️ ☑ 🔢, ❎ 📊 ⚪️➡️ 📨.
-
-🤙, 🌐 (⚖️ 🏆) 🕸 🛠️ 👷 👉 🎏 🌌.
-
-👆 🙅 🤙 👈 🔢 🔗. 👫 🤙 👆 🛠️ (👉 💼, **FastAPI**).
-
-⏮️ 🔗 💉 ⚙️, 👆 💪 💬 **FastAPI** 👈 👆 *➡ 🛠️ 🔢* "🪀" 🔛 🕳 🙆 👈 🔜 🛠️ ⏭ 👆 *➡ 🛠️ 🔢*, & **FastAPI** 🔜 ✊ 💅 🛠️ ⚫️ & "💉" 🏁.
-
-🎏 ⚠ ⚖ 👉 🎏 💭 "🔗 💉":
-
-* ℹ
-* 🐕🦺
-* 🐕🦺
-* 💉
-* 🦲
-
-## **FastAPI** 🔌-🔌
-
-🛠️ & "🔌-"Ⓜ 💪 🏗 ⚙️ **🔗 💉** ⚙️. ✋️ 👐, 📤 🤙 **🙅♂ 💪 ✍ "🔌-🔌"**, ⚙️ 🔗 ⚫️ 💪 📣 ♾ 🔢 🛠️ & 🔗 👈 ▶️️ 💪 👆 *➡ 🛠️ 🔢*.
-
-& 🔗 💪 ✍ 📶 🙅 & 🏋️ 🌌 👈 ✔ 👆 🗄 🐍 📦 👆 💪, & 🛠️ 👫 ⏮️ 👆 🛠️ 🔢 👩❤👨 ⏸ 📟, *🌖*.
-
-👆 🔜 👀 🖼 👉 ⏭ 📃, 🔃 🔗 & ☁ 💽, 💂♂, ♒️.
-
-## **FastAPI** 🔗
-
-🦁 🔗 💉 ⚙️ ⚒ **FastAPI** 🔗 ⏮️:
-
-* 🌐 🔗 💽
-* ☁ 💽
-* 🔢 📦
-* 🔢 🔗
-* 🤝 & ✔ ⚙️
-* 🛠️ ⚙️ ⚖ ⚙️
-* 📨 💽 💉 ⚙️
-* ♒️.
-
-## 🙅 & 🏋️
-
-👐 🔗 🔗 💉 ⚙️ 📶 🙅 🔬 & ⚙️, ⚫️ 📶 🏋️.
-
-👆 💪 🔬 🔗 👈 🔄 💪 🔬 🔗 👫.
-
-🔚, 🔗 🌲 🔗 🏗, & **🔗 💉** ⚙️ ✊ 💅 🔬 🌐 👉 🔗 👆 (& 👫 🎧-🔗) & 🚚 (💉) 🏁 🔠 🔁.
-
-🖼, ➡️ 💬 👆 ✔️ 4️⃣ 🛠️ 🔗 (*➡ 🛠️*):
-
-* `/items/public/`
-* `/items/private/`
-* `/users/{user_id}/activate`
-* `/items/pro/`
-
-⤴️ 👆 💪 🚮 🎏 ✔ 📄 🔠 👫 ⏮️ 🔗 & 🎧-🔗:
-
-```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
-```
-
-## 🛠️ ⏮️ **🗄**
-
-🌐 👫 🔗, ⏪ 📣 👫 📄, 🚮 🔢, 🔬, ♒️. 👆 *➡ 🛠️*.
-
-**FastAPI** 🔜 ✊ 💅 🚮 ⚫️ 🌐 🗄 🔗, 👈 ⚫️ 🎦 🎓 🧾 ⚙️.
diff --git a/docs/em/docs/tutorial/dependencies/sub-dependencies.md b/docs/em/docs/tutorial/dependencies/sub-dependencies.md
deleted file mode 100644
index 6d622e952..000000000
--- a/docs/em/docs/tutorial/dependencies/sub-dependencies.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# 🎧-🔗
-
-👆 💪 ✍ 🔗 👈 ✔️ **🎧-🔗**.
-
-👫 💪 **⏬** 👆 💪 👫.
-
-**FastAPI** 🔜 ✊ 💅 🔬 👫.
-
-## 🥇 🔗 "☑"
-
-👆 💪 ✍ 🥇 🔗 ("☑") 💖:
-
-{* ../../docs_src/dependencies/tutorial005.py hl[8:9] *}
-
-⚫️ 📣 📦 🔢 🔢 `q` `str`, & ⤴️ ⚫️ 📨 ⚫️.
-
-👉 🙅 (🚫 📶 ⚠), ✋️ 🔜 ℹ 👥 🎯 🔛 ❔ 🎧-🔗 👷.
-
-## 🥈 🔗, "☑" & "⚓️"
-
-⤴️ 👆 💪 ✍ ➕1️⃣ 🔗 🔢 ("☑") 👈 🎏 🕰 📣 🔗 🚮 👍 (⚫️ "⚓️" 💁♂️):
-
-{* ../../docs_src/dependencies/tutorial005.py hl[13] *}
-
-➡️ 🎯 🔛 🔢 📣:
-
-* ✋️ 👉 🔢 🔗 ("☑") ⚫️, ⚫️ 📣 ➕1️⃣ 🔗 (⚫️ "🪀" 🔛 🕳 🙆).
- * ⚫️ 🪀 🔛 `query_extractor`, & 🛠️ 💲 📨 ⚫️ 🔢 `q`.
-* ⚫️ 📣 📦 `last_query` 🍪, `str`.
- * 🚥 👩💻 🚫 🚚 🙆 🔢 `q`, 👥 ⚙️ 🏁 🔢 ⚙️, ❔ 👥 🖊 🍪 ⏭.
-
-## ⚙️ 🔗
-
-⤴️ 👥 💪 ⚙️ 🔗 ⏮️:
-
-{* ../../docs_src/dependencies/tutorial005.py hl[22] *}
-
-/// info
-
-👀 👈 👥 🕴 📣 1️⃣ 🔗 *➡ 🛠️ 🔢*, `query_or_cookie_extractor`.
-
-✋️ **FastAPI** 🔜 💭 👈 ⚫️ ✔️ ❎ `query_extractor` 🥇, 🚶♀️ 🏁 👈 `query_or_cookie_extractor` ⏪ 🤙 ⚫️.
-
-///
-
-```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
-```
-
-## ⚙️ 🎏 🔗 💗 🕰
-
-🚥 1️⃣ 👆 🔗 📣 💗 🕰 🎏 *➡ 🛠️*, 🖼, 💗 🔗 ✔️ ⚠ 🎧-🔗, **FastAPI** 🔜 💭 🤙 👈 🎧-🔗 🕴 🕐 📍 📨.
-
-& ⚫️ 🔜 🖊 📨 💲 "💾" & 🚶♀️ ⚫️ 🌐 "⚓️" 👈 💪 ⚫️ 👈 🎯 📨, ↩️ 🤙 🔗 💗 🕰 🎏 📨.
-
-🏧 😐 🌐❔ 👆 💭 👆 💪 🔗 🤙 🔠 🔁 (🎲 💗 🕰) 🎏 📨 ↩️ ⚙️ "💾" 💲, 👆 💪 ⚒ 🔢 `use_cache=False` 🕐❔ ⚙️ `Depends`:
-
-```Python hl_lines="1"
-async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False)):
- return {"fresh_value": fresh_value}
-```
-
-## 🌃
-
-↖️ ⚪️➡️ 🌐 🎀 🔤 ⚙️ 📥, **🔗 💉** ⚙️ 🙅.
-
-🔢 👈 👀 🎏 *➡ 🛠️ 🔢*.
-
-✋️, ⚫️ 📶 🏋️, & ✔ 👆 📣 🎲 🙇 🐦 🔗 "📊" (🌲).
-
-/// tip
-
-🌐 👉 💪 🚫 😑 ⚠ ⏮️ 👫 🙅 🖼.
-
-✋️ 👆 🔜 👀 ❔ ⚠ ⚫️ 📃 🔃 **💂♂**.
-
- & 👆 🔜 👀 💸 📟 ⚫️ 🔜 🖊 👆.
-
-///
diff --git a/docs/em/docs/tutorial/encoder.md b/docs/em/docs/tutorial/encoder.md
deleted file mode 100644
index ad05f701e..000000000
--- a/docs/em/docs/tutorial/encoder.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 🎻 🔗 🔢
-
-📤 💼 🌐❔ 👆 5️⃣📆 💪 🗜 💽 🆎 (💖 Pydantic 🏷) 🕳 🔗 ⏮️ 🎻 (💖 `dict`, `list`, ♒️).
-
-🖼, 🚥 👆 💪 🏪 ⚫️ 💽.
-
-👈, **FastAPI** 🚚 `jsonable_encoder()` 🔢.
-
-## ⚙️ `jsonable_encoder`
-
-➡️ 🌈 👈 👆 ✔️ 💽 `fake_db` 👈 🕴 📨 🎻 🔗 💽.
-
-🖼, ⚫️ 🚫 📨 `datetime` 🎚, 👈 🚫 🔗 ⏮️ 🎻.
-
-, `datetime` 🎚 🔜 ✔️ 🗜 `str` ⚗ 💽 💾 📁.
-
-🎏 🌌, 👉 💽 🚫🔜 📨 Pydantic 🏷 (🎚 ⏮️ 🔢), 🕴 `dict`.
-
-👆 💪 ⚙️ `jsonable_encoder` 👈.
-
-⚫️ 📨 🎚, 💖 Pydantic 🏷, & 📨 🎻 🔗 ⏬:
-
-{* ../../docs_src/encoder/tutorial001.py hl[5,22] *}
-
-👉 🖼, ⚫️ 🔜 🗜 Pydantic 🏷 `dict`, & `datetime` `str`.
-
-🏁 🤙 ⚫️ 🕳 👈 💪 🗜 ⏮️ 🐍 🐩 `json.dumps()`.
-
-⚫️ 🚫 📨 ⭕ `str` ⚗ 💽 🎻 📁 (🎻). ⚫️ 📨 🐍 🐩 💽 📊 (✅ `dict`) ⏮️ 💲 & 🎧-💲 👈 🌐 🔗 ⏮️ 🎻.
-
-/// note
-
-`jsonable_encoder` 🤙 ⚙️ **FastAPI** 🔘 🗜 💽. ✋️ ⚫️ ⚠ 📚 🎏 😐.
-
-///
diff --git a/docs/em/docs/tutorial/extra-data-types.md b/docs/em/docs/tutorial/extra-data-types.md
deleted file mode 100644
index f15a74b4a..000000000
--- a/docs/em/docs/tutorial/extra-data-types.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# ➕ 💽 🆎
-
-🆙 🔜, 👆 ✔️ ⚙️ ⚠ 📊 🆎, 💖:
-
-* `int`
-* `float`
-* `str`
-* `bool`
-
-✋️ 👆 💪 ⚙️ 🌅 🏗 📊 🆎.
-
-& 👆 🔜 ✔️ 🎏 ⚒ 👀 🆙 🔜:
-
-* 👑 👨🎨 🐕🦺.
-* 💽 🛠️ ⚪️➡️ 📨 📨.
-* 💽 🛠️ 📨 💽.
-* 💽 🔬.
-* 🏧 ✍ & 🧾.
-
-## 🎏 💽 🆎
-
-📥 🌖 📊 🆎 👆 💪 ⚙️:
-
-* `UUID`:
- * 🐩 "⭐ 😍 🆔", ⚠ 🆔 📚 💽 & ⚙️.
- * 📨 & 📨 🔜 🎨 `str`.
-* `datetime.datetime`:
- * 🐍 `datetime.datetime`.
- * 📨 & 📨 🔜 🎨 `str` 💾 8️⃣6️⃣0️⃣1️⃣ 📁, 💖: `2008-09-15T15:53:00+05:00`.
-* `datetime.date`:
- * 🐍 `datetime.date`.
- * 📨 & 📨 🔜 🎨 `str` 💾 8️⃣6️⃣0️⃣1️⃣ 📁, 💖: `2008-09-15`.
-* `datetime.time`:
- * 🐍 `datetime.time`.
- * 📨 & 📨 🔜 🎨 `str` 💾 8️⃣6️⃣0️⃣1️⃣ 📁, 💖: `14:23:55.003`.
-* `datetime.timedelta`:
- * 🐍 `datetime.timedelta`.
- * 📨 & 📨 🔜 🎨 `float` 🌐 🥈.
- * Pydantic ✔ 🎦 ⚫️ "💾 8️⃣6️⃣0️⃣1️⃣ 🕰 ➕ 🔢", 👀 🩺 🌅 ℹ.
-* `frozenset`:
- * 📨 & 📨, 😥 🎏 `set`:
- * 📨, 📇 🔜 ✍, ❎ ❎ & 🏭 ⚫️ `set`.
- * 📨, `set` 🔜 🗜 `list`.
- * 🏗 🔗 🔜 ✔ 👈 `set` 💲 😍 (⚙️ 🎻 🔗 `uniqueItems`).
-* `bytes`:
- * 🐩 🐍 `bytes`.
- * 📨 & 📨 🔜 😥 `str`.
- * 🏗 🔗 🔜 ✔ 👈 ⚫️ `str` ⏮️ `binary` "📁".
-* `Decimal`:
- * 🐩 🐍 `Decimal`.
- * 📨 & 📨, 🍵 🎏 `float`.
-* 👆 💪 ✅ 🌐 ☑ Pydantic 📊 🆎 📥: Pydantic 📊 🆎.
-
-## 🖼
-
-📥 🖼 *➡ 🛠️* ⏮️ 🔢 ⚙️ 🔛 🆎.
-
-{* ../../docs_src/extra_data_types/tutorial001.py hl[1,3,12:16] *}
-
-🗒 👈 🔢 🔘 🔢 ✔️ 👫 🐠 💽 🆎, & 👆 💪, 🖼, 🎭 😐 📅 🎭, 💖:
-
-{* ../../docs_src/extra_data_types/tutorial001.py hl[18:19] *}
diff --git a/docs/em/docs/tutorial/extra-models.md b/docs/em/docs/tutorial/extra-models.md
deleted file mode 100644
index 19ab5b798..000000000
--- a/docs/em/docs/tutorial/extra-models.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# ➕ 🏷
-
-▶️ ⏮️ ⏮️ 🖼, ⚫️ 🔜 ⚠ ✔️ 🌅 🌘 1️⃣ 🔗 🏷.
-
-👉 ✴️ 💼 👩💻 🏷, ↩️:
-
-* **🔢 🏷** 💪 💪 ✔️ 🔐.
-* **🔢 🏷** 🔜 🚫 ✔️ 🔐.
-* **💽 🏷** 🔜 🎲 💪 ✔️ #️⃣ 🔐.
-
-/// danger
-
-🙅 🏪 👩💻 🔢 🔐. 🕧 🏪 "🔐 #️⃣" 👈 👆 💪 ⤴️ ✔.
-
-🚥 👆 🚫 💭, 👆 🔜 💡 ⚫️❔ "🔐#️⃣" [💂♂ 📃](security/simple-oauth2.md#_4){.internal-link target=_blank}.
-
-///
-
-## 💗 🏷
-
-📥 🏢 💭 ❔ 🏷 💪 👀 💖 ⏮️ 👫 🔐 🏑 & 🥉 🌐❔ 👫 ⚙️:
-
-{* ../../docs_src/extra_models/tutorial001.py hl[9,11,16,22,24,29:30,33:35,40:41] *}
-
-### 🔃 `**user_in.dict()`
-
-#### Pydantic `.dict()`
-
-`user_in` Pydantic 🏷 🎓 `UserIn`.
-
-Pydantic 🏷 ✔️ `.dict()` 👩🔬 👈 📨 `dict` ⏮️ 🏷 💽.
-
-, 🚥 👥 ✍ Pydantic 🎚 `user_in` 💖:
-
-```Python
-user_in = UserIn(username="john", password="secret", email="john.doe@example.com")
-```
-
-& ⤴️ 👥 🤙:
-
-```Python
-user_dict = user_in.dict()
-```
-
-👥 🔜 ✔️ `dict` ⏮️ 💽 🔢 `user_dict` (⚫️ `dict` ↩️ Pydantic 🏷 🎚).
-
-& 🚥 👥 🤙:
-
-```Python
-print(user_dict)
-```
-
-👥 🔜 🤚 🐍 `dict` ⏮️:
-
-```Python
-{
- 'username': 'john',
- 'password': 'secret',
- 'email': 'john.doe@example.com',
- 'full_name': None,
-}
-```
-
-#### 🎁 `dict`
-
-🚥 👥 ✊ `dict` 💖 `user_dict` & 🚶♀️ ⚫️ 🔢 (⚖️ 🎓) ⏮️ `**user_dict`, 🐍 🔜 "🎁" ⚫️. ⚫️ 🔜 🚶♀️ 🔑 & 💲 `user_dict` 🔗 🔑-💲 ❌.
-
-, ▶️ ⏮️ `user_dict` ⚪️➡️ 🔛, ✍:
-
-```Python
-UserInDB(**user_dict)
-```
-
-🔜 🏁 🕳 🌓:
-
-```Python
-UserInDB(
- username="john",
- password="secret",
- email="john.doe@example.com",
- full_name=None,
-)
-```
-
-⚖️ 🌅 ⚫️❔, ⚙️ `user_dict` 🔗, ⏮️ ⚫️❔ 🎚 ⚫️ 💪 ✔️ 🔮:
-
-```Python
-UserInDB(
- username = user_dict["username"],
- password = user_dict["password"],
- email = user_dict["email"],
- full_name = user_dict["full_name"],
-)
-```
-
-#### Pydantic 🏷 ⚪️➡️ 🎚 ➕1️⃣
-
-🖼 🔛 👥 🤚 `user_dict` ⚪️➡️ `user_in.dict()`, 👉 📟:
-
-```Python
-user_dict = user_in.dict()
-UserInDB(**user_dict)
-```
-
-🔜 🌓:
-
-```Python
-UserInDB(**user_in.dict())
-```
-
-...↩️ `user_in.dict()` `dict`, & ⤴️ 👥 ⚒ 🐍 "🎁" ⚫️ 🚶♀️ ⚫️ `UserInDB` 🔠 ⏮️ `**`.
-
-, 👥 🤚 Pydantic 🏷 ⚪️➡️ 💽 ➕1️⃣ Pydantic 🏷.
-
-#### 🎁 `dict` & ➕ 🇨🇻
-
-& ⤴️ ❎ ➕ 🇨🇻 ❌ `hashed_password=hashed_password`, 💖:
-
-```Python
-UserInDB(**user_in.dict(), hashed_password=hashed_password)
-```
-
-...🔚 🆙 💆♂ 💖:
-
-```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
-
-🔗 🌖 🔢 🤖 💪 💧 💽, ✋️ 👫 ↗️ 🚫 🚚 🙆 🎰 💂♂.
-
-///
-
-## 📉 ❎
-
-📉 📟 ❎ 1️⃣ 🐚 💭 **FastAPI**.
-
-📟 ❎ 📈 🤞 🐛, 💂♂ ❔, 📟 🔁 ❔ (🕐❔ 👆 ℹ 1️⃣ 🥉 ✋️ 🚫 🎏), ♒️.
-
-& 👉 🏷 🌐 🤝 📚 💽 & ❎ 🔢 📛 & 🆎.
-
-👥 💪 👻.
-
-👥 💪 📣 `UserBase` 🏷 👈 🍦 🧢 👆 🎏 🏷. & ⤴️ 👥 💪 ⚒ 🏿 👈 🏷 👈 😖 🚮 🔢 (🆎 📄, 🔬, ♒️).
-
-🌐 💽 🛠️, 🔬, 🧾, ♒️. 🔜 👷 🛎.
-
-👈 🌌, 👥 💪 📣 🔺 🖖 🏷 (⏮️ 🔢 `password`, ⏮️ `hashed_password` & 🍵 🔐):
-
-{* ../../docs_src/extra_models/tutorial002.py hl[9,15:16,19:20,23:24] *}
-
-## `Union` ⚖️ `anyOf`
-
-👆 💪 📣 📨 `Union` 2️⃣ 🆎, 👈 ⛓, 👈 📨 🔜 🙆 2️⃣.
-
-⚫️ 🔜 🔬 🗄 ⏮️ `anyOf`.
-
-👈, ⚙️ 🐩 🐍 🆎 🔑 `typing.Union`:
-
-/// note
-
-🕐❔ ⚖ `Union`, 🔌 🏆 🎯 🆎 🥇, ⏩ 🌘 🎯 🆎. 🖼 🔛, 🌖 🎯 `PlaneItem` 👟 ⏭ `CarItem` `Union[PlaneItem, CarItem]`.
-
-///
-
-{* ../../docs_src/extra_models/tutorial003.py hl[1,14:15,18:20,33] *}
-
-### `Union` 🐍 3️⃣.1️⃣0️⃣
-
-👉 🖼 👥 🚶♀️ `Union[PlaneItem, CarItem]` 💲 ❌ `response_model`.
-
-↩️ 👥 🚶♀️ ⚫️ **💲 ❌** ↩️ 🚮 ⚫️ **🆎 ✍**, 👥 ✔️ ⚙️ `Union` 🐍 3️⃣.1️⃣0️⃣.
-
-🚥 ⚫️ 🆎 ✍ 👥 💪 ✔️ ⚙️ ⏸ ⏸,:
-
-```Python
-some_variable: PlaneItem | CarItem
-```
-
-✋️ 🚥 👥 🚮 👈 `response_model=PlaneItem | CarItem` 👥 🔜 🤚 ❌, ↩️ 🐍 🔜 🔄 🎭 **❌ 🛠️** 🖖 `PlaneItem` & `CarItem` ↩️ 🔬 👈 🆎 ✍.
-
-## 📇 🏷
-
-🎏 🌌, 👆 💪 📣 📨 📇 🎚.
-
-👈, ⚙️ 🐩 🐍 `typing.List` (⚖️ `list` 🐍 3️⃣.9️⃣ & 🔛):
-
-{* ../../docs_src/extra_models/tutorial004.py hl[1,20] *}
-
-## 📨 ⏮️ ❌ `dict`
-
-👆 💪 📣 📨 ⚙️ ✅ ❌ `dict`, 📣 🆎 🔑 & 💲, 🍵 ⚙️ Pydantic 🏷.
-
-👉 ⚠ 🚥 👆 🚫 💭 ☑ 🏑/🔢 📛 (👈 🔜 💪 Pydantic 🏷) ⏪.
-
-👉 💼, 👆 💪 ⚙️ `typing.Dict` (⚖️ `dict` 🐍 3️⃣.9️⃣ & 🔛):
-
-{* ../../docs_src/extra_models/tutorial005.py hl[1,8] *}
-
-## 🌃
-
-⚙️ 💗 Pydantic 🏷 & 😖 ➡ 🔠 💼.
-
-👆 🚫 💪 ✔️ 👁 💽 🏷 📍 👨💼 🚥 👈 👨💼 🔜 💪 ✔️ 🎏 "🇵🇸". 💼 ⏮️ 👩💻 "👨💼" ⏮️ 🇵🇸 ✅ `password`, `password_hash` & 🙅♂ 🔐.
diff --git a/docs/em/docs/tutorial/first-steps.md b/docs/em/docs/tutorial/first-steps.md
deleted file mode 100644
index a8f936b01..000000000
--- a/docs/em/docs/tutorial/first-steps.md
+++ /dev/null
@@ -1,335 +0,0 @@
-# 🥇 🔁
-
-🙅 FastAPI 📁 💪 👀 💖 👉:
-
-{* ../../docs_src/first_steps/tutorial001.py *}
-
-📁 👈 📁 `main.py`.
-
-🏃 🖖 💽:
-
-get 🛠️
-
-/// info | `@decorator` ℹ
-
-👈 `@something` ❕ 🐍 🤙 "👨🎨".
-
-👆 🚮 ⚫️ 🔛 🔝 🔢. 💖 📶 📔 👒 (👤 💭 👈 🌐❔ ⚖ 👟 ⚪️➡️).
-
- "👨🎨" ✊ 🔢 🔛 & 🔨 🕳 ⏮️ ⚫️.
-
-👆 💼, 👉 👨🎨 💬 **FastAPI** 👈 🔢 🔛 🔗 **➡** `/` ⏮️ **🛠️** `get`.
-
-⚫️ "**➡ 🛠️ 👨🎨**".
-
-///
-
-👆 💪 ⚙️ 🎏 🛠️:
-
-* `@app.post()`
-* `@app.put()`
-* `@app.delete()`
-
-& 🌅 😍 🕐:
-
-* `@app.options()`
-* `@app.head()`
-* `@app.patch()`
-* `@app.trace()`
-
-/// tip
-
-👆 🆓 ⚙️ 🔠 🛠️ (🇺🇸🔍 👩🔬) 👆 🎋.
-
-**FastAPI** 🚫 🛠️ 🙆 🎯 🔑.
-
-ℹ 📥 🎁 📄, 🚫 📄.
-
-🖼, 🕐❔ ⚙️ 🕹 👆 🛎 🎭 🌐 🎯 ⚙️ 🕴 `POST` 🛠️.
-
-///
-
-### 🔁 4️⃣: 🔬 **➡ 🛠️ 🔢**
-
-👉 👆 "**➡ 🛠️ 🔢**":
-
-* **➡**: `/`.
-* **🛠️**: `get`.
-* **🔢**: 🔢 🔛 "👨🎨" (🔛 `@app.get("/")`).
-
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
-
-👉 🐍 🔢.
-
-⚫️ 🔜 🤙 **FastAPI** 🕐❔ ⚫️ 📨 📨 📛 "`/`" ⚙️ `GET` 🛠️.
-
-👉 💼, ⚫️ `async` 🔢.
-
----
-
-👆 💪 🔬 ⚫️ 😐 🔢 ↩️ `async def`:
-
-{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
-
-/// note
-
-🚥 👆 🚫 💭 🔺, ✅ [🔁: *"🏃 ❓"*](../async.md#_2){.internal-link target=_blank}.
-
-///
-
-### 🔁 5️⃣: 📨 🎚
-
-{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
-
-👆 💪 📨 `dict`, `list`, ⭐ 💲 `str`, `int`, ♒️.
-
-👆 💪 📨 Pydantic 🏷 (👆 🔜 👀 🌅 🔃 👈 ⏪).
-
-📤 📚 🎏 🎚 & 🏷 👈 🔜 🔁 🗜 🎻 (🔌 🐜, ♒️). 🔄 ⚙️ 👆 💕 🕐, ⚫️ 🏆 🎲 👈 👫 ⏪ 🐕🦺.
-
-## 🌃
-
-* 🗄 `FastAPI`.
-* ✍ `app` 👐.
-* ✍ **➡ 🛠️ 👨🎨** (💖 `@app.get("/")`).
-* ✍ **➡ 🛠️ 🔢** (💖 `def root(): ...` 🔛).
-* 🏃 🛠️ 💽 (💖 `uvicorn main:app --reload`).
diff --git a/docs/em/docs/tutorial/handling-errors.md b/docs/em/docs/tutorial/handling-errors.md
deleted file mode 100644
index d73b730e1..000000000
--- a/docs/em/docs/tutorial/handling-errors.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# 🚚 ❌
-
-📤 📚 ⚠ 🌐❔ 👆 💪 🚨 ❌ 👩💻 👈 ⚙️ 👆 🛠️.
-
-👉 👩💻 💪 🖥 ⏮️ 🕸, 📟 ⚪️➡️ 👱 🙆, ☁ 📳, ♒️.
-
-👆 💪 💪 💬 👩💻 👈:
-
-* 👩💻 🚫 ✔️ 🥃 😌 👈 🛠️.
-* 👩💻 🚫 ✔️ 🔐 👈 ℹ.
-* 🏬 👩💻 🔄 🔐 🚫 🔀.
-* ♒️.
-
-👫 💼, 👆 🔜 🛎 📨 **🇺🇸🔍 👔 📟** ↔ **4️⃣0️⃣0️⃣** (⚪️➡️ 4️⃣0️⃣0️⃣ 4️⃣9️⃣9️⃣).
-
-👉 🎏 2️⃣0️⃣0️⃣ 🇺🇸🔍 👔 📟 (⚪️➡️ 2️⃣0️⃣0️⃣ 2️⃣9️⃣9️⃣). 👈 "2️⃣0️⃣0️⃣" 👔 📟 ⛓ 👈 😫 📤 "🏆" 📨.
-
-👔 📟 4️⃣0️⃣0️⃣ ↔ ⛓ 👈 📤 ❌ ⚪️➡️ 👩💻.
-
-💭 🌐 👈 **"4️⃣0️⃣4️⃣ 🚫 🔎"** ❌ (& 🤣) ❓
-
-## ⚙️ `HTTPException`
-
-📨 🇺🇸🔍 📨 ⏮️ ❌ 👩💻 👆 ⚙️ `HTTPException`.
-
-### 🗄 `HTTPException`
-
-{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
-
-### 🤚 `HTTPException` 👆 📟
-
-`HTTPException` 😐 🐍 ⚠ ⏮️ 🌖 📊 🔗 🔗.
-
-↩️ ⚫️ 🐍 ⚠, 👆 🚫 `return` ⚫️, 👆 `raise` ⚫️.
-
-👉 ⛓ 👈 🚥 👆 🔘 🚙 🔢 👈 👆 🤙 🔘 👆 *➡ 🛠️ 🔢*, & 👆 🤚 `HTTPException` ⚪️➡️ 🔘 👈 🚙 🔢, ⚫️ 🏆 🚫 🏃 🎂 📟 *➡ 🛠️ 🔢*, ⚫️ 🔜 ❎ 👈 📨 ▶️️ ↖️ & 📨 🇺🇸🔍 ❌ ⚪️➡️ `HTTPException` 👩💻.
-
-💰 🙋♀ ⚠ 🤭 `return`😅 💲 🔜 🌖 ⭐ 📄 🔃 🔗 & 💂♂.
-
-👉 🖼, 🕐❔ 👩💻 📨 🏬 🆔 👈 🚫 🔀, 🤚 ⚠ ⏮️ 👔 📟 `404`:
-
-{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
-
-### 📉 📨
-
-🚥 👩💻 📨 `http://example.com/items/foo` ( `item_id` `"foo"`), 👈 👩💻 🔜 📨 🇺🇸🔍 👔 📟 2️⃣0️⃣0️⃣, & 🎻 📨:
-
-```JSON
-{
- "item": "The Foo Wrestlers"
-}
-```
-
-✋️ 🚥 👩💻 📨 `http://example.com/items/bar` (🚫-🚫 `item_id` `"bar"`), 👈 👩💻 🔜 📨 🇺🇸🔍 👔 📟 4️⃣0️⃣4️⃣ ("🚫 🔎" ❌), & 🎻 📨:
-
-```JSON
-{
- "detail": "Item not found"
-}
-```
-
-/// tip
-
-🕐❔ 🙋♀ `HTTPException`, 👆 💪 🚶♀️ 🙆 💲 👈 💪 🗜 🎻 🔢 `detail`, 🚫 🕴 `str`.
-
-👆 💪 🚶♀️ `dict`, `list`, ♒️.
-
-👫 🍵 🔁 **FastAPI** & 🗜 🎻.
-
-///
-
-## 🚮 🛃 🎚
-
-📤 ⚠ 🌐❔ ⚫️ ⚠ 💪 🚮 🛃 🎚 🇺🇸🔍 ❌. 🖼, 🆎 💂♂.
-
-👆 🎲 🏆 🚫 💪 ⚙️ ⚫️ 🔗 👆 📟.
-
-✋️ 💼 👆 💪 ⚫️ 🏧 😐, 👆 💪 🚮 🛃 🎚:
-
-{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
-
-## ❎ 🛃 ⚠ 🐕🦺
-
-👆 💪 🚮 🛃 ⚠ 🐕🦺 ⏮️ 🎏 ⚠ 🚙 ⚪️➡️ 💃.
-
-➡️ 💬 👆 ✔️ 🛃 ⚠ `UnicornException` 👈 👆 (⚖️ 🗃 👆 ⚙️) 💪 `raise`.
-
-& 👆 💚 🍵 👉 ⚠ 🌐 ⏮️ FastAPI.
-
-👆 💪 🚮 🛃 ⚠ 🐕🦺 ⏮️ `@app.exception_handler()`:
-
-{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
-
-📥, 🚥 👆 📨 `/unicorns/yolo`, *➡ 🛠️* 🔜 `raise` `UnicornException`.
-
-✋️ ⚫️ 🔜 🍵 `unicorn_exception_handler`.
-
-, 👆 🔜 📨 🧹 ❌, ⏮️ 🇺🇸🔍 👔 📟 `418` & 🎻 🎚:
-
-```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` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃. 🎏 ⏮️ `Request`.
-
-///
-
-## 🔐 🔢 ⚠ 🐕🦺
-
-**FastAPI** ✔️ 🔢 ⚠ 🐕🦺.
-
-👫 🐕🦺 🈚 🛬 🔢 🎻 📨 🕐❔ 👆 `raise` `HTTPException` & 🕐❔ 📨 ✔️ ❌ 💽.
-
-👆 💪 🔐 👫 ⚠ 🐕🦺 ⏮️ 👆 👍.
-
-### 🔐 📨 🔬 ⚠
-
-🕐❔ 📨 🔌 ❌ 📊, **FastAPI** 🔘 🤚 `RequestValidationError`.
-
-& ⚫️ 🔌 🔢 ⚠ 🐕🦺 ⚫️.
-
-🔐 ⚫️, 🗄 `RequestValidationError` & ⚙️ ⚫️ ⏮️ `@app.exception_handler(RequestValidationError)` 🎀 ⚠ 🐕🦺.
-
-⚠ 🐕🦺 🔜 📨 `Request` & ⚠.
-
-{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
-
-🔜, 🚥 👆 🚶 `/items/foo`, ↩️ 💆♂ 🔢 🎻 ❌ ⏮️:
-
-```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`, & 👆 💽 ✔️ ❌, 👆 🔜 👀 ❌ 👆 🕹.
-
-✋️ 👩💻/👩💻 🔜 🚫 👀 ⚫️. ↩️, 👩💻 🔜 📨 "🔗 💽 ❌" ⏮️ 🇺🇸🔍 👔 📟 `500`.
-
-⚫️ 🔜 👉 🌌 ↩️ 🚥 👆 ✔️ Pydantic `ValidationError` 👆 *📨* ⚖️ 🙆 👆 📟 (🚫 👩💻 *📨*), ⚫️ 🤙 🐛 👆 📟.
-
-& ⏪ 👆 🔧 ⚫️, 👆 👩💻/👩💻 🚫🔜 🚫 ✔️ 🔐 🔗 ℹ 🔃 ❌, 👈 💪 🎦 💂♂ ⚠.
-
-### 🔐 `HTTPException` ❌ 🐕🦺
-
-🎏 🌌, 👆 💪 🔐 `HTTPException` 🐕🦺.
-
-🖼, 👆 💪 💚 📨 ✅ ✍ 📨 ↩️ 🎻 👫 ❌:
-
-{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.responses import PlainTextResponse`.
-
-**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-### ⚙️ `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"
- }
-}
-```
-
-#### FastAPI `HTTPException` 🆚 💃 `HTTPException`
-
-**FastAPI** ✔️ 🚮 👍 `HTTPException`.
-
-& **FastAPI**'Ⓜ `HTTPException` ❌ 🎓 😖 ⚪️➡️ 💃 `HTTPException` ❌ 🎓.
-
-🕴 🔺, 👈 **FastAPI**'Ⓜ `HTTPException` ✔ 👆 🚮 🎚 🔌 📨.
-
-👉 💪/⚙️ 🔘 ✳ 2️⃣.0️⃣ & 💂♂ 🚙.
-
-, 👆 💪 🚧 🙋♀ **FastAPI**'Ⓜ `HTTPException` 🛎 👆 📟.
-
-✋️ 🕐❔ 👆 ® ⚠ 🐕🦺, 👆 🔜 ® ⚫️ 💃 `HTTPException`.
-
-👉 🌌, 🚥 🙆 🍕 💃 🔗 📟, ⚖️ 💃 ↔ ⚖️ 🔌 -, 🤚 💃 `HTTPException`, 👆 🐕🦺 🔜 💪 ✊ & 🍵 ⚫️.
-
-👉 🖼, 💪 ✔️ 👯♂️ `HTTPException`Ⓜ 🎏 📟, 💃 ⚠ 📁 `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/em/docs/tutorial/header-params.md b/docs/em/docs/tutorial/header-params.md
deleted file mode 100644
index fa5e3a22b..000000000
--- a/docs/em/docs/tutorial/header-params.md
+++ /dev/null
@@ -1,91 +0,0 @@
-# 🎚 🔢
-
-👆 💪 🔬 🎚 🔢 🎏 🌌 👆 🔬 `Query`, `Path` & `Cookie` 🔢.
-
-## 🗄 `Header`
-
-🥇 🗄 `Header`:
-
-{* ../../docs_src/header_params/tutorial001.py hl[3] *}
-
-## 📣 `Header` 🔢
-
-⤴️ 📣 🎚 🔢 ⚙️ 🎏 📊 ⏮️ `Path`, `Query` & `Cookie`.
-
-🥇 💲 🔢 💲, 👆 💪 🚶♀️ 🌐 ➕ 🔬 ⚖️ ✍ 🔢:
-
-{* ../../docs_src/header_params/tutorial001.py hl[9] *}
-
-/// note | 📡 ℹ
-
-`Header` "👭" 🎓 `Path`, `Query` & `Cookie`. ⚫️ 😖 ⚪️➡️ 🎏 ⚠ `Param` 🎓.
-
-✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `Header`, & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-
-///
-
-/// info
-
-📣 🎚, 👆 💪 ⚙️ `Header`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢.
-
-///
-
-## 🏧 🛠️
-
-`Header` ✔️ 🐥 ➕ 🛠️ 🔛 🔝 ⚫️❔ `Path`, `Query` & `Cookie` 🚚.
-
-🌅 🐩 🎚 🎏 "🔠" 🦹, 💭 "➖ 🔣" (`-`).
-
-✋️ 🔢 💖 `user-agent` ❌ 🐍.
-
-, 🔢, `Header` 🔜 🗜 🔢 📛 🦹 ⚪️➡️ 🎦 (`_`) 🔠 (`-`) ⚗ & 📄 🎚.
-
-, 🇺🇸🔍 🎚 💼-😛,, 👆 💪 📣 👫 ⏮️ 🐩 🐍 👗 (💭 "🔡").
-
-, 👆 💪 ⚙️ `user_agent` 👆 🛎 🔜 🐍 📟, ↩️ 💆♂ 🎯 🥇 🔤 `User_Agent` ⚖️ 🕳 🎏.
-
-🚥 🤔 👆 💪 ❎ 🏧 🛠️ 🎦 🔠, ⚒ 🔢 `convert_underscores` `Header` `False`:
-
-{* ../../docs_src/header_params/tutorial002.py hl[10] *}
-
-/// warning
-
-⏭ ⚒ `convert_underscores` `False`, 🐻 🤯 👈 🇺🇸🔍 🗳 & 💽 / ⚙️ 🎚 ⏮️ 🎦.
-
-///
-
-## ❎ 🎚
-
-⚫️ 💪 📨 ❎ 🎚. 👈 ⛓, 🎏 🎚 ⏮️ 💗 💲.
-
-👆 💪 🔬 👈 💼 ⚙️ 📇 🆎 📄.
-
-👆 🔜 📨 🌐 💲 ⚪️➡️ ❎ 🎚 🐍 `list`.
-
-🖼, 📣 🎚 `X-Token` 👈 💪 😑 🌅 🌘 🕐, 👆 💪 ✍:
-
-{* ../../docs_src/header_params/tutorial003.py hl[9] *}
-
-🚥 👆 🔗 ⏮️ 👈 *➡ 🛠️* 📨 2️⃣ 🇺🇸🔍 🎚 💖:
-
-```
-X-Token: foo
-X-Token: bar
-```
-
-📨 🔜 💖:
-
-```JSON
-{
- "X-Token values": [
- "bar",
- "foo"
- ]
-}
-```
-
-## 🌃
-
-📣 🎚 ⏮️ `Header`, ⚙️ 🎏 ⚠ ⚓ `Query`, `Path` & `Cookie`.
-
-& 🚫 😟 🔃 🎦 👆 🔢, **FastAPI** 🔜 ✊ 💅 🏭 👫.
diff --git a/docs/em/docs/tutorial/index.md b/docs/em/docs/tutorial/index.md
deleted file mode 100644
index 5f7532341..000000000
--- a/docs/em/docs/tutorial/index.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# 🔰 - 👩💻 🦮
-
-👉 🔰 🎦 👆 ❔ ⚙️ **FastAPI** ⏮️ 🌅 🚮 ⚒, 🔁 🔁.
-
-🔠 📄 📉 🏗 🔛 ⏮️ 🕐, ✋️ ⚫️ 🏗 🎏 ❔, 👈 👆 💪 🚶 🔗 🙆 🎯 1️⃣ ❎ 👆 🎯 🛠️ 💪.
-
-⚫️ 🏗 👷 🔮 🔗.
-
-👆 💪 👟 🔙 & 👀 ⚫️❔ ⚫️❔ 👆 💪.
-
-## 🏃 📟
-
-🌐 📟 🍫 💪 📁 & ⚙️ 🔗 (👫 🤙 💯 🐍 📁).
-
-🏃 🙆 🖼, 📁 📟 📁 `main.py`, & ▶️ `uvicorn` ⏮️:
-
-contact 🏑| 🔢 | 🆎 | 📛 |
|---|---|---|
name | str | ⚖ 📛 📧 👨💼/🏢. |
url | str | 📛 ☝ 📧 ℹ. 🔜 📁 📛. |
email | str | 📧 📢 📧 👨💼/🏢. 🔜 📁 📧 📢. |
license_info 🏑| 🔢 | 🆎 | 📛 |
|---|---|---|
name | str | 🚚 (🚥 license_info ⚒). 🛂 📛 ⚙️ 🛠️. |
url | str | 📛 🛂 ⚙️ 🛠️. 🔜 📁 📛. |
-
-## 🗃 🔖
-
-👆 💪 🚮 🌖 🗃 🎏 🔖 ⚙️ 👪 👆 ➡ 🛠️ ⏮️ 🔢 `openapi_tags`.
-
-⚫️ ✊ 📇 ⚗ 1️⃣ 📖 🔠 🔖.
-
-🔠 📖 💪 🔌:
-
-* `name` (**✔**): `str` ⏮️ 🎏 📛 👆 ⚙️ `tags` 🔢 👆 *➡ 🛠️* & `APIRouter`Ⓜ.
-* `description`: `str` ⏮️ 📏 📛 🔖. ⚫️ 💪 ✔️ ✍ & 🔜 🎦 🩺 🎚.
-* `externalDocs`: `dict` 🔬 🔢 🧾 ⏮️:
- * `description`: `str` ⏮️ 📏 📛 🔢 🩺.
- * `url` (**✔**): `str` ⏮️ 📛 🔢 🧾.
-
-### ✍ 🗃 🔖
-
-➡️ 🔄 👈 🖼 ⏮️ 🔖 `users` & `items`.
-
-✍ 🗃 👆 🔖 & 🚶♀️ ⚫️ `openapi_tags` 🔢:
-
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
-
-👀 👈 👆 💪 ⚙️ ✍ 🔘 📛, 🖼 "💳" 🔜 🎦 🦁 (**💳**) & "🎀" 🔜 🎦 ❕ (_🎀_).
-
-/// tip
-
-👆 🚫 ✔️ 🚮 🗃 🌐 🔖 👈 👆 ⚙️.
-
-///
-
-### ⚙️ 👆 🔖
-
-⚙️ `tags` 🔢 ⏮️ 👆 *➡ 🛠️* (& `APIRouter`Ⓜ) 🛠️ 👫 🎏 🔖:
-
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
-
-/// info
-
-✍ 🌅 🔃 🔖 [➡ 🛠️ 📳](path-operation-configuration.md#_3){.internal-link target=_blank}.
-
-///
-
-### ✅ 🩺
-
-🔜, 🚥 👆 ✅ 🩺, 👫 🔜 🎦 🌐 🌖 🗃:
-
-
-
-### ✔ 🔖
-
-✔ 🔠 🔖 🗃 📖 🔬 ✔ 🎦 🩺 🎚.
-
-🖼, ✋️ `users` 🔜 🚶 ⏮️ `items` 🔤 ✔, ⚫️ 🎦 ⏭ 👫, ↩️ 👥 🚮 👫 🗃 🥇 📖 📇.
-
-## 🗄 📛
-
-🔢, 🗄 🔗 🍦 `/openapi.json`.
-
-✋️ 👆 💪 🔗 ⚫️ ⏮️ 🔢 `openapi_url`.
-
-🖼, ⚒ ⚫️ 🍦 `/api/v1/openapi.json`:
-
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
-
-🚥 👆 💚 ❎ 🗄 🔗 🍕 👆 💪 ⚒ `openapi_url=None`, 👈 🔜 ❎ 🧾 👩💻 🔢 👈 ⚙️ ⚫️.
-
-## 🩺 📛
-
-👆 💪 🔗 2️⃣ 🧾 👩💻 🔢 🔌:
-
-* **🦁 🎚**: 🍦 `/docs`.
- * 👆 💪 ⚒ 🚮 📛 ⏮️ 🔢 `docs_url`.
- * 👆 💪 ❎ ⚫️ ⚒ `docs_url=None`.
-* **📄**: 🍦 `/redoc`.
- * 👆 💪 ⚒ 🚮 📛 ⏮️ 🔢 `redoc_url`.
- * 👆 💪 ❎ ⚫️ ⚒ `redoc_url=None`.
-
-🖼, ⚒ 🦁 🎚 🍦 `/documentation` & ❎ 📄:
-
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
diff --git a/docs/em/docs/tutorial/middleware.md b/docs/em/docs/tutorial/middleware.md
deleted file mode 100644
index d203471e8..000000000
--- a/docs/em/docs/tutorial/middleware.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# 🛠️
-
-👆 💪 🚮 🛠️ **FastAPI** 🈸.
-
-"🛠️" 🔢 👈 👷 ⏮️ 🔠 **📨** ⏭ ⚫️ 🛠️ 🙆 🎯 *➡ 🛠️*. & ⏮️ 🔠 **📨** ⏭ 🛬 ⚫️.
-
-* ⚫️ ✊ 🔠 **📨** 👈 👟 👆 🈸.
-* ⚫️ 💪 ⤴️ 🕳 👈 **📨** ⚖️ 🏃 🙆 💪 📟.
-* ⤴️ ⚫️ 🚶♀️ **📨** 🛠️ 🎂 🈸 ( *➡ 🛠️*).
-* ⚫️ ⤴️ ✊ **📨** 🏗 🈸 ( *➡ 🛠️*).
-* ⚫️ 💪 🕳 👈 **📨** ⚖️ 🏃 🙆 💪 📟.
-* ⤴️ ⚫️ 📨 **📨**.
-
-/// note | 📡 ℹ
-
-🚥 👆 ✔️ 🔗 ⏮️ `yield`, 🚪 📟 🔜 🏃 *⏮️* 🛠️.
-
-🚥 📤 🙆 🖥 📋 (📄 ⏪), 👫 🔜 🏃 *⏮️* 🌐 🛠️.
-
-///
-
-## ✍ 🛠️
-
-✍ 🛠️ 👆 ⚙️ 👨🎨 `@app.middleware("http")` 🔛 🔝 🔢.
-
-🛠️ 🔢 📨:
-
-* `request`.
-* 🔢 `call_next` 👈 🔜 📨 `request` 🔢.
- * 👉 🔢 🔜 🚶♀️ `request` 🔗 *➡ 🛠️*.
- * ⤴️ ⚫️ 📨 `response` 🏗 🔗 *➡ 🛠️*.
-* 👆 💪 ⤴️ 🔀 🌅 `response` ⏭ 🛬 ⚫️.
-
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-
-/// tip
-
-✔️ 🤯 👈 🛃 © 🎚 💪 🚮 ⚙️ '✖-' 🔡.
-
-✋️ 🚥 👆 ✔️ 🛃 🎚 👈 👆 💚 👩💻 🖥 💪 👀, 👆 💪 🚮 👫 👆 ⚜ 📳 ([⚜ (✖️-🇨🇳 ℹ 🤝)](cors.md){.internal-link target=_blank}) ⚙️ 🔢 `expose_headers` 📄 💃 ⚜ 🩺.
-
-///
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.requests import Request`.
-
-**FastAPI** 🚚 ⚫️ 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-### ⏭ & ⏮️ `response`
-
-👆 💪 🚮 📟 🏃 ⏮️ `request`, ⏭ 🙆 *➡ 🛠️* 📨 ⚫️.
-
-& ⏮️ `response` 🏗, ⏭ 🛬 ⚫️.
-
-🖼, 👆 💪 🚮 🛃 🎚 `X-Process-Time` ⚗ 🕰 🥈 👈 ⚫️ ✊ 🛠️ 📨 & 🏗 📨:
-
-{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
-
-## 🎏 🛠️
-
-👆 💪 ⏪ ✍ 🌖 🔃 🎏 🛠️ [🏧 👩💻 🦮: 🏧 🛠️](../advanced/middleware.md){.internal-link target=_blank}.
-
-👆 🔜 ✍ 🔃 ❔ 🍵 ⚜ ⏮️ 🛠️ ⏭ 📄.
diff --git a/docs/em/docs/tutorial/path-operation-configuration.md b/docs/em/docs/tutorial/path-operation-configuration.md
deleted file mode 100644
index c6030c089..000000000
--- a/docs/em/docs/tutorial/path-operation-configuration.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# ➡ 🛠️ 📳
-
-📤 📚 🔢 👈 👆 💪 🚶♀️ 👆 *➡ 🛠️ 👨🎨* 🔗 ⚫️.
-
-/// warning
-
-👀 👈 👫 🔢 🚶♀️ 🔗 *➡ 🛠️ 👨🎨*, 🚫 👆 *➡ 🛠️ 🔢*.
-
-///
-
-## 📨 👔 📟
-
-👆 💪 🔬 (🇺🇸🔍) `status_code` ⚙️ 📨 👆 *➡ 🛠️*.
-
-👆 💪 🚶♀️ 🔗 `int` 📟, 💖 `404`.
-
-✋️ 🚥 👆 🚫 💭 ⚫️❔ 🔠 🔢 📟, 👆 💪 ⚙️ ⌨ 📉 `status`:
-
-{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
-
-👈 👔 📟 🔜 ⚙️ 📨 & 🔜 🚮 🗄 🔗.
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette import status`.
-
-**FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-## 🔖
-
-👆 💪 🚮 🔖 👆 *➡ 🛠️*, 🚶♀️ 🔢 `tags` ⏮️ `list` `str` (🛎 1️⃣ `str`):
-
-{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
-
-👫 🔜 🚮 🗄 🔗 & ⚙️ 🏧 🧾 🔢:
-
-
-
-### 🔖 ⏮️ 🔢
-
-🚥 👆 ✔️ 🦏 🈸, 👆 5️⃣📆 🔚 🆙 📈 **📚 🔖**, & 👆 🔜 💚 ⚒ 💭 👆 🕧 ⚙️ **🎏 🔖** 🔗 *➡ 🛠️*.
-
-👫 💼, ⚫️ 💪 ⚒ 🔑 🏪 🔖 `Enum`.
-
-**FastAPI** 🐕🦺 👈 🎏 🌌 ⏮️ ✅ 🎻:
-
-{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
-
-## 📄 & 📛
-
-👆 💪 🚮 `summary` & `description`:
-
-{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
-
-## 📛 ⚪️➡️ #️⃣
-
-📛 😑 📏 & 📔 💗 ⏸, 👆 💪 📣 *➡ 🛠️* 📛 🔢 #️⃣ & **FastAPI** 🔜 ✍ ⚫️ ⚪️➡️ 📤.
-
-👆 💪 ✍ ✍ #️⃣ , ⚫️ 🔜 🔬 & 🖥 ☑ (✊ 🔘 🏧 #️⃣ 📐).
-
-{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
-
-⚫️ 🔜 ⚙️ 🎓 🩺:
-
-
-
-## 📨 📛
-
-👆 💪 ✔ 📨 📛 ⏮️ 🔢 `response_description`:
-
-{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
-
-/// info
-
-👀 👈 `response_description` 🔗 🎯 📨, `description` 🔗 *➡ 🛠️* 🏢.
-
-///
-
-/// check
-
-🗄 ✔ 👈 🔠 *➡ 🛠️* 🚚 📨 📛.
-
-, 🚥 👆 🚫 🚚 1️⃣, **FastAPI** 🔜 🔁 🏗 1️⃣ "🏆 📨".
-
-///
-
-
-
-## 😢 *➡ 🛠️*
-
-🚥 👆 💪 ™ *➡ 🛠️* 😢, ✋️ 🍵 ❎ ⚫️, 🚶♀️ 🔢 `deprecated`:
-
-{* ../../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
deleted file mode 100644
index b45e0557b..000000000
--- a/docs/em/docs/tutorial/path-params-numeric-validations.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# ➡ 🔢 & 🔢 🔬
-
-🎏 🌌 👈 👆 💪 📣 🌅 🔬 & 🗃 🔢 🔢 ⏮️ `Query`, 👆 💪 📣 🎏 🆎 🔬 & 🗃 ➡ 🔢 ⏮️ `Path`.
-
-## 🗄 ➡
-
-🥇, 🗄 `Path` ⚪️➡️ `fastapi`:
-
-{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[3] *}
-
-## 📣 🗃
-
-👆 💪 📣 🌐 🎏 🔢 `Query`.
-
-🖼, 📣 `title` 🗃 💲 ➡ 🔢 `item_id` 👆 💪 🆎:
-
-{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[10] *}
-
-/// note
-
-➡ 🔢 🕧 ✔ ⚫️ ✔️ 🍕 ➡.
-
-, 👆 🔜 📣 ⚫️ ⏮️ `...` ™ ⚫️ ✔.
-
-👐, 🚥 👆 📣 ⚫️ ⏮️ `None` ⚖️ ⚒ 🔢 💲, ⚫️ 🔜 🚫 📉 🕳, ⚫️ 🔜 🕧 🚚.
-
-///
-
-## ✔ 🔢 👆 💪
-
-➡️ 💬 👈 👆 💚 📣 🔢 🔢 `q` ✔ `str`.
-
-& 👆 🚫 💪 📣 🕳 🙆 👈 🔢, 👆 🚫 🤙 💪 ⚙️ `Query`.
-
-✋️ 👆 💪 ⚙️ `Path` `item_id` ➡ 🔢.
-
-🐍 🔜 😭 🚥 👆 🚮 💲 ⏮️ "🔢" ⏭ 💲 👈 🚫 ✔️ "🔢".
-
-✋️ 👆 💪 🏤-✔ 👫, & ✔️ 💲 🍵 🔢 (🔢 🔢 `q`) 🥇.
-
-⚫️ 🚫 🤔 **FastAPI**. ⚫️ 🔜 🔍 🔢 👫 📛, 🆎 & 🔢 📄 (`Query`, `Path`, ♒️), ⚫️ 🚫 💅 🔃 ✔.
-
-, 👆 💪 📣 👆 🔢:
-
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
-
-## ✔ 🔢 👆 💪, 🎱
-
-🚥 👆 💚 📣 `q` 🔢 🔢 🍵 `Query` 🚫 🙆 🔢 💲, & ➡ 🔢 `item_id` ⚙️ `Path`, & ✔️ 👫 🎏 ✔, 🐍 ✔️ 🐥 🎁 ❕ 👈.
-
-🚶♀️ `*`, 🥇 🔢 🔢.
-
-🐍 🏆 🚫 🕳 ⏮️ 👈 `*`, ✋️ ⚫️ 🔜 💭 👈 🌐 📄 🔢 🔜 🤙 🇨🇻 ❌ (🔑-💲 👫), 💭 kwargs. 🚥 👫 🚫 ✔️ 🔢 💲.
-
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
-
-## 🔢 🔬: 👑 🌘 ⚖️ 🌓
-
-⏮️ `Query` & `Path` (& 🎏 👆 🔜 👀 ⏪) 👆 💪 📣 🔢 ⚛.
-
-📥, ⏮️ `ge=1`, `item_id` 🔜 💪 🔢 🔢 "`g`🅾 🌘 ⚖️ `e`🅾" `1`.
-
-{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
-
-## 🔢 🔬: 🌘 🌘 & 🌘 🌘 ⚖️ 🌓
-
-🎏 ✔:
-
-* `gt`: `g`🅾 `t`👲
-* `le`: `l`👭 🌘 ⚖️ `e`🅾
-
-{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
-
-## 🔢 🔬: 🎈, 🌘 🌘 & 🌘 🌘
-
-🔢 🔬 👷 `float` 💲.
-
-📥 🌐❔ ⚫️ ▶️️ ⚠ 💪 📣 gt & 🚫 ge. ⏮️ ⚫️ 👆 💪 🚚, 🖼, 👈 💲 🔜 👑 🌘 `0`, 🚥 ⚫️ 🌘 🌘 `1`.
-
-, `0.5` 🔜 ☑ 💲. ✋️ `0.0` ⚖️ `0` 🔜 🚫.
-
-& 🎏 lt.
-
-{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
-
-## 🌃
-
-⏮️ `Query`, `Path` (& 🎏 👆 🚫 👀) 👆 💪 📣 🗃 & 🎻 🔬 🎏 🌌 ⏮️ [🔢 🔢 & 🎻 🔬](query-params-str-validations.md){.internal-link target=_blank}.
-
-& 👆 💪 📣 🔢 🔬:
-
-* `gt`: `g`🅾 `t`👲
-* `ge`: `g`🅾 🌘 ⚖️ `e`🅾
-* `lt`: `l`👭 `t`👲
-* `le`: `l`👭 🌘 ⚖️ `e`🅾
-
-/// info
-
-`Query`, `Path`, & 🎏 🎓 👆 🔜 👀 ⏪ 🏿 ⚠ `Param` 🎓.
-
-🌐 👫 💰 🎏 🔢 🌖 🔬 & 🗃 👆 ✔️ 👀.
-
-///
-
-/// note | 📡 ℹ
-
-🕐❔ 👆 🗄 `Query`, `Path` & 🎏 ⚪️➡️ `fastapi`, 👫 🤙 🔢.
-
-👈 🕐❔ 🤙, 📨 👐 🎓 🎏 📛.
-
-, 👆 🗄 `Query`, ❔ 🔢. & 🕐❔ 👆 🤙 ⚫️, ⚫️ 📨 👐 🎓 🌟 `Query`.
-
-👫 🔢 📤 (↩️ ⚙️ 🎓 🔗) 👈 👆 👨🎨 🚫 ™ ❌ 🔃 👫 🆎.
-
-👈 🌌 👆 💪 ⚙️ 👆 😐 👨🎨 & 🛠️ 🧰 🍵 ✔️ 🚮 🛃 📳 🤷♂ 📚 ❌.
-
-///
diff --git a/docs/em/docs/tutorial/path-params.md b/docs/em/docs/tutorial/path-params.md
deleted file mode 100644
index a914dc905..000000000
--- a/docs/em/docs/tutorial/path-params.md
+++ /dev/null
@@ -1,256 +0,0 @@
-# ➡ 🔢
-
-👆 💪 📣 ➡ "🔢" ⚖️ "🔢" ⏮️ 🎏 ❕ ⚙️ 🐍 📁 🎻:
-
-{* ../../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"}
-```
-
-## ➡ 🔢 ⏮️ 🆎
-
-👆 💪 📣 🆎 ➡ 🔢 🔢, ⚙️ 🐩 🐍 🆎 ✍:
-
-{* ../../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`, 🐍 `int`, 🚫 🎻 `"3"`.
-
-, ⏮️ 👈 🆎 📄, **FastAPI** 🤝 👆 🏧 📨 "✍".
-
-///
-
-## 💽 🔬
-
-✋️ 🚥 👆 🚶 🖥 http://127.0.0.1:8000/items/foo, 👆 🔜 👀 👌 🇺🇸🔍 ❌:
-
-```JSON
-{
- "detail": [
- {
- "loc": [
- "path",
- "item_id"
- ],
- "msg": "value is not a valid integer",
- "type": "type_error.integer"
- }
- ]
-}
-```
-
-↩️ ➡ 🔢 `item_id` ✔️ 💲 `"foo"`, ❔ 🚫 `int`.
-
-🎏 ❌ 🔜 😑 🚥 👆 🚚 `float` ↩️ `int`,: http://127.0.0.1:8000/items/4.2
-
-/// check
-
-, ⏮️ 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 💽 🔬.
-
-👀 👈 ❌ 🎯 🇵🇸 ⚫️❔ ☝ 🌐❔ 🔬 🚫 🚶♀️.
-
-👉 🙃 👍 ⏪ 🛠️ & 🛠️ 📟 👈 🔗 ⏮️ 👆 🛠️.
-
-///
-
-## 🧾
-
-& 🕐❔ 👆 📂 👆 🖥 http://127.0.0.1:8000/docs, 👆 🔜 👀 🏧, 🎓, 🛠️ 🧾 💖:
-
-
-
-/// check
-
-🔄, ⏮️ 👈 🎏 🐍 🆎 📄, **FastAPI** 🤝 👆 🏧, 🎓 🧾 (🛠️ 🦁 🎚).
-
-👀 👈 ➡ 🔢 📣 🔢.
-
-///
-
-## 🐩-⚓️ 💰, 🎛 🧾
-
-& ↩️ 🏗 🔗 ⚪️➡️ 🗄 🐩, 📤 📚 🔗 🧰.
-
-↩️ 👉, **FastAPI** ⚫️ 🚚 🎛 🛠️ 🧾 (⚙️ 📄), ❔ 👆 💪 🔐 http://127.0.0.1:8000/redoc:
-
-
-
-🎏 🌌, 📤 📚 🔗 🧰. ✅ 📟 ⚡ 🧰 📚 🇪🇸.
-
-## Pydantic
-
-🌐 💽 🔬 🎭 🔽 🚘 Pydantic, 👆 🤚 🌐 💰 ⚪️➡️ ⚫️. & 👆 💭 👆 👍 ✋.
-
-👆 💪 ⚙️ 🎏 🆎 📄 ⏮️ `str`, `float`, `bool` & 📚 🎏 🏗 📊 🆎.
-
-📚 👫 🔬 ⏭ 📃 🔰.
-
-## ✔ 🤔
-
-🕐❔ 🏗 *➡ 🛠️*, 👆 💪 🔎 ⚠ 🌐❔ 👆 ✔️ 🔧 ➡.
-
-💖 `/users/me`, ➡️ 💬 👈 ⚫️ 🤚 📊 🔃 ⏮️ 👩💻.
-
-& ⤴️ 👆 💪 ✔️ ➡ `/users/{user_id}` 🤚 💽 🔃 🎯 👩💻 👩💻 🆔.
-
-↩️ *➡ 🛠️* 🔬 ✔, 👆 💪 ⚒ 💭 👈 ➡ `/users/me` 📣 ⏭ 1️⃣ `/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] *}
-
-🥇 🕐 🔜 🕧 ⚙️ ↩️ ➡ 🏏 🥇.
-
-## 🔁 💲
-
-🚥 👆 ✔️ *➡ 🛠️* 👈 📨 *➡ 🔢*, ✋️ 👆 💚 💪 ☑ *➡ 🔢* 💲 🔁, 👆 💪 ⚙️ 🐩 🐍 `Enum`.
-
-### ✍ `Enum` 🎓
-
-🗄 `Enum` & ✍ 🎧-🎓 👈 😖 ⚪️➡️ `str` & ⚪️➡️ `Enum`.
-
-😖 ⚪️➡️ `str` 🛠️ 🩺 🔜 💪 💭 👈 💲 🔜 🆎 `string` & 🔜 💪 ✍ ☑.
-
-⤴️ ✍ 🎓 🔢 ⏮️ 🔧 💲, ❔ 🔜 💪 ☑ 💲:
-
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-
-/// info
-
-🔢 (⚖️ 🔢) 💪 🐍 ↩️ ⏬ 3️⃣.4️⃣.
-
-///
-
-/// tip
-
-🚥 👆 💭, "📊", "🎓", & "🍏" 📛 🎰 🏫 🏷.
-
-///
-
-### 📣 *➡ 🔢*
-
-⤴️ ✍ *➡ 🔢* ⏮️ 🆎 ✍ ⚙️ 🔢 🎓 👆 ✍ (`ModelName`):
-
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
-
-### ✅ 🩺
-
-↩️ 💪 💲 *➡ 🔢* 🔢, 🎓 🩺 💪 🎦 👫 🎆:
-
-
-
-### 👷 ⏮️ 🐍 *🔢*
-
-💲 *➡ 🔢* 🔜 *🔢 👨🎓*.
-
-#### 🔬 *🔢 👨🎓*
-
-👆 💪 🔬 ⚫️ ⏮️ *🔢 👨🎓* 👆 ✍ 🔢 `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`.
-
-///
-
-#### 📨 *🔢 👨🎓*
-
-👆 💪 📨 *🔢 👨🎓* ⚪️➡️ 👆 *➡ 🛠️*, 🐦 🎻 💪 (✅ `dict`).
-
-👫 🔜 🗜 👫 🔗 💲 (🎻 👉 💼) ⏭ 🛬 👫 👩💻:
-
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
-
-👆 👩💻 👆 🔜 🤚 🎻 📨 💖:
-
-```JSON
-{
- "model_name": "alexnet",
- "message": "Deep Learning FTW!"
-}
-```
-
-## ➡ 🔢 ⚗ ➡
-
-➡️ 💬 👆 ✔️ *➡ 🛠️* ⏮️ ➡ `/files/{file_path}`.
-
-✋️ 👆 💪 `file_path` ⚫️ 🔌 *➡*, 💖 `home/johndoe/myfile.txt`.
-
-, 📛 👈 📁 🔜 🕳 💖: `/files/home/johndoe/myfile.txt`.
-
-### 🗄 🐕🦺
-
-🗄 🚫 🐕🦺 🌌 📣 *➡ 🔢* 🔌 *➡* 🔘, 👈 💪 ↘️ 😐 👈 ⚠ 💯 & 🔬.
-
-👐, 👆 💪 ⚫️ **FastAPI**, ⚙️ 1️⃣ 🔗 🧰 ⚪️➡️ 💃.
-
-& 🩺 🔜 👷, 👐 🚫 ❎ 🙆 🧾 💬 👈 🔢 🔜 🔌 ➡.
-
-### ➡ 🔌
-
-⚙️ 🎛 🔗 ⚪️➡️ 💃 👆 💪 📣 *➡ 🔢* ⚗ *➡* ⚙️ 📛 💖:
-
-```
-/files/{file_path:path}
-```
-
-👉 💼, 📛 🔢 `file_path`, & 🏁 🍕, `:path`, 💬 ⚫️ 👈 🔢 🔜 🏏 🙆 *➡*.
-
-, 👆 💪 ⚙️ ⚫️ ⏮️:
-
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
-
-/// tip
-
-👆 💪 💪 🔢 🔌 `/home/johndoe/myfile.txt`, ⏮️ 🏁 🔪 (`/`).
-
-👈 💼, 📛 🔜: `/files//home/johndoe/myfile.txt`, ⏮️ 2️⃣✖️ 🔪 (`//`) 🖖 `files` & `home`.
-
-///
-
-## 🌃
-
-⏮️ **FastAPI**, ⚙️ 📏, 🏋️ & 🐩 🐍 🆎 📄, 👆 🤚:
-
-* 👨🎨 🐕🦺: ❌ ✅, ✍, ♒️.
-* 💽 "✍"
-* 💽 🔬
-* 🛠️ ✍ & 🏧 🧾
-
-& 👆 🕴 ✔️ 📣 👫 🕐.
-
-👈 🎲 👑 ⭐ 📈 **FastAPI** 🔬 🎛 🛠️ (↖️ ⚪️➡️ 🍣 🎭).
diff --git a/docs/em/docs/tutorial/query-params-str-validations.md b/docs/em/docs/tutorial/query-params-str-validations.md
deleted file mode 100644
index fd077bf8f..000000000
--- a/docs/em/docs/tutorial/query-params-str-validations.md
+++ /dev/null
@@ -1,320 +0,0 @@
-# 🔢 🔢 & 🎻 🔬
-
-**FastAPI** ✔ 👆 📣 🌖 ℹ & 🔬 👆 🔢.
-
-➡️ ✊ 👉 🈸 🖼:
-
-{* ../../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`.
-
- `Union` `Union[str, None]` 🔜 ✔ 👆 👨🎨 🤝 👆 👍 🐕🦺 & 🔍 ❌.
-
-///
-
-## 🌖 🔬
-
-👥 🔜 🛠️ 👈 ✋️ `q` 📦, 🕐❔ ⚫️ 🚚, **🚮 📐 🚫 📉 5️⃣0️⃣ 🦹**.
-
-### 🗄 `Query`
-
-🏆 👈, 🥇 🗄 `Query` ⚪️➡️ `fastapi`:
-
-{* ../../docs_src/query_params_str_validations/tutorial002.py hl[3] *}
-
-## ⚙️ `Query` 🔢 💲
-
-& 🔜 ⚙️ ⚫️ 🔢 💲 👆 🔢, ⚒ 🔢 `max_length` 5️⃣0️⃣:
-
-{* ../../docs_src/query_params_str_validations/tutorial002.py hl[9] *}
-
-👥 ✔️ ❎ 🔢 💲 `None` 🔢 ⏮️ `Query()`, 👥 💪 🔜 ⚒ 🔢 💲 ⏮️ 🔢 `Query(default=None)`, ⚫️ 🍦 🎏 🎯 ⚖ 👈 🔢 💲.
-
-:
-
-```Python
-q: Union[str, None] = Query(default=None)
-```
-
-...⚒ 🔢 📦, 🎏:
-
-```Python
-q: Union[str, None] = None
-```
-
-& 🐍 3️⃣.1️⃣0️⃣ & 🔛:
-
-```Python
-q: str | None = Query(default=None)
-```
-
-...⚒ 🔢 📦, 🎏:
-
-```Python
-q: str | None = None
-```
-
-✋️ ⚫️ 📣 ⚫️ 🎯 💆♂ 🔢 🔢.
-
-/// info
-
-✔️ 🤯 👈 🌅 ⚠ 🍕 ⚒ 🔢 📦 🍕:
-
-```Python
-= None
-```
-
-⚖️:
-
-```Python
-= Query(default=None)
-```
-
-⚫️ 🔜 ⚙️ 👈 `None` 🔢 💲, & 👈 🌌 ⚒ 🔢 **🚫 ✔**.
-
- `Union[str, None]` 🍕 ✔ 👆 👨🎨 🚚 👻 🐕🦺, ✋️ ⚫️ 🚫 ⚫️❔ 💬 FastAPI 👈 👉 🔢 🚫 ✔.
-
-///
-
-⤴️, 👥 💪 🚶♀️ 🌅 🔢 `Query`. 👉 💼, `max_length` 🔢 👈 ✔ 🎻:
-
-```Python
-q: Union[str, None] = Query(default=None, max_length=50)
-```
-
-👉 🔜 ✔ 📊, 🎦 🆑 ❌ 🕐❔ 📊 🚫 ☑, & 📄 🔢 🗄 🔗 *➡ 🛠️*.
-
-## 🚮 🌅 🔬
-
-👆 💪 🚮 🔢 `min_length`:
-
-{* ../../docs_src/query_params_str_validations/tutorial003.py hl[10] *}
-
-## 🚮 🥔 🧬
-
-👆 💪 🔬 🥔 🧬 👈 🔢 🔜 🏏:
-
-{* ../../docs_src/query_params_str_validations/tutorial004.py hl[11] *}
-
-👉 🎯 🥔 🧬 ✅ 👈 📨 🔢 💲:
-
-* `^`: ▶️ ⏮️ 📄 🦹, 🚫 ✔️ 🦹 ⏭.
-* `fixedquery`: ✔️ ☑ 💲 `fixedquery`.
-* `$`: 🔚 📤, 🚫 ✔️ 🙆 🌖 🦹 ⏮️ `fixedquery`.
-
-🚥 👆 💭 💸 ⏮️ 🌐 👉 **"🥔 🧬"** 💭, 🚫 😟. 👫 🏋️ ❔ 📚 👫👫. 👆 💪 📚 💩 🍵 💆♂ 🥔 🧬.
-
-✋️ 🕐❔ 👆 💪 👫 & 🚶 & 💡 👫, 💭 👈 👆 💪 ⏪ ⚙️ 👫 🔗 **FastAPI**.
-
-## 🔢 💲
-
-🎏 🌌 👈 👆 💪 🚶♀️ `None` 💲 `default` 🔢, 👆 💪 🚶♀️ 🎏 💲.
-
-➡️ 💬 👈 👆 💚 📣 `q` 🔢 🔢 ✔️ `min_length` `3`, & ✔️ 🔢 💲 `"fixedquery"`:
-
-{* ../../docs_src/query_params_str_validations/tutorial005.py hl[7] *}
-
-/// note
-
-✔️ 🔢 💲 ⚒ 🔢 📦.
-
-///
-
-## ⚒ ⚫️ ✔
-
-🕐❔ 👥 🚫 💪 📣 🌅 🔬 ⚖️ 🗃, 👥 💪 ⚒ `q` 🔢 🔢 ✔ 🚫 📣 🔢 💲, 💖:
-
-```Python
-q: str
-```
-
-↩️:
-
-```Python
-q: Union[str, None] = None
-```
-
-✋️ 👥 🔜 📣 ⚫️ ⏮️ `Query`, 🖼 💖:
-
-```Python
-q: Union[str, None] = Query(default=None, min_length=3)
-```
-
-, 🕐❔ 👆 💪 📣 💲 ✔ ⏪ ⚙️ `Query`, 👆 💪 🎯 🚫 📣 🔢 💲:
-
-{* ../../docs_src/query_params_str_validations/tutorial006.py hl[7] *}
-
-### ✔ ⏮️ `None`
-
-👆 💪 📣 👈 🔢 💪 🚫 `None`, ✋️ 👈 ⚫️ ✔. 👉 🔜 ⚡ 👩💻 📨 💲, 🚥 💲 `None`.
-
-👈, 👆 💪 📣 👈 `None` ☑ 🆎 ✋️ ⚙️ `default=...`:
-
-{* ../../docs_src/query_params_str_validations/tutorial006c.py hl[9] *}
-
-/// tip
-
-Pydantic, ❔ ⚫️❔ 🏋️ 🌐 💽 🔬 & 🛠️ FastAPI, ✔️ 🎁 🎭 🕐❔ 👆 ⚙️ `Optional` ⚖️ `Union[Something, None]` 🍵 🔢 💲, 👆 💪 ✍ 🌅 🔃 ⚫️ Pydantic 🩺 🔃 ✔ 📦 🏑.
-
-///
-
-## 🔢 🔢 📇 / 💗 💲
-
-🕐❔ 👆 🔬 🔢 🔢 🎯 ⏮️ `Query` 👆 💪 📣 ⚫️ 📨 📇 💲, ⚖️ 🙆♀ 🎏 🌌, 📨 💗 💲.
-
-🖼, 📣 🔢 🔢 `q` 👈 💪 😑 💗 🕰 📛, 👆 💪 ✍:
-
-{* ../../docs_src/query_params_str_validations/tutorial011.py hl[9] *}
-
-⤴️, ⏮️ 📛 💖:
-
-```
-http://localhost:8000/items/?q=foo&q=bar
-```
-
-👆 🔜 📨 💗 `q` *🔢 🔢'* 💲 (`foo` & `bar`) 🐍 `list` 🔘 👆 *➡ 🛠️ 🔢*, *🔢 🔢* `q`.
-
-, 📨 👈 📛 🔜:
-
-```JSON
-{
- "q": [
- "foo",
- "bar"
- ]
-}
-```
-
-/// tip
-
-📣 🔢 🔢 ⏮️ 🆎 `list`, 💖 🖼 🔛, 👆 💪 🎯 ⚙️ `Query`, ⏪ ⚫️ 🔜 🔬 📨 💪.
-
-///
-
-🎓 🛠️ 🩺 🔜 ℹ ➡️, ✔ 💗 💲:
-
-
-
-### 🔢 🔢 📇 / 💗 💲 ⏮️ 🔢
-
-& 👆 💪 🔬 🔢 `list` 💲 🚥 👌 🚚:
-
-{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
-
-🚥 👆 🚶:
-
-```
-http://localhost:8000/items/
-```
-
-🔢 `q` 🔜: `["foo", "bar"]` & 👆 📨 🔜:
-
-```JSON
-{
- "q": [
- "foo",
- "bar"
- ]
-}
-```
-
-#### ⚙️ `list`
-
-👆 💪 ⚙️ `list` 🔗 ↩️ `List[str]` (⚖️ `list[str]` 🐍 3️⃣.9️⃣ ➕):
-
-{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
-
-/// note
-
-✔️ 🤯 👈 👉 💼, FastAPI 🏆 🚫 ✅ 🎚 📇.
-
-🖼, `List[int]` 🔜 ✅ (& 📄) 👈 🎚 📇 🔢. ✋️ `list` 😞 🚫🔜.
-
-///
-
-## 📣 🌅 🗃
-
-👆 💪 🚮 🌅 ℹ 🔃 🔢.
-
-👈 ℹ 🔜 🔌 🏗 🗄 & ⚙️ 🧾 👩💻 🔢 & 🔢 🧰.
-
-/// note
-
-✔️ 🤯 👈 🎏 🧰 5️⃣📆 ✔️ 🎏 🎚 🗄 🐕🦺.
-
-👫 💪 🚫 🎦 🌐 ➕ ℹ 📣, 👐 🌅 💼, ❌ ⚒ ⏪ 📄 🛠️.
-
-///
-
-👆 💪 🚮 `title`:
-
-{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
-
-& `description`:
-
-{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
-
-## 📛 🔢
-
-🌈 👈 👆 💚 🔢 `item-query`.
-
-💖:
-
-```
-http://127.0.0.1:8000/items/?item-query=foobaritems
-```
-
-✋️ `item-query` 🚫 ☑ 🐍 🔢 📛.
-
-🔐 🔜 `item_query`.
-
-✋️ 👆 💪 ⚫️ ⚫️❔ `item-query`...
-
-⤴️ 👆 💪 📣 `alias`, & 👈 📛 ⚫️❔ 🔜 ⚙️ 🔎 🔢 💲:
-
-{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
-
-## 😛 🔢
-
-🔜 ➡️ 💬 👆 🚫 💖 👉 🔢 🚫🔜.
-
-👆 ✔️ 👈 ⚫️ 📤 ⏪ ↩️ 📤 👩💻 ⚙️ ⚫️, ✋️ 👆 💚 🩺 🎯 🎦 ⚫️ 😢.
-
-⤴️ 🚶♀️ 🔢 `deprecated=True` `Query`:
-
-{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
-
-🩺 🔜 🎦 ⚫️ 💖 👉:
-
-
-
-## 🚫 ⚪️➡️ 🗄
-
-🚫 🔢 🔢 ⚪️➡️ 🏗 🗄 🔗 (& ➡️, ⚪️➡️ 🏧 🧾 ⚙️), ⚒ 🔢 `include_in_schema` `Query` `False`:
-
-{* ../../docs_src/query_params_str_validations/tutorial014.py hl[10] *}
-
-## 🌃
-
-👆 💪 📣 🌖 🔬 & 🗃 👆 🔢.
-
-💊 🔬 & 🗃:
-
-* `alias`
-* `title`
-* `description`
-* `deprecated`
-
-🔬 🎯 🎻:
-
-* `min_length`
-* `max_length`
-* `regex`
-
-👫 🖼 👆 👀 ❔ 📣 🔬 `str` 💲.
-
-👀 ⏭ 📃 👀 ❔ 📣 🔬 🎏 🆎, 💖 🔢.
diff --git a/docs/em/docs/tutorial/query-params.md b/docs/em/docs/tutorial/query-params.md
deleted file mode 100644
index 5c8d868a9..000000000
--- a/docs/em/docs/tutorial/query-params.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# 🔢 🔢
-
-🕐❔ 👆 📣 🎏 🔢 🔢 👈 🚫 🍕 ➡ 🔢, 👫 🔁 🔬 "🔢" 🔢.
-
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
-
-🔢 ⚒ 🔑-💲 👫 👈 🚶 ⏮️ `?` 📛, 🎏 `&` 🦹.
-
-🖼, 📛:
-
-```
-http://127.0.0.1:8000/items/?skip=0&limit=10
-```
-
-...🔢 🔢:
-
-* `skip`: ⏮️ 💲 `0`
-* `limit`: ⏮️ 💲 `10`
-
-👫 🍕 📛, 👫 "🛎" 🎻.
-
-✋️ 🕐❔ 👆 📣 👫 ⏮️ 🐍 🆎 (🖼 🔛, `int`), 👫 🗜 👈 🆎 & ✔ 🛡 ⚫️.
-
-🌐 🎏 🛠️ 👈 ⚖ ➡ 🔢 ✔ 🔢 🔢:
-
-* 👨🎨 🐕🦺 (🎲)
-* 💽 "✍"
-* 💽 🔬
-* 🏧 🧾
-
-## 🔢
-
-🔢 🔢 🚫 🔧 🍕 ➡, 👫 💪 📦 & 💪 ✔️ 🔢 💲.
-
-🖼 🔛 👫 ✔️ 🔢 💲 `skip=0` & `limit=10`.
-
-, 🔜 📛:
-
-```
-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`: ↩️ 👆 ⚒ ⚫️ 📛
-* `limit=10`: ↩️ 👈 🔢 💲
-
-## 📦 🔢
-
-🎏 🌌, 👆 💪 📣 📦 🔢 🔢, ⚒ 👫 🔢 `None`:
-
-{* ../../docs_src/query_params/tutorial002.py hl[9] *}
-
-👉 💼, 🔢 🔢 `q` 🔜 📦, & 🔜 `None` 🔢.
-
-/// check
-
-👀 👈 **FastAPI** 🙃 🥃 👀 👈 ➡ 🔢 `item_id` ➡ 🔢 & `q` 🚫,, ⚫️ 🔢 🔢.
-
-///
-
-## 🔢 🔢 🆎 🛠️
-
-👆 💪 📣 `bool` 🆎, & 👫 🔜 🗜:
-
-{* ../../docs_src/query_params/tutorial003.py hl[9] *}
-
-👉 💼, 🚥 👆 🚶:
-
-```
-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` ⏮️ `bool` 💲 `True`. ⏪ `False`.
-
-
-## 💗 ➡ & 🔢 🔢
-
-👆 💪 📣 💗 ➡ 🔢 & 🔢 🔢 🎏 🕰, **FastAPI** 💭 ❔ ❔.
-
-& 👆 🚫 ✔️ 📣 👫 🙆 🎯 ✔.
-
-👫 🔜 🔬 📛:
-
-{* ../../docs_src/query_params/tutorial004.py hl[8,10] *}
-
-## ✔ 🔢 🔢
-
-🕐❔ 👆 📣 🔢 💲 🚫-➡ 🔢 (🔜, 👥 ✔️ 🕴 👀 🔢 🔢), ⤴️ ⚫️ 🚫 ✔.
-
-🚥 👆 🚫 💚 🚮 🎯 💲 ✋️ ⚒ ⚫️ 📦, ⚒ 🔢 `None`.
-
-✋️ 🕐❔ 👆 💚 ⚒ 🔢 🔢 ✔, 👆 💪 🚫 📣 🙆 🔢 💲:
-
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
-
-📥 🔢 🔢 `needy` ✔ 🔢 🔢 🆎 `str`.
-
-🚥 👆 📂 👆 🖥 📛 💖:
-
-```
-http://127.0.0.1:8000/items/foo-item
-```
-
-...🍵 ❎ ✔ 🔢 `needy`, 👆 🔜 👀 ❌ 💖:
-
-```JSON
-{
- "detail": [
- {
- "loc": [
- "query",
- "needy"
- ],
- "msg": "field required",
- "type": "value_error.missing"
- }
- ]
-}
-```
-
-`needy` 🚚 🔢, 👆 🔜 💪 ⚒ ⚫️ 📛:
-
-```
-http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
-```
-
-...👉 🔜 👷:
-
-```JSON
-{
- "item_id": "foo-item",
- "needy": "sooooneedy"
-}
-```
-
-& ↗️, 👆 💪 🔬 🔢 ✔, ✔️ 🔢 💲, & 🍕 📦:
-
-{* ../../docs_src/query_params/tutorial006.py hl[10] *}
-
-👉 💼, 📤 3️⃣ 🔢 🔢:
-
-* `needy`, ✔ `str`.
-* `skip`, `int` ⏮️ 🔢 💲 `0`.
-* `limit`, 📦 `int`.
-
-/// 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
deleted file mode 100644
index c3bdeafd4..000000000
--- a/docs/em/docs/tutorial/request-files.md
+++ /dev/null
@@ -1,172 +0,0 @@
-# 📨 📁
-
-👆 💪 🔬 📁 📂 👩💻 ⚙️ `File`.
-
-/// info
-
-📨 📂 📁, 🥇 ❎ `python-multipart`.
-
-🤶 Ⓜ. `pip install python-multipart`.
-
-👉 ↩️ 📂 📁 📨 "📨 💽".
-
-///
-
-## 🗄 `File`
-
-🗄 `File` & `UploadFile` ⚪️➡️ `fastapi`:
-
-{* ../../docs_src/request_files/tutorial001.py hl[1] *}
-
-## 🔬 `File` 🔢
-
-✍ 📁 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Form`:
-
-{* ../../docs_src/request_files/tutorial001.py hl[7] *}
-
-/// info
-
-`File` 🎓 👈 😖 🔗 ⚪️➡️ `Form`.
-
-✋️ 💭 👈 🕐❔ 👆 🗄 `Query`, `Path`, `File` & 🎏 ⚪️➡️ `fastapi`, 👈 🤙 🔢 👈 📨 🎁 🎓.
-
-///
-
-/// tip
-
-📣 📁 💪, 👆 💪 ⚙️ `File`, ↩️ ⏪ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
-
-///
-
-📁 🔜 📂 "📨 💽".
-
-🚥 👆 📣 🆎 👆 *➡ 🛠️ 🔢* 🔢 `bytes`, **FastAPI** 🔜 ✍ 📁 👆 & 👆 🔜 📨 🎚 `bytes`.
-
-✔️ 🤯 👈 👉 ⛓ 👈 🎂 🎚 🔜 🏪 💾. 👉 🔜 👷 👍 🤪 📁.
-
-✋️ 📤 📚 💼 ❔ 👆 💪 💰 ⚪️➡️ ⚙️ `UploadFile`.
-
-## 📁 🔢 ⏮️ `UploadFile`
-
-🔬 📁 🔢 ⏮️ 🆎 `UploadFile`:
-
-{* ../../docs_src/request_files/tutorial001.py hl[12] *}
-
-⚙️ `UploadFile` ✔️ 📚 📈 🤭 `bytes`:
-
-* 👆 🚫 ✔️ ⚙️ `File()` 🔢 💲 🔢.
-* ⚫️ ⚙️ "🧵" 📁:
- * 📁 🏪 💾 🆙 🔆 📐 📉, & ⏮️ 🚶♀️ 👉 📉 ⚫️ 🔜 🏪 💾.
-* 👉 ⛓ 👈 ⚫️ 🔜 👷 👍 ⭕ 📁 💖 🖼, 📹, ⭕ 💱, ♒️. 🍵 😩 🌐 💾.
-* 👆 💪 🤚 🗃 ⚪️➡️ 📂 📁.
-* ⚫️ ✔️ 📁-💖 `async` 🔢.
-* ⚫️ 🎦 ☑ 🐍 `SpooledTemporaryFile` 🎚 👈 👆 💪 🚶♀️ 🔗 🎏 🗃 👈 ⌛ 📁-💖 🎚.
-
-### `UploadFile`
-
-`UploadFile` ✔️ 📄 🔢:
-
-* `filename`: `str` ⏮️ ⏮️ 📁 📛 👈 📂 (✅ `myimage.jpg`).
-* `content_type`: `str` ⏮️ 🎚 🆎 (📁 🆎 / 📻 🆎) (✅ `image/jpeg`).
-* `file`: `SpooledTemporaryFile` ( 📁-💖 🎚). 👉 ☑ 🐍 📁 👈 👆 💪 🚶♀️ 🔗 🎏 🔢 ⚖️ 🗃 👈 ⌛ "📁-💖" 🎚.
-
-`UploadFile` ✔️ 📄 `async` 👩🔬. 👫 🌐 🤙 🔗 📁 👩🔬 🔘 (⚙️ 🔗 `SpooledTemporaryFile`).
-
-* `write(data)`: ✍ `data` (`str` ⚖️ `bytes`) 📁.
-* `read(size)`: ✍ `size` (`int`) 🔢/🦹 📁.
-* `seek(offset)`: 🚶 🔢 🧘 `offset` (`int`) 📁.
- * 🤶 Ⓜ., `await myfile.seek(0)` 🔜 🚶 ▶️ 📁.
- * 👉 ✴️ ⚠ 🚥 👆 🏃 `await myfile.read()` 🕐 & ⤴️ 💪 ✍ 🎚 🔄.
-* `close()`: 🔐 📁.
-
-🌐 👫 👩🔬 `async` 👩🔬, 👆 💪 "⌛" 👫.
-
-🖼, 🔘 `async` *➡ 🛠️ 🔢* 👆 💪 🤚 🎚 ⏮️:
-
-```Python
-contents = await myfile.read()
-```
-
-🚥 👆 🔘 😐 `def` *➡ 🛠️ 🔢*, 👆 💪 🔐 `UploadFile.file` 🔗, 🖼:
-
-```Python
-contents = myfile.file.read()
-```
-
-/// note | `async` 📡 ℹ
-
-🕐❔ 👆 ⚙️ `async` 👩🔬, **FastAPI** 🏃 📁 👩🔬 🧵 & ⌛ 👫.
-
-///
-
-/// note | 💃 📡 ℹ
-
-**FastAPI**'Ⓜ `UploadFile` 😖 🔗 ⚪️➡️ **💃**'Ⓜ `UploadFile`, ✋️ 🚮 💪 🍕 ⚒ ⚫️ 🔗 ⏮️ **Pydantic** & 🎏 🍕 FastAPI.
-
-///
-
-## ⚫️❔ "📨 💽"
-
-🌌 🕸 📨 (``) 📨 💽 💽 🛎 ⚙️ "🎁" 🔢 👈 📊, ⚫️ 🎏 ⚪️➡️ 🎻.
-
-**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-
-/// note | 📡 ℹ
-
-📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded` 🕐❔ ⚫️ 🚫 🔌 📁.
-
-✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 🚥 👆 ⚙️ `File`, **FastAPI** 🔜 💭 ⚫️ ✔️ 🤚 📁 ⚪️➡️ ☑ 🍕 💪.
-
-🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
-
-///
-
-/// warning
-
-👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
-
-👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
-
-///
-
-## 📦 📁 📂
-
-👆 💪 ⚒ 📁 📦 ⚙️ 🐩 🆎 ✍ & ⚒ 🔢 💲 `None`:
-
-{* ../../docs_src/request_files/tutorial001_02.py hl[9,17] *}
-
-## `UploadFile` ⏮️ 🌖 🗃
-
-👆 💪 ⚙️ `File()` ⏮️ `UploadFile`, 🖼, ⚒ 🌖 🗃:
-
-{* ../../docs_src/request_files/tutorial001_03.py hl[13] *}
-
-## 💗 📁 📂
-
-⚫️ 💪 📂 📚 📁 🎏 🕰.
-
-👫 🔜 👨💼 🎏 "📨 🏑" 📨 ⚙️ "📨 💽".
-
-⚙️ 👈, 📣 📇 `bytes` ⚖️ `UploadFile`:
-
-{* ../../docs_src/request_files/tutorial002.py hl[10,15] *}
-
-👆 🔜 📨, 📣, `list` `bytes` ⚖️ `UploadFile`Ⓜ.
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.responses import HTMLResponse`.
-
-**FastAPI** 🚚 🎏 `starlette.responses` `fastapi.responses` 🏪 👆, 👩💻. ✋️ 🌅 💪 📨 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-### 💗 📁 📂 ⏮️ 🌖 🗃
-
-& 🎏 🌌 ⏭, 👆 💪 ⚙️ `File()` ⚒ 🌖 🔢, `UploadFile`:
-
-{* ../../docs_src/request_files/tutorial003.py hl[18] *}
-
-## 🌃
-
-⚙️ `File`, `bytes`, & `UploadFile` 📣 📁 📂 📨, 📨 📨 💽.
diff --git a/docs/em/docs/tutorial/request-forms-and-files.md b/docs/em/docs/tutorial/request-forms-and-files.md
deleted file mode 100644
index 680b1a96a..000000000
--- a/docs/em/docs/tutorial/request-forms-and-files.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# 📨 📨 & 📁
-
-👆 💪 🔬 📁 & 📨 🏑 🎏 🕰 ⚙️ `File` & `Form`.
-
-/// info
-
-📨 📂 📁 & /⚖️ 📨 📊, 🥇 ❎ `python-multipart`.
-
-🤶 Ⓜ. `pip install python-multipart`.
-
-///
-
-## 🗄 `File` & `Form`
-
-{* ../../docs_src/request_forms_and_files/tutorial001.py hl[1] *}
-
-## 🔬 `File` & `Form` 🔢
-
-✍ 📁 & 📨 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Query`:
-
-{* ../../docs_src/request_forms_and_files/tutorial001.py hl[8] *}
-
-📁 & 📨 🏑 🔜 📂 📨 📊 & 👆 🔜 📨 📁 & 📨 🏑.
-
-& 👆 💪 📣 📁 `bytes` & `UploadFile`.
-
-/// warning
-
-👆 💪 📣 💗 `File` & `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `multipart/form-data` ↩️ `application/json`.
-
-👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
-
-///
-
-## 🌃
-
-⚙️ `File` & `Form` 👯♂️ 🕐❔ 👆 💪 📨 💽 & 📁 🎏 📨.
diff --git a/docs/em/docs/tutorial/request-forms.md b/docs/em/docs/tutorial/request-forms.md
deleted file mode 100644
index 1cc1ea5dc..000000000
--- a/docs/em/docs/tutorial/request-forms.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# 📨 💽
-
-🕐❔ 👆 💪 📨 📨 🏑 ↩️ 🎻, 👆 💪 ⚙️ `Form`.
-
-/// info
-
-⚙️ 📨, 🥇 ❎ `python-multipart`.
-
-🤶 Ⓜ. `pip install python-multipart`.
-
-///
-
-## 🗄 `Form`
-
-🗄 `Form` ⚪️➡️ `fastapi`:
-
-{* ../../docs_src/request_forms/tutorial001.py hl[1] *}
-
-## 🔬 `Form` 🔢
-
-✍ 📨 🔢 🎏 🌌 👆 🔜 `Body` ⚖️ `Query`:
-
-{* ../../docs_src/request_forms/tutorial001.py hl[7] *}
-
-🖼, 1️⃣ 🌌 Oauth2️⃣ 🔧 💪 ⚙️ (🤙 "🔐 💧") ⚫️ ✔ 📨 `username` & `password` 📨 🏑.
-
-🔌 🚚 🏑 ⚫️❔ 📛 `username` & `password`, & 📨 📨 🏑, 🚫 🎻.
-
-⏮️ `Form` 👆 💪 📣 🎏 📳 ⏮️ `Body` (& `Query`, `Path`, `Cookie`), 🔌 🔬, 🖼, 📛 (✅ `user-name` ↩️ `username`), ♒️.
-
-/// info
-
-`Form` 🎓 👈 😖 🔗 ⚪️➡️ `Body`.
-
-///
-
-/// tip
-
-📣 📨 💪, 👆 💪 ⚙️ `Form` 🎯, ↩️ 🍵 ⚫️ 🔢 🔜 🔬 🔢 🔢 ⚖️ 💪 (🎻) 🔢.
-
-///
-
-## 🔃 "📨 🏑"
-
-🌌 🕸 📨 (``) 📨 💽 💽 🛎 ⚙️ "🎁" 🔢 👈 📊, ⚫️ 🎏 ⚪️➡️ 🎻.
-
-**FastAPI** 🔜 ⚒ 💭 ✍ 👈 📊 ⚪️➡️ ▶️️ 🥉 ↩️ 🎻.
-
-/// note | 📡 ℹ
-
-📊 ⚪️➡️ 📨 🛎 🗜 ⚙️ "📻 🆎" `application/x-www-form-urlencoded`.
-
-✋️ 🕐❔ 📨 🔌 📁, ⚫️ 🗜 `multipart/form-data`. 👆 🔜 ✍ 🔃 🚚 📁 ⏭ 📃.
-
-🚥 👆 💚 ✍ 🌖 🔃 👉 🔢 & 📨 🏑, 👳 🏇 🕸 🩺 POST.
-
-///
-
-/// warning
-
-👆 💪 📣 💗 `Form` 🔢 *➡ 🛠️*, ✋️ 👆 💪 🚫 📣 `Body` 🏑 👈 👆 ⌛ 📨 🎻, 📨 🔜 ✔️ 💪 🗜 ⚙️ `application/x-www-form-urlencoded` ↩️ `application/json`.
-
-👉 🚫 🚫 **FastAPI**, ⚫️ 🍕 🇺🇸🔍 🛠️.
-
-///
-
-## 🌃
-
-⚙️ `Form` 📣 📨 💽 🔢 🔢.
diff --git a/docs/em/docs/tutorial/response-model.md b/docs/em/docs/tutorial/response-model.md
deleted file mode 100644
index 477376458..000000000
--- a/docs/em/docs/tutorial/response-model.md
+++ /dev/null
@@ -1,340 +0,0 @@
-# 📨 🏷 - 📨 🆎
-
-👆 💪 📣 🆎 ⚙️ 📨 ✍ *➡ 🛠️ 🔢* **📨 🆎**.
-
-👆 💪 ⚙️ **🆎 ✍** 🎏 🌌 👆 🔜 🔢 💽 🔢 **🔢**, 👆 💪 ⚙️ Pydantic 🏷, 📇, 📖, 📊 💲 💖 🔢, 🎻, ♒️.
-
-{* ../../docs_src/response_model/tutorial001_01.py hl[18,23] *}
-
-FastAPI 🔜 ⚙️ 👉 📨 🆎:
-
-* **✔** 📨 💽.
- * 🚥 💽 ❌ (✅ 👆 ❌ 🏑), ⚫️ ⛓ 👈 *👆* 📱 📟 💔, 🚫 🛬 ⚫️❔ ⚫️ 🔜, & ⚫️ 🔜 📨 💽 ❌ ↩️ 🛬 ❌ 💽. 👉 🌌 👆 & 👆 👩💻 💪 🎯 👈 👫 🔜 📨 💽 & 💽 💠 📈.
-* 🚮 **🎻 🔗** 📨, 🗄 *➡ 🛠️*.
- * 👉 🔜 ⚙️ **🏧 🩺**.
- * ⚫️ 🔜 ⚙️ 🏧 👩💻 📟 ⚡ 🧰.
-
-✋️ 🏆 🥈:
-
-* ⚫️ 🔜 **📉 & ⛽** 🔢 📊 ⚫️❔ 🔬 📨 🆎.
- * 👉 ✴️ ⚠ **💂♂**, 👥 🔜 👀 🌅 👈 🔛.
-
-## `response_model` 🔢
-
-📤 💼 🌐❔ 👆 💪 ⚖️ 💚 📨 💽 👈 🚫 ⚫️❔ ⚫️❔ 🆎 📣.
-
-🖼, 👆 💪 💚 **📨 📖** ⚖️ 💽 🎚, ✋️ **📣 ⚫️ Pydantic 🏷**. 👉 🌌 Pydantic 🏷 🔜 🌐 💽 🧾, 🔬, ♒️. 🎚 👈 👆 📨 (✅ 📖 ⚖️ 💽 🎚).
-
-🚥 👆 🚮 📨 🆎 ✍, 🧰 & 👨🎨 🔜 😭 ⏮️ (☑) ❌ 💬 👆 👈 👆 🔢 🛬 🆎 (✅#️⃣) 👈 🎏 ⚪️➡️ ⚫️❔ 👆 📣 (✅ Pydantic 🏷).
-
-📚 💼, 👆 💪 ⚙️ *➡ 🛠️ 👨🎨* 🔢 `response_model` ↩️ 📨 🆎.
-
-👆 💪 ⚙️ `response_model` 🔢 🙆 *➡ 🛠️*:
-
-* `@app.get()`
-* `@app.post()`
-* `@app.put()`
-* `@app.delete()`
-* ♒️.
-
-{* ../../docs_src/response_model/tutorial001.py hl[17,22,24:27] *}
-
-/// note
-
-👀 👈 `response_model` 🔢 "👨🎨" 👩🔬 (`get`, `post`, ♒️). 🚫 👆 *➡ 🛠️ 🔢*, 💖 🌐 🔢 & 💪.
-
-///
-
-`response_model` 📨 🎏 🆎 👆 🔜 📣 Pydantic 🏷 🏑,, ⚫️ 💪 Pydantic 🏷, ✋️ ⚫️ 💪, ✅ `list` Pydantic 🏷, 💖 `List[Item]`.
-
-FastAPI 🔜 ⚙️ 👉 `response_model` 🌐 💽 🧾, 🔬, ♒️. & **🗜 & ⛽ 🔢 📊** 🚮 🆎 📄.
-
-/// tip
-
-🚥 👆 ✔️ ⚠ 🆎 ✅ 👆 👨🎨, ✍, ♒️, 👆 💪 📣 🔢 📨 🆎 `Any`.
-
-👈 🌌 👆 💬 👨🎨 👈 👆 😫 🛬 🕳. ✋️ FastAPI 🔜 💽 🧾, 🔬, 🖥, ♒️. ⏮️ `response_model`.
-
-///
-
-### `response_model` 📫
-
-🚥 👆 📣 👯♂️ 📨 🆎 & `response_model`, `response_model` 🔜 ✊ 📫 & ⚙️ FastAPI.
-
-👉 🌌 👆 💪 🚮 ☑ 🆎 ✍ 👆 🔢 🕐❔ 👆 🛬 🆎 🎏 🌘 📨 🏷, ⚙️ 👨🎨 & 🧰 💖 ✍. & 👆 💪 ✔️ FastAPI 💽 🔬, 🧾, ♒️. ⚙️ `response_model`.
-
-👆 💪 ⚙️ `response_model=None` ❎ 🏗 📨 🏷 👈 *➡ 🛠️*, 👆 5️⃣📆 💪 ⚫️ 🚥 👆 ❎ 🆎 ✍ 👜 👈 🚫 ☑ Pydantic 🏑, 👆 🔜 👀 🖼 👈 1️⃣ 📄 🔛.
-
-## 📨 🎏 🔢 💽
-
-📥 👥 📣 `UserIn` 🏷, ⚫️ 🔜 🔌 🔢 🔐:
-
-{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
-
-/// info
-
-⚙️ `EmailStr`, 🥇 ❎ `email-validator`.
-
-🤶 Ⓜ. `pip install email-validator`
-⚖️ `pip install pydantic[email]`.
-
-///
-
-& 👥 ⚙️ 👉 🏷 📣 👆 🔢 & 🎏 🏷 📣 👆 🔢:
-
-{* ../../docs_src/response_model/tutorial002.py hl[18] *}
-
-🔜, 🕐❔ 🖥 🏗 👩💻 ⏮️ 🔐, 🛠️ 🔜 📨 🎏 🔐 📨.
-
-👉 💼, ⚫️ 💪 🚫 ⚠, ↩️ ⚫️ 🎏 👩💻 📨 🔐.
-
-✋️ 🚥 👥 ⚙️ 🎏 🏷 ➕1️⃣ *➡ 🛠️*, 👥 💪 📨 👆 👩💻 🔐 🔠 👩💻.
-
-/// danger
-
-🙅 🏪 ✅ 🔐 👩💻 ⚖️ 📨 ⚫️ 📨 💖 👉, 🚥 👆 💭 🌐 ⚠ & 👆 💭 ⚫️❔ 👆 🔨.
-
-///
-
-## 🚮 🔢 🏷
-
-👥 💪 ↩️ ✍ 🔢 🏷 ⏮️ 🔢 🔐 & 🔢 🏷 🍵 ⚫️:
-
-{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *}
-
-📥, ✋️ 👆 *➡ 🛠️ 🔢* 🛬 🎏 🔢 👩💻 👈 🔌 🔐:
-
-{* ../../docs_src/response_model/tutorial003.py hl[24] *}
-
-...👥 📣 `response_model` 👆 🏷 `UserOut`, 👈 🚫 🔌 🔐:
-
-{* ../../docs_src/response_model/tutorial003.py hl[22] *}
-
-, **FastAPI** 🔜 ✊ 💅 🖥 👅 🌐 💽 👈 🚫 📣 🔢 🏷 (⚙️ Pydantic).
-
-### `response_model` ⚖️ 📨 🆎
-
-👉 💼, ↩️ 2️⃣ 🏷 🎏, 🚥 👥 ✍ 🔢 📨 🆎 `UserOut`, 👨🎨 & 🧰 🔜 😭 👈 👥 🛬 ❌ 🆎, 📚 🎏 🎓.
-
-👈 ⚫️❔ 👉 🖼 👥 ✔️ 📣 ⚫️ `response_model` 🔢.
-
-...✋️ 😣 👂 🔛 👀 ❔ ❎ 👈.
-
-## 📨 🆎 & 💽 🖥
-
-➡️ 😣 ⚪️➡️ ⏮️ 🖼. 👥 💚 **✍ 🔢 ⏮️ 1️⃣ 🆎** ✋️ 📨 🕳 👈 🔌 **🌅 💽**.
-
-👥 💚 FastAPI 🚧 **🖥** 📊 ⚙️ 📨 🏷.
-
-⏮️ 🖼, ↩️ 🎓 🎏, 👥 ✔️ ⚙️ `response_model` 🔢. ✋️ 👈 ⛓ 👈 👥 🚫 🤚 🐕🦺 ⚪️➡️ 👨🎨 & 🧰 ✅ 🔢 📨 🆎.
-
-✋️ 🌅 💼 🌐❔ 👥 💪 🕳 💖 👉, 👥 💚 🏷 **⛽/❎** 📊 👉 🖼.
-
-& 👈 💼, 👥 💪 ⚙️ 🎓 & 🧬 ✊ 📈 🔢 **🆎 ✍** 🤚 👍 🐕🦺 👨🎨 & 🧰, & 🤚 FastAPI **💽 🖥**.
-
-{* ../../docs_src/response_model/tutorial003_01.py hl[9:13,15:16,20] *}
-
-⏮️ 👉, 👥 🤚 🏭 🐕🦺, ⚪️➡️ 👨🎨 & ✍ 👉 📟 ☑ ⚖ 🆎, ✋️ 👥 🤚 💽 🖥 ⚪️➡️ FastAPI.
-
-❔ 🔨 👉 👷 ❓ ➡️ ✅ 👈 👅. 👶
-
-### 🆎 ✍ & 🏭
-
-🥇 ➡️ 👀 ❔ 👨🎨, ✍ & 🎏 🧰 🔜 👀 👉.
-
-`BaseUser` ✔️ 🧢 🏑. ⤴️ `UserIn` 😖 ⚪️➡️ `BaseUser` & 🚮 `password` 🏑,, ⚫️ 🔜 🔌 🌐 🏑 ⚪️➡️ 👯♂️ 🏷.
-
-👥 ✍ 🔢 📨 🆎 `BaseUser`, ✋️ 👥 🤙 🛬 `UserIn` 👐.
-
-👨🎨, ✍, & 🎏 🧰 🏆 🚫 😭 🔃 👉 ↩️, ⌨ ⚖, `UserIn` 🏿 `BaseUser`, ❔ ⛓ ⚫️ *☑* 🆎 🕐❔ ⚫️❔ ⌛ 🕳 👈 `BaseUser`.
-
-### FastAPI 💽 🖥
-
-🔜, FastAPI, ⚫️ 🔜 👀 📨 🆎 & ⚒ 💭 👈 ⚫️❔ 👆 📨 🔌 **🕴** 🏑 👈 📣 🆎.
-
-FastAPI 🔨 📚 👜 🔘 ⏮️ Pydantic ⚒ 💭 👈 📚 🎏 🚫 🎓 🧬 🚫 ⚙️ 📨 💽 🖥, ⏪ 👆 💪 🔚 🆙 🛬 🌅 🌅 💽 🌘 ⚫️❔ 👆 📈.
-
-👉 🌌, 👆 💪 🤚 🏆 👯♂️ 🌏: 🆎 ✍ ⏮️ **🏭 🐕🦺** & **💽 🖥**.
-
-## 👀 ⚫️ 🩺
-
-🕐❔ 👆 👀 🏧 🩺, 👆 💪 ✅ 👈 🔢 🏷 & 🔢 🏷 🔜 👯♂️ ✔️ 👫 👍 🎻 🔗:
-
-
-
-& 👯♂️ 🏷 🔜 ⚙️ 🎓 🛠️ 🧾:
-
-
-
-## 🎏 📨 🆎 ✍
-
-📤 5️⃣📆 💼 🌐❔ 👆 📨 🕳 👈 🚫 ☑ Pydantic 🏑 & 👆 ✍ ⚫️ 🔢, 🕴 🤚 🐕🦺 🚚 🏭 (👨🎨, ✍, ♒️).
-
-### 📨 📨 🔗
-
-🏆 ⚠ 💼 🔜 [🛬 📨 🔗 🔬 ⏪ 🏧 🩺](../advanced/response-directly.md){.internal-link target=_blank}.
-
-{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
-
-👉 🙅 💼 🍵 🔁 FastAPI ↩️ 📨 🆎 ✍ 🎓 (⚖️ 🏿) `Response`.
-
-& 🧰 🔜 😄 ↩️ 👯♂️ `RedirectResponse` & `JSONResponse` 🏿 `Response`, 🆎 ✍ ☑.
-
-### ✍ 📨 🏿
-
-👆 💪 ⚙️ 🏿 `Response` 🆎 ✍:
-
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
-
-👉 🔜 👷 ↩️ `RedirectResponse` 🏿 `Response`, & FastAPI 🔜 🔁 🍵 👉 🙅 💼.
-
-### ❌ 📨 🆎 ✍
-
-✋️ 🕐❔ 👆 📨 🎏 ❌ 🎚 👈 🚫 ☑ Pydantic 🆎 (✅ 💽 🎚) & 👆 ✍ ⚫️ 💖 👈 🔢, FastAPI 🔜 🔄 ✍ Pydantic 📨 🏷 ⚪️➡️ 👈 🆎 ✍, & 🔜 ❌.
-
-🎏 🔜 🔨 🚥 👆 ✔️ 🕳 💖 🇪🇺 🖖 🎏 🆎 🌐❔ 1️⃣ ⚖️ 🌅 👫 🚫 ☑ Pydantic 🆎, 🖼 👉 🔜 ❌ 👶:
-
-{* ../../docs_src/response_model/tutorial003_04.py hl[10] *}
-
-...👉 ❌ ↩️ 🆎 ✍ 🚫 Pydantic 🆎 & 🚫 👁 `Response` 🎓 ⚖️ 🏿, ⚫️ 🇪🇺 (🙆 2️⃣) 🖖 `Response` & `dict`.
-
-### ❎ 📨 🏷
-
-▶️ ⚪️➡️ 🖼 🔛, 👆 5️⃣📆 🚫 💚 ✔️ 🔢 💽 🔬, 🧾, 🖥, ♒️. 👈 🎭 FastAPI.
-
-✋️ 👆 💪 💚 🚧 📨 🆎 ✍ 🔢 🤚 🐕🦺 ⚪️➡️ 🧰 💖 👨🎨 & 🆎 ☑ (✅ ✍).
-
-👉 💼, 👆 💪 ❎ 📨 🏷 ⚡ ⚒ `response_model=None`:
-
-{* ../../docs_src/response_model/tutorial003_05.py hl[9] *}
-
-👉 🔜 ⚒ FastAPI 🚶 📨 🏷 ⚡ & 👈 🌌 👆 💪 ✔️ 🙆 📨 🆎 ✍ 👆 💪 🍵 ⚫️ 🤕 👆 FastAPI 🈸. 👶
-
-## 📨 🏷 🔢 🔢
-
-👆 📨 🏷 💪 ✔️ 🔢 💲, 💖:
-
-{* ../../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`.
-* `tags: List[str] = []` 🔢 🛁 📇: `[]`.
-
-✋️ 👆 💪 💚 🚫 👫 ⚪️➡️ 🏁 🚥 👫 🚫 🤙 🏪.
-
-🖼, 🚥 👆 ✔️ 🏷 ⏮️ 📚 📦 🔢 ☁ 💽, ✋️ 👆 🚫 💚 📨 📶 📏 🎻 📨 🌕 🔢 💲.
-
-### ⚙️ `response_model_exclude_unset` 🔢
-
-👆 💪 ⚒ *➡ 🛠️ 👨🎨* 🔢 `response_model_exclude_unset=True`:
-
-{* ../../docs_src/response_model/tutorial004.py hl[24] *}
-
-& 👈 🔢 💲 🏆 🚫 🔌 📨, 🕴 💲 🤙 ⚒.
-
-, 🚥 👆 📨 📨 👈 *➡ 🛠️* 🏬 ⏮️ 🆔 `foo`, 📨 (🚫 ✅ 🔢 💲) 🔜:
-
-```JSON
-{
- "name": "Foo",
- "price": 50.2
-}
-```
-
-/// info
-
-FastAPI ⚙️ Pydantic 🏷 `.dict()` ⏮️ 🚮 `exclude_unset` 🔢 🏆 👉.
-
-///
-
-/// info
-
-👆 💪 ⚙️:
-
-* `response_model_exclude_defaults=True`
-* `response_model_exclude_none=True`
-
-🔬 Pydantic 🩺 `exclude_defaults` & `exclude_none`.
-
-///
-
-#### 📊 ⏮️ 💲 🏑 ⏮️ 🔢
-
-✋️ 🚥 👆 📊 ✔️ 💲 🏷 🏑 ⏮️ 🔢 💲, 💖 🏬 ⏮️ 🆔 `bar`:
-
-```Python hl_lines="3 5"
-{
- "name": "Bar",
- "description": "The bartenders",
- "price": 62,
- "tax": 20.2
-}
-```
-
-👫 🔜 🔌 📨.
-
-#### 📊 ⏮️ 🎏 💲 🔢
-
-🚥 📊 ✔️ 🎏 💲 🔢 🕐, 💖 🏬 ⏮️ 🆔 `baz`:
-
-```Python hl_lines="3 5-6"
-{
- "name": "Baz",
- "description": None,
- "price": 50.2,
- "tax": 10.5,
- "tags": []
-}
-```
-
-FastAPI 🙃 🥃 (🤙, Pydantic 🙃 🥃) 🤔 👈, ✋️ `description`, `tax`, & `tags` ✔️ 🎏 💲 🔢, 👫 ⚒ 🎯 (↩️ ✊ ⚪️➡️ 🔢).
-
-, 👫 🔜 🔌 🎻 📨.
-
-/// tip
-
-👀 👈 🔢 💲 💪 🕳, 🚫 🕴 `None`.
-
-👫 💪 📇 (`[]`), `float` `10.5`, ♒️.
-
-///
-
-### `response_model_include` & `response_model_exclude`
-
-👆 💪 ⚙️ *➡ 🛠️ 👨🎨* 🔢 `response_model_include` & `response_model_exclude`.
-
-👫 ✊ `set` `str` ⏮️ 📛 🔢 🔌 (❎ 🎂) ⚖️ 🚫 (✅ 🎂).
-
-👉 💪 ⚙️ ⏩ ⌨ 🚥 👆 ✔️ 🕴 1️⃣ Pydantic 🏷 & 💚 ❎ 💽 ⚪️➡️ 🔢.
-
-/// tip
-
-✋️ ⚫️ 👍 ⚙️ 💭 🔛, ⚙️ 💗 🎓, ↩️ 👫 🔢.
-
-👉 ↩️ 🎻 🔗 🏗 👆 📱 🗄 (& 🩺) 🔜 1️⃣ 🏁 🏷, 🚥 👆 ⚙️ `response_model_include` ⚖️ `response_model_exclude` 🚫 🔢.
-
-👉 ✔ `response_model_by_alias` 👈 👷 ➡.
-
-///
-
-{* ../../docs_src/response_model/tutorial005.py hl[31,37] *}
-
-/// tip
-
-❕ `{"name", "description"}` ✍ `set` ⏮️ 📚 2️⃣ 💲.
-
-⚫️ 🌓 `set(["name", "description"])`.
-
-///
-
-#### ⚙️ `list`Ⓜ ↩️ `set`Ⓜ
-
-🚥 👆 💭 ⚙️ `set` & ⚙️ `list` ⚖️ `tuple` ↩️, FastAPI 🔜 🗜 ⚫️ `set` & ⚫️ 🔜 👷 ☑:
-
-{* ../../docs_src/response_model/tutorial006.py hl[31,37] *}
-
-## 🌃
-
-⚙️ *➡ 🛠️ 👨🎨* 🔢 `response_model` 🔬 📨 🏷 & ✴️ 🚚 📢 💽 ⛽ 👅.
-
-⚙️ `response_model_exclude_unset` 📨 🕴 💲 🎯 ⚒.
diff --git a/docs/em/docs/tutorial/response-status-code.md b/docs/em/docs/tutorial/response-status-code.md
deleted file mode 100644
index 413ceb916..000000000
--- a/docs/em/docs/tutorial/response-status-code.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# 📨 👔 📟
-
-🎏 🌌 👆 💪 ✔ 📨 🏷, 👆 💪 📣 🇺🇸🔍 👔 📟 ⚙️ 📨 ⏮️ 🔢 `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` 🔢 📨 🔢 ⏮️ 🇺🇸🔍 👔 📟.
-
-/// info
-
-`status_code` 💪 👐 📨 `IntEnum`, ✅ 🐍 `http.HTTPStatus`.
-
-///
-
-⚫️ 🔜:
-
-* 📨 👈 👔 📟 📨.
-* 📄 ⚫️ ✅ 🗄 🔗 ( & , 👩💻 🔢):
-
-
-
-/// note
-
-📨 📟 (👀 ⏭ 📄) 🎦 👈 📨 🔨 🚫 ✔️ 💪.
-
-FastAPI 💭 👉, & 🔜 🏭 🗄 🩺 👈 🇵🇸 📤 🙅♂ 📨 💪.
-
-///
-
-## 🔃 🇺🇸🔍 👔 📟
-
-/// note
-
-🚥 👆 ⏪ 💭 ⚫️❔ 🇺🇸🔍 👔 📟, 🚶 ⏭ 📄.
-
-///
-
-🇺🇸🔍, 👆 📨 🔢 👔 📟 3️⃣ 9️⃣ 🍕 📨.
-
-👫 👔 📟 ✔️ 📛 🔗 🤔 👫, ✋️ ⚠ 🍕 🔢.
-
-📏:
-
-* `100` & 🔛 "ℹ". 👆 🛎 ⚙️ 👫 🔗. 📨 ⏮️ 👫 👔 📟 🚫🔜 ✔️ 💪.
-* **`200`** & 🔛 "🏆" 📨. 👫 🕐 👆 🔜 ⚙️ 🏆.
- * `200` 🔢 👔 📟, ❔ ⛓ 🌐 "👌".
- * ➕1️⃣ 🖼 🔜 `201`, "✍". ⚫️ 🛎 ⚙️ ⏮️ 🏗 🆕 ⏺ 💽.
- * 🎁 💼 `204`, "🙅♂ 🎚". 👉 📨 ⚙️ 🕐❔ 📤 🙅♂ 🎚 📨 👩💻, & 📨 🔜 🚫 ✔️ 💪.
-* **`300`** & 🔛 "❎". 📨 ⏮️ 👫 👔 📟 5️⃣📆 ⚖️ 5️⃣📆 🚫 ✔️ 💪, 🌖 `304`, "🚫 🔀", ❔ 🔜 🚫 ✔️ 1️⃣.
-* **`400`** & 🔛 "👩💻 ❌" 📨. 👫 🥈 🆎 👆 🔜 🎲 ⚙️ 🏆.
- * 🖼 `404`, "🚫 🔎" 📨.
- * 💊 ❌ ⚪️➡️ 👩💻, 👆 💪 ⚙️ `400`.
-* `500` & 🔛 💽 ❌. 👆 🌖 🙅 ⚙️ 👫 🔗. 🕐❔ 🕳 🚶 ❌ 🍕 👆 🈸 📟, ⚖️ 💽, ⚫️ 🔜 🔁 📨 1️⃣ 👫 👔 📟.
-
-/// tip
-
-💭 🌅 🔃 🔠 👔 📟 & ❔ 📟 ⚫️❔, ✅ 🏇 🧾 🔃 🇺🇸🔍 👔 📟.
-
-///
-
-## ⌨ 💭 📛
-
-➡️ 👀 ⏮️ 🖼 🔄:
-
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
-
-`201` 👔 📟 "✍".
-
-✋️ 👆 🚫 ✔️ ✍ ⚫️❔ 🔠 👉 📟 ⛓.
-
-👆 💪 ⚙️ 🏪 🔢 ⚪️➡️ `fastapi.status`.
-
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
-
-👫 🏪, 👫 🧑🤝🧑 🎏 🔢, ✋️ 👈 🌌 👆 💪 ⚙️ 👨🎨 📋 🔎 👫:
-
-
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette import status`.
-
-**FastAPI** 🚚 🎏 `starlette.status` `fastapi.status` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-## 🔀 🔢
-
-⏪, [🏧 👩💻 🦮](../advanced/response-change-status-code.md){.internal-link target=_blank}, 👆 🔜 👀 ❔ 📨 🎏 👔 📟 🌘 🔢 👆 📣 📥.
diff --git a/docs/em/docs/tutorial/schema-extra-example.md b/docs/em/docs/tutorial/schema-extra-example.md
deleted file mode 100644
index 1bd314c51..000000000
--- a/docs/em/docs/tutorial/schema-extra-example.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# 📣 📨 🖼 💽
-
-👆 💪 📣 🖼 💽 👆 📱 💪 📨.
-
-📥 📚 🌌 ⚫️.
-
-## Pydantic `schema_extra`
-
-👆 💪 📣 `example` Pydantic 🏷 ⚙️ `Config` & `schema_extra`, 🔬 Pydantic 🩺: 🔗 🛃:
-
-{* ../../docs_src/schema_extra_example/tutorial001.py hl[15:23] *}
-
-👈 ➕ ℹ 🔜 🚮-🔢 **🎻 🔗** 👈 🏷, & ⚫️ 🔜 ⚙️ 🛠️ 🩺.
-
-/// tip
-
-👆 💪 ⚙️ 🎏 ⚒ ↔ 🎻 🔗 & 🚮 👆 👍 🛃 ➕ ℹ.
-
-🖼 👆 💪 ⚙️ ⚫️ 🚮 🗃 🕸 👩💻 🔢, ♒️.
-
-///
-
-## `Field` 🌖 ❌
-
-🕐❔ ⚙️ `Field()` ⏮️ Pydantic 🏷, 👆 💪 📣 ➕ ℹ **🎻 🔗** 🚶♀️ 🙆 🎏 ❌ ❌ 🔢.
-
-👆 💪 ⚙️ 👉 🚮 `example` 🔠 🏑:
-
-{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10:13] *}
-
-/// warning
-
-🚧 🤯 👈 📚 ➕ ❌ 🚶♀️ 🏆 🚫 🚮 🙆 🔬, 🕴 ➕ ℹ, 🧾 🎯.
-
-///
-
-## `example` & `examples` 🗄
-
-🕐❔ ⚙️ 🙆:
-
-* `Path()`
-* `Query()`
-* `Header()`
-* `Cookie()`
-* `Body()`
-* `Form()`
-* `File()`
-
-👆 💪 📣 💽 `example` ⚖️ 👪 `examples` ⏮️ 🌖 ℹ 👈 🔜 🚮 **🗄**.
-
-### `Body` ⏮️ `example`
-
-📥 👥 🚶♀️ `example` 📊 ⌛ `Body()`:
-
-{* ../../docs_src/schema_extra_example/tutorial003.py hl[20:25] *}
-
-### 🖼 🩺 🎚
-
-⏮️ 🙆 👩🔬 🔛 ⚫️ 🔜 👀 💖 👉 `/docs`:
-
-
-
-### `Body` ⏮️ 💗 `examples`
-
-👐 👁 `example`, 👆 💪 🚶♀️ `examples` ⚙️ `dict` ⏮️ **💗 🖼**, 🔠 ⏮️ ➕ ℹ 👈 🔜 🚮 **🗄** 💁♂️.
-
-🔑 `dict` 🔬 🔠 🖼, & 🔠 💲 ➕1️⃣ `dict`.
-
-🔠 🎯 🖼 `dict` `examples` 💪 🔌:
-
-* `summary`: 📏 📛 🖼.
-* `description`: 📏 📛 👈 💪 🔌 ✍ ✍.
-* `value`: 👉 ☑ 🖼 🎦, ✅ `dict`.
-* `externalValue`: 🎛 `value`, 📛 ☝ 🖼. 👐 👉 5️⃣📆 🚫 🐕🦺 📚 🧰 `value`.
-
-{* ../../docs_src/schema_extra_example/tutorial004.py hl[21:47] *}
-
-### 🖼 🩺 🎚
-
-⏮️ `examples` 🚮 `Body()` `/docs` 🔜 👀 💖:
-
-
-
-## 📡 ℹ
-
-/// warning
-
-👉 📶 📡 ℹ 🔃 🐩 **🎻 🔗** & **🗄**.
-
-🚥 💭 🔛 ⏪ 👷 👆, 👈 💪 🥃, & 👆 🎲 🚫 💪 👉 ℹ, 💭 🆓 🚶 👫.
-
-///
-
-🕐❔ 👆 🚮 🖼 🔘 Pydantic 🏷, ⚙️ `schema_extra` ⚖️ `Field(example="something")` 👈 🖼 🚮 **🎻 🔗** 👈 Pydantic 🏷.
-
-& 👈 **🎻 🔗** Pydantic 🏷 🔌 **🗄** 👆 🛠️, & ⤴️ ⚫️ ⚙️ 🩺 🎚.
-
-**🎻 🔗** 🚫 🤙 ✔️ 🏑 `example` 🐩. ⏮️ ⏬ 🎻 🔗 🔬 🏑 `examples`, ✋️ 🗄 3️⃣.0️⃣.3️⃣ ⚓️ 🔛 🗝 ⏬ 🎻 🔗 👈 🚫 ✔️ `examples`.
-
-, 🗄 3️⃣.0️⃣.3️⃣ 🔬 🚮 👍 `example` 🔀 ⏬ **🎻 🔗** ⚫️ ⚙️, 🎏 🎯 (✋️ ⚫️ 👁 `example`, 🚫 `examples`), & 👈 ⚫️❔ ⚙️ 🛠️ 🩺 🎚 (⚙️ 🦁 🎚).
-
-, 👐 `example` 🚫 🍕 🎻 🔗, ⚫️ 🍕 🗄 🛃 ⏬ 🎻 🔗, & 👈 ⚫️❔ 🔜 ⚙️ 🩺 🎚.
-
-✋️ 🕐❔ 👆 ⚙️ `example` ⚖️ `examples` ⏮️ 🙆 🎏 🚙 (`Query()`, `Body()`, ♒️.) 📚 🖼 🚫 🚮 🎻 🔗 👈 🔬 👈 💽 (🚫 🗄 👍 ⏬ 🎻 🔗), 👫 🚮 🔗 *➡ 🛠️* 📄 🗄 (🏞 🍕 🗄 👈 ⚙️ 🎻 🔗).
-
-`Path()`, `Query()`, `Header()`, & `Cookie()`, `example` ⚖️ `examples` 🚮 🗄 🔑, `Parameter Object` (🔧).
-
-& `Body()`, `File()`, & `Form()`, `example` ⚖️ `examples` 📊 🚮 🗄 🔑, `Request Body Object`, 🏑 `content`, 🔛 `Media Type Object` (🔧).
-
-🔛 🎏 ✋, 📤 🆕 ⏬ 🗄: **3️⃣.1️⃣.0️⃣**, ⏳ 🚀. ⚫️ ⚓️ 🔛 ⏪ 🎻 🔗 & 🏆 🛠️ ⚪️➡️ 🗄 🛃 ⏬ 🎻 🔗 ❎, 💱 ⚒ ⚪️➡️ ⏮️ ⏬ 🎻 🔗, 🌐 👫 🤪 🔺 📉. 👐, 🦁 🎚 ⏳ 🚫 🐕🦺 🗄 3️⃣.1️⃣.0️⃣,, 🔜, ⚫️ 👍 😣 ⚙️ 💭 🔛.
diff --git a/docs/em/docs/tutorial/security/first-steps.md b/docs/em/docs/tutorial/security/first-steps.md
deleted file mode 100644
index 8fb459a65..000000000
--- a/docs/em/docs/tutorial/security/first-steps.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# 💂♂ - 🥇 🔁
-
-➡️ 🌈 👈 👆 ✔️ 👆 **👩💻** 🛠️ 🆔.
-
-& 👆 ✔️ **🕸** ➕1️⃣ 🆔 ⚖️ 🎏 ➡ 🎏 🆔 (⚖️ 📱 🈸).
-
-& 👆 💚 ✔️ 🌌 🕸 🔓 ⏮️ 👩💻, ⚙️ **🆔** & **🔐**.
-
-👥 💪 ⚙️ **Oauth2️⃣** 🏗 👈 ⏮️ **FastAPI**.
-
-✋️ ➡️ 🖊 👆 🕰 👂 🌕 📏 🔧 🔎 👈 🐥 🍖 ℹ 👆 💪.
-
-➡️ ⚙️ 🧰 🚚 **FastAPI** 🍵 💂♂.
-
-## ❔ ⚫️ 👀
-
-➡️ 🥇 ⚙️ 📟 & 👀 ❔ ⚫️ 👷, & ⤴️ 👥 🔜 👟 🔙 🤔 ⚫️❔ 😥.
-
-## ✍ `main.py`
-
-📁 🖼 📁 `main.py`:
-
-{* ../../docs_src/security/tutorial001.py *}
-
-## 🏃 ⚫️
-
-/// info
-
-🥇 ❎ `python-multipart`.
-
-🤶 Ⓜ. `pip install python-multipart`.
-
-👉 ↩️ **Oauth2️⃣** ⚙️ "📨 📊" 📨 `username` & `password`.
-
-///
-
-🏃 🖼 ⏮️:
-
-
-
-/// check | ✔ 🔼 ❗
-
-👆 ⏪ ✔️ ✨ 🆕 "✔" 🔼.
-
- & 👆 *➡ 🛠️* ✔️ 🐥 🔒 🔝-▶️️ ↩ 👈 👆 💪 🖊.
-
-///
-
-& 🚥 👆 🖊 ⚫️, 👆 ✔️ 🐥 ✔ 📨 🆎 `username` & `password` (& 🎏 📦 🏑):
-
-
-
-/// note
-
-⚫️ 🚫 🤔 ⚫️❔ 👆 🆎 📨, ⚫️ 🏆 🚫 👷. ✋️ 👥 🔜 🤚 📤.
-
-///
-
-👉 ↗️ 🚫 🕸 🏁 👩💻, ✋️ ⚫️ 👑 🏧 🧰 📄 🖥 🌐 👆 🛠️.
-
-⚫️ 💪 ⚙️ 🕸 🏉 (👈 💪 👆).
-
-⚫️ 💪 ⚙️ 🥉 🥳 🈸 & ⚙️.
-
-& ⚫️ 💪 ⚙️ 👆, ℹ, ✅ & 💯 🎏 🈸.
-
-## `password` 💧
-
-🔜 ➡️ 🚶 🔙 👄 & 🤔 ⚫️❔ 🌐 👈.
-
-`password` "💧" 1️⃣ 🌌 ("💧") 🔬 Oauth2️⃣, 🍵 💂♂ & 🤝.
-
-Oauth2️⃣ 🔧 👈 👩💻 ⚖️ 🛠️ 💪 🔬 💽 👈 🔓 👩💻.
-
-✋️ 👉 💼, 🎏 **FastAPI** 🈸 🔜 🍵 🛠️ & 🤝.
-
-, ➡️ 📄 ⚫️ ⚪️➡️ 👈 📉 ☝ 🎑:
-
-* 👩💻 🆎 `username` & `password` 🕸, & 🎯 `Enter`.
-* 🕸 (🏃♂ 👩💻 🖥) 📨 👈 `username` & `password` 🎯 📛 👆 🛠️ (📣 ⏮️ `tokenUrl="token"`).
-* 🛠️ ✅ 👈 `username` & `password`, & 📨 ⏮️ "🤝" (👥 🚫 🛠️ 🙆 👉).
- * "🤝" 🎻 ⏮️ 🎚 👈 👥 💪 ⚙️ ⏪ ✔ 👉 👩💻.
- * 🛎, 🤝 ⚒ 🕛 ⏮️ 🕰.
- * , 👩💻 🔜 ✔️ 🕹 🔄 ☝ ⏪.
- * & 🚥 🤝 📎, ⚠ 🌘. ⚫️ 🚫 💖 🧲 🔑 👈 🔜 👷 ♾ (🏆 💼).
-* 🕸 🏪 👈 🤝 🍕 👱.
-* 👩💻 🖊 🕸 🚶 ➕1️⃣ 📄 🕸 🕸 📱.
-* 🕸 💪 ☕ 🌅 💽 ⚪️➡️ 🛠️.
- * ✋️ ⚫️ 💪 🤝 👈 🎯 🔗.
- * , 🔓 ⏮️ 👆 🛠️, ⚫️ 📨 🎚 `Authorization` ⏮️ 💲 `Bearer ` ➕ 🤝.
- * 🚥 🤝 🔌 `foobar`, 🎚 `Authorization` 🎚 🔜: `Bearer foobar`.
-
-## **FastAPI**'Ⓜ `OAuth2PasswordBearer`
-
-**FastAPI** 🚚 📚 🧰, 🎏 🎚 ⚛, 🛠️ 👫 💂♂ ⚒.
-
-👉 🖼 👥 🔜 ⚙️ **Oauth2️⃣**, ⏮️ **🔐** 💧, ⚙️ **📨** 🤝. 👥 👈 ⚙️ `OAuth2PasswordBearer` 🎓.
-
-/// info
-
-"📨" 🤝 🚫 🕴 🎛.
-
-✋️ ⚫️ 🏆 1️⃣ 👆 ⚙️ 💼.
-
- & ⚫️ 💪 🏆 🏆 ⚙️ 💼, 🚥 👆 Oauth2️⃣ 🕴 & 💭 ⚫️❔ ⚫️❔ 📤 ➕1️⃣ 🎛 👈 ♣ 👻 👆 💪.
-
-👈 💼, **FastAPI** 🚚 👆 ⏮️ 🧰 🏗 ⚫️.
-
-///
-
-🕐❔ 👥 ✍ 👐 `OAuth2PasswordBearer` 🎓 👥 🚶♀️ `tokenUrl` 🔢. 👉 🔢 🔌 📛 👈 👩💻 (🕸 🏃 👩💻 🖥) 🔜 ⚙️ 📨 `username` & `password` ✔ 🤚 🤝.
-
-{* ../../docs_src/security/tutorial001.py hl[6] *}
-
-/// tip
-
-📥 `tokenUrl="token"` 🔗 ⚖ 📛 `token` 👈 👥 🚫 ✍. ⚫️ ⚖ 📛, ⚫️ 🌓 `./token`.
-
-↩️ 👥 ⚙️ ⚖ 📛, 🚥 👆 🛠️ 🔎 `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`.
-
-👈 ↩️ ⚫️ ⚙️ 🎏 📛 🗄 🔌. 👈 🚥 👆 💪 🔬 🌅 🔃 🙆 👫 💂♂ ⚖ 👆 💪 📁 & 📋 ⚫️ 🔎 🌖 ℹ 🔃 ⚫️.
-
-///
-
-`oauth2_scheme` 🔢 👐 `OAuth2PasswordBearer`, ✋️ ⚫️ "🇧🇲".
-
-⚫️ 💪 🤙:
-
-```Python
-oauth2_scheme(some, parameters)
-```
-
-, ⚫️ 💪 ⚙️ ⏮️ `Depends`.
-
-### ⚙️ ⚫️
-
-🔜 👆 💪 🚶♀️ 👈 `oauth2_scheme` 🔗 ⏮️ `Depends`.
-
-{* ../../docs_src/security/tutorial001.py hl[10] *}
-
-👉 🔗 🔜 🚚 `str` 👈 🛠️ 🔢 `token` *➡ 🛠️ 🔢*.
-
-**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 👉 🔗 🔬 "💂♂ ⚖" 🗄 🔗 (& 🏧 🛠️ 🩺).
-
-/// info | 📡 ℹ
-
-**FastAPI** 🔜 💭 👈 ⚫️ 💪 ⚙️ 🎓 `OAuth2PasswordBearer` (📣 🔗) 🔬 💂♂ ⚖ 🗄 ↩️ ⚫️ 😖 ⚪️➡️ `fastapi.security.oauth2.OAuth2`, ❔ 🔄 😖 ⚪️➡️ `fastapi.security.base.SecurityBase`.
-
-🌐 💂♂ 🚙 👈 🛠️ ⏮️ 🗄 (& 🏧 🛠️ 🩺) 😖 ⚪️➡️ `SecurityBase`, 👈 ❔ **FastAPI** 💪 💭 ❔ 🛠️ 👫 🗄.
-
-///
-
-## ⚫️❔ ⚫️ 🔨
-
-⚫️ 🔜 🚶 & 👀 📨 👈 `Authorization` 🎚, ✅ 🚥 💲 `Bearer ` ➕ 🤝, & 🔜 📨 🤝 `str`.
-
-🚥 ⚫️ 🚫 👀 `Authorization` 🎚, ⚖️ 💲 🚫 ✔️ `Bearer ` 🤝, ⚫️ 🔜 📨 ⏮️ 4️⃣0️⃣1️⃣ 👔 📟 ❌ (`UNAUTHORIZED`) 🔗.
-
-👆 🚫 ✔️ ✅ 🚥 🤝 🔀 📨 ❌. 👆 💪 💭 👈 🚥 👆 🔢 🛠️, ⚫️ 🔜 ✔️ `str` 👈 🤝.
-
-👆 💪 🔄 ⚫️ ⏪ 🎓 🩺:
-
-
-
-👥 🚫 ✔ 🔬 🤝, ✋️ 👈 ▶️ ⏪.
-
-## 🌃
-
-, 3️⃣ ⚖️ 4️⃣ ➕ ⏸, 👆 ⏪ ✔️ 🐒 📨 💂♂.
diff --git a/docs/em/docs/tutorial/security/get-current-user.md b/docs/em/docs/tutorial/security/get-current-user.md
deleted file mode 100644
index 2f4a26f35..000000000
--- a/docs/em/docs/tutorial/security/get-current-user.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# 🤚 ⏮️ 👩💻
-
-⏮️ 📃 💂♂ ⚙️ (❔ 🧢 🔛 🔗 💉 ⚙️) 🤝 *➡ 🛠️ 🔢* `token` `str`:
-
-{* ../../docs_src/security/tutorial001.py hl[10] *}
-
-✋️ 👈 🚫 👈 ⚠.
-
-➡️ ⚒ ⚫️ 🤝 👥 ⏮️ 👩💻.
-
-## ✍ 👩💻 🏷
-
-🥇, ➡️ ✍ Pydantic 👩💻 🏷.
-
-🎏 🌌 👥 ⚙️ Pydantic 📣 💪, 👥 💪 ⚙️ ⚫️ 🙆 🙆:
-
-{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
-
-## ✍ `get_current_user` 🔗
-
-➡️ ✍ 🔗 `get_current_user`.
-
-💭 👈 🔗 💪 ✔️ 🎧-🔗 ❓
-
-`get_current_user` 🔜 ✔️ 🔗 ⏮️ 🎏 `oauth2_scheme` 👥 ✍ ⏭.
-
-🎏 👥 🔨 ⏭ *➡ 🛠️* 🔗, 👆 🆕 🔗 `get_current_user` 🔜 📨 `token` `str` ⚪️➡️ 🎧-🔗 `oauth2_scheme`:
-
-{* ../../docs_src/security/tutorial002.py hl[25] *}
-
-## 🤚 👩💻
-
-`get_current_user` 🔜 ⚙️ (❌) 🚙 🔢 👥 ✍, 👈 ✊ 🤝 `str` & 📨 👆 Pydantic `User` 🏷:
-
-{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
-
-## 💉 ⏮️ 👩💻
-
-🔜 👥 💪 ⚙️ 🎏 `Depends` ⏮️ 👆 `get_current_user` *➡ 🛠️*:
-
-{* ../../docs_src/security/tutorial002.py hl[31] *}
-
-👀 👈 👥 📣 🆎 `current_user` Pydantic 🏷 `User`.
-
-👉 🔜 ℹ 🇺🇲 🔘 🔢 ⏮️ 🌐 🛠️ & 🆎 ✅.
-
-/// tip
-
-👆 5️⃣📆 💭 👈 📨 💪 📣 ⏮️ Pydantic 🏷.
-
-📥 **FastAPI** 🏆 🚫 🤚 😨 ↩️ 👆 ⚙️ `Depends`.
-
-///
-
-/// check
-
-🌌 👉 🔗 ⚙️ 🏗 ✔ 👥 ✔️ 🎏 🔗 (🎏 "☑") 👈 🌐 📨 `User` 🏷.
-
-👥 🚫 🚫 ✔️ 🕴 1️⃣ 🔗 👈 💪 📨 👈 🆎 💽.
-
-///
-
-## 🎏 🏷
-
-👆 💪 🔜 🤚 ⏮️ 👩💻 🔗 *➡ 🛠️ 🔢* & 🙅 ⏮️ 💂♂ 🛠️ **🔗 💉** 🎚, ⚙️ `Depends`.
-
-& 👆 💪 ⚙️ 🙆 🏷 ⚖️ 💽 💂♂ 📄 (👉 💼, Pydantic 🏷 `User`).
-
-✋️ 👆 🚫 🚫 ⚙️ 🎯 💽 🏷, 🎓 ⚖️ 🆎.
-
-👆 💚 ✔️ `id` & `email` & 🚫 ✔️ 🙆 `username` 👆 🏷 ❓ 💭. 👆 💪 ⚙️ 👉 🎏 🧰.
-
-👆 💚 ✔️ `str`❓ ⚖️ `dict`❓ ⚖️ 💽 🎓 🏷 👐 🔗 ❓ ⚫️ 🌐 👷 🎏 🌌.
-
-👆 🤙 🚫 ✔️ 👩💻 👈 🕹 👆 🈸 ✋️ 🤖, 🤖, ⚖️ 🎏 ⚙️, 👈 ✔️ 🔐 🤝 ❓ 🔄, ⚫️ 🌐 👷 🎏.
-
-⚙️ 🙆 😇 🏷, 🙆 😇 🎓, 🙆 😇 💽 👈 👆 💪 👆 🈸. **FastAPI** ✔️ 👆 📔 ⏮️ 🔗 💉 ⚙️.
-
-## 📟 📐
-
-👉 🖼 5️⃣📆 😑 🔁. ✔️ 🤯 👈 👥 🌀 💂♂, 📊 🏷, 🚙 🔢 & *➡ 🛠️* 🎏 📁.
-
-✋️ 📥 🔑 ☝.
-
-💂♂ & 🔗 💉 💩 ✍ 🕐.
-
-& 👆 💪 ⚒ ⚫️ 🏗 👆 💚. & , ✔️ ⚫️ ✍ 🕴 🕐, 👁 🥉. ⏮️ 🌐 💪.
-
-✋️ 👆 💪 ✔️ 💯 🔗 (*➡ 🛠️*) ⚙️ 🎏 💂♂ ⚙️.
-
-& 🌐 👫 (⚖️ 🙆 ↔ 👫 👈 👆 💚) 💪 ✊ 📈 🏤-⚙️ 👫 🔗 ⚖️ 🙆 🎏 🔗 👆 ✍.
-
-& 🌐 👉 💯 *➡ 🛠️* 💪 🤪 3️⃣ ⏸:
-
-{* ../../docs_src/security/tutorial002.py hl[30:32] *}
-
-## 🌃
-
-👆 💪 🔜 🤚 ⏮️ 👩💻 🔗 👆 *➡ 🛠️ 🔢*.
-
-👥 ⏪ 😬 📤.
-
-👥 💪 🚮 *➡ 🛠️* 👩💻/👩💻 🤙 📨 `username` & `password`.
-
-👈 👟 ⏭.
diff --git a/docs/em/docs/tutorial/security/index.md b/docs/em/docs/tutorial/security/index.md
deleted file mode 100644
index 1a47e5510..000000000
--- a/docs/em/docs/tutorial/security/index.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# 💂♂
-
-📤 📚 🌌 🍵 💂♂, 🤝 & ✔.
-
-& ⚫️ 🛎 🏗 & "⚠" ❔.
-
-📚 🛠️ & ⚙️ 🍵 💂♂ & 🤝 ✊ 🦏 💸 🎯 & 📟 (📚 💼 ⚫️ 💪 5️⃣0️⃣ 💯 ⚖️ 🌅 🌐 📟 ✍).
-
-**FastAPI** 🚚 📚 🧰 ℹ 👆 🙅 ⏮️ **💂♂** 💪, 📉, 🐩 🌌, 🍵 ✔️ 🔬 & 💡 🌐 💂♂ 🔧.
-
-✋️ 🥇, ➡️ ✅ 🤪 🔧.
-
-## 🏃 ❓
-
-🚥 👆 🚫 💅 🔃 🙆 👉 ⚖ & 👆 💪 🚮 💂♂ ⏮️ 🤝 ⚓️ 🔛 🆔 & 🔐 *▶️️ 🔜*, 🚶 ⏭ 📃.
-
-## Oauth2️⃣
-
-Oauth2️⃣ 🔧 👈 🔬 📚 🌌 🍵 🤝 & ✔.
-
-⚫️ 🔬 🔧 & 📔 📚 🏗 ⚙️ 💼.
-
-⚫️ 🔌 🌌 🔓 ⚙️ "🥉 🥳".
-
-👈 ⚫️❔ 🌐 ⚙️ ⏮️ "💳 ⏮️ 👱📔, 🇺🇸🔍, 👱📔, 📂" ⚙️ 🔘.
-
-### ✳ 1️⃣
-
-📤 ✳ 1️⃣, ❔ 📶 🎏 ⚪️➡️ Oauth2️⃣, & 🌖 🏗, ⚫️ 🔌 🔗 🔧 🔛 ❔ 🗜 📻.
-
-⚫️ 🚫 📶 🌟 ⚖️ ⚙️ 🛎.
-
-Oauth2️⃣ 🚫 ✔ ❔ 🗜 📻, ⚫️ ⌛ 👆 ✔️ 👆 🈸 🍦 ⏮️ 🇺🇸🔍.
-
-/// tip
-
-📄 🔃 **🛠️** 👆 🔜 👀 ❔ ⚒ 🆙 🇺🇸🔍 🆓, ⚙️ Traefik & ➡️ 🗜.
-
-///
-
-## 👩💻 🔗
-
-👩💻 🔗 ➕1️⃣ 🔧, 🧢 🔛 **Oauth2️⃣**.
-
-⚫️ ↔ Oauth2️⃣ ✔ 👜 👈 📶 🌌 Oauth2️⃣, 🔄 ⚒ ⚫️ 🌅 🛠️.
-
-🖼, 🇺🇸🔍 💳 ⚙️ 👩💻 🔗 (❔ 🔘 ⚙️ Oauth2️⃣).
-
-✋️ 👱📔 💳 🚫 🐕🦺 👩💻 🔗. ⚫️ ✔️ 🚮 👍 🍛 Oauth2️⃣.
-
-### 👩💻 (🚫 "👩💻 🔗")
-
-📤 "👩💻" 🔧. 👈 🔄 ❎ 🎏 👜 **👩💻 🔗**, ✋️ 🚫 ⚓️ 🔛 Oauth2️⃣.
-
-, ⚫️ 🏁 🌖 ⚙️.
-
-⚫️ 🚫 📶 🌟 ⚖️ ⚙️ 🛎.
-
-## 🗄
-
-🗄 (⏪ 💭 🦁) 📂 🔧 🏗 🔗 (🔜 🍕 💾 🏛).
-
-**FastAPI** ⚓️ 🔛 **🗄**.
-
-👈 ⚫️❔ ⚒ ⚫️ 💪 ✔️ 💗 🏧 🎓 🧾 🔢, 📟 ⚡, ♒️.
-
-🗄 ✔️ 🌌 🔬 💗 💂♂ "⚖".
-
-⚙️ 👫, 👆 💪 ✊ 📈 🌐 👫 🐩-⚓️ 🧰, 🔌 👉 🎓 🧾 ⚙️.
-
-🗄 🔬 📄 💂♂ ⚖:
-
-* `apiKey`: 🈸 🎯 🔑 👈 💪 👟 ⚪️➡️:
- * 🔢 🔢.
- * 🎚.
- * 🍪.
-* `http`: 🐩 🇺🇸🔍 🤝 ⚙️, 🔌:
- * `bearer`: 🎚 `Authorization` ⏮️ 💲 `Bearer ` ➕ 🤝. 👉 😖 ⚪️➡️ Oauth2️⃣.
- * 🇺🇸🔍 🔰 🤝.
- * 🇺🇸🔍 📰, ♒️.
-* `oauth2`: 🌐 Oauth2️⃣ 🌌 🍵 💂♂ (🤙 "💧").
- * 📚 👫 💧 ☑ 🏗 ✳ 2️⃣.0️⃣ 🤝 🐕🦺 (💖 🇺🇸🔍, 👱📔, 👱📔, 📂, ♒️):
- * `implicit`
- * `clientCredentials`
- * `authorizationCode`
- * ✋️ 📤 1️⃣ 🎯 "💧" 👈 💪 👌 ⚙️ 🚚 🤝 🎏 🈸 🔗:
- * `password`: ⏭ 📃 🔜 📔 🖼 👉.
-* `openIdConnect`: ✔️ 🌌 🔬 ❔ 🔎 Oauth2️⃣ 🤝 📊 🔁.
- * 👉 🏧 🔍 ⚫️❔ 🔬 👩💻 🔗 🔧.
-
-
-/// tip
-
-🛠️ 🎏 🤝/✔ 🐕🦺 💖 🇺🇸🔍, 👱📔, 👱📔, 📂, ♒️. 💪 & 📶 ⏩.
-
-🌅 🏗 ⚠ 🏗 🤝/✔ 🐕🦺 💖 👈, ✋️ **FastAPI** 🤝 👆 🧰 ⚫️ 💪, ⏪ 🔨 🏋️ 🏋♂ 👆.
-
-///
-
-## **FastAPI** 🚙
-
-FastAPI 🚚 📚 🧰 🔠 👉 💂♂ ⚖ `fastapi.security` 🕹 👈 📉 ⚙️ 👉 💂♂ 🛠️.
-
-⏭ 📃 👆 🔜 👀 ❔ 🚮 💂♂ 👆 🛠️ ⚙️ 📚 🧰 🚚 **FastAPI**.
-
-& 👆 🔜 👀 ❔ ⚫️ 🤚 🔁 🛠️ 🔘 🎓 🧾 ⚙️.
diff --git a/docs/em/docs/tutorial/security/oauth2-jwt.md b/docs/em/docs/tutorial/security/oauth2-jwt.md
deleted file mode 100644
index ee7bc2d28..000000000
--- a/docs/em/docs/tutorial/security/oauth2-jwt.md
+++ /dev/null
@@ -1,275 +0,0 @@
-# Oauth2️⃣ ⏮️ 🔐 (& 🔁), 📨 ⏮️ 🥙 🤝
-
-🔜 👈 👥 ✔️ 🌐 💂♂ 💧, ➡️ ⚒ 🈸 🤙 🔐, ⚙️ 🥙 🤝 & 🔐 🔐 🔁.
-
-👉 📟 🕳 👆 💪 🤙 ⚙️ 👆 🈸, 🖊 🔐 #️⃣ 👆 💽, ♒️.
-
-👥 🔜 ▶️ ⚪️➡️ 🌐❔ 👥 ◀️ ⏮️ 📃 & 📈 ⚫️.
-
-## 🔃 🥙
-
-🥙 ⛓ "🎻 🕸 🤝".
-
-⚫️ 🐩 🚫 🎻 🎚 📏 💧 🎻 🍵 🚀. ⚫️ 👀 💖 👉:
-
-```
-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
-```
-
-⚫️ 🚫 🗜,, 🙆 💪 🛡 ℹ ⚪️➡️ 🎚.
-
-✋️ ⚫️ 🛑. , 🕐❔ 👆 📨 🤝 👈 👆 ♨, 👆 💪 ✔ 👈 👆 🤙 ♨ ⚫️.
-
-👈 🌌, 👆 💪 ✍ 🤝 ⏮️ 👔, ➡️ 💬, 1️⃣ 🗓️. & ⤴️ 🕐❔ 👩💻 👟 🔙 ⏭ 📆 ⏮️ 🤝, 👆 💭 👈 👩💻 🕹 👆 ⚙️.
-
-⏮️ 🗓️, 🤝 🔜 🕛 & 👩💻 🔜 🚫 ✔ & 🔜 ✔️ 🛑 🔄 🤚 🆕 🤝. & 🚥 👩💻 (⚖️ 🥉 🥳) 🔄 🔀 🤝 🔀 👔, 👆 🔜 💪 🔎 ⚫️, ↩️ 💳 🔜 🚫 🏏.
-
-🚥 👆 💚 🤾 ⏮️ 🥙 🤝 & 👀 ❔ 👫 👷, ✅ https://jwt.io.
-
-## ❎ `python-jose`
-
-👥 💪 ❎ `python-jose` 🏗 & ✔ 🥙 🤝 🐍:
-
-
-
-✔ 🈸 🎏 🌌 ⏭.
-
-⚙️ 🎓:
-
-🆔: `johndoe`
-🔐: `secret`
-
-/// check
-
-👀 👈 🕳 📟 🔢 🔐 "`secret`", 👥 🕴 ✔️ #️⃣ ⏬.
-
-///
-
-
-
-🤙 🔗 `/users/me/`, 👆 🔜 🤚 📨:
-
-```JSON
-{
- "username": "johndoe",
- "email": "johndoe@example.com",
- "full_name": "John Doe",
- "disabled": false
-}
-```
-
-
-
-🚥 👆 📂 👩💻 🧰, 👆 💪 👀 ❔ 📊 📨 🕴 🔌 🤝, 🔐 🕴 📨 🥇 📨 🔓 👩💻 & 🤚 👈 🔐 🤝, ✋️ 🚫 ⏮️:
-
-
-
-/// note
-
-👀 🎚 `Authorization`, ⏮️ 💲 👈 ▶️ ⏮️ `Bearer `.
-
-///
-
-## 🏧 ⚙️ ⏮️ `scopes`
-
-Oauth2️⃣ ✔️ 🔑 "↔".
-
-👆 💪 ⚙️ 👫 🚮 🎯 ⚒ ✔ 🥙 🤝.
-
-⤴️ 👆 💪 🤝 👉 🤝 👩💻 🔗 ⚖️ 🥉 🥳, 🔗 ⏮️ 👆 🛠️ ⏮️ ⚒ 🚫.
-
-👆 💪 💡 ❔ ⚙️ 👫 & ❔ 👫 🛠️ 🔘 **FastAPI** ⏪ **🏧 👩💻 🦮**.
-
-## 🌃
-
-⏮️ ⚫️❔ 👆 ✔️ 👀 🆙 🔜, 👆 💪 ⚒ 🆙 🔐 **FastAPI** 🈸 ⚙️ 🐩 💖 Oauth2️⃣ & 🥙.
-
-🌖 🙆 🛠️ 🚚 💂♂ ▶️️ 👍 🏗 📄 🔜.
-
-📚 📦 👈 📉 ⚫️ 📚 ✔️ ⚒ 📚 ⚠ ⏮️ 💽 🏷, 💽, & 💪 ⚒. & 👉 📦 👈 📉 👜 💁♂️ 🌅 🤙 ✔️ 💂♂ ⚠ 🔘.
-
----
-
-**FastAPI** 🚫 ⚒ 🙆 ⚠ ⏮️ 🙆 💽, 💽 🏷 ⚖️ 🧰.
-
-⚫️ 🤝 👆 🌐 💪 ⚒ 🕐 👈 👖 👆 🏗 🏆.
-
-& 👆 💪 ⚙️ 🔗 📚 👍 🚧 & 🛎 ⚙️ 📦 💖 `passlib` & `python-jose`, ↩️ **FastAPI** 🚫 🚚 🙆 🏗 🛠️ 🛠️ 🔢 📦.
-
-✋️ ⚫️ 🚚 👆 🧰 📉 🛠️ 🌅 💪 🍵 🎯 💪, ⚖, ⚖️ 💂♂.
-
-& 👆 💪 ⚙️ & 🛠️ 🔐, 🐩 🛠️, 💖 Oauth2️⃣ 📶 🙅 🌌.
-
-👆 💪 💡 🌅 **🏧 👩💻 🦮** 🔃 ❔ ⚙️ Oauth2️⃣ "↔", 🌖 👌-🧽 ✔ ⚙️, 📄 👫 🎏 🐩. Oauth2️⃣ ⏮️ ↔ 🛠️ ⚙️ 📚 🦏 🤝 🐕🦺, 💖 👱📔, 🇺🇸🔍, 📂, 🤸♂, 👱📔, ♒️. ✔ 🥉 🥳 🈸 🔗 ⏮️ 👫 🔗 🔛 👨💼 👫 👩💻.
diff --git a/docs/em/docs/tutorial/security/simple-oauth2.md b/docs/em/docs/tutorial/security/simple-oauth2.md
deleted file mode 100644
index 1fd513d48..000000000
--- a/docs/em/docs/tutorial/security/simple-oauth2.md
+++ /dev/null
@@ -1,289 +0,0 @@
-# 🙅 Oauth2️⃣ ⏮️ 🔐 & 📨
-
-🔜 ➡️ 🏗 ⚪️➡️ ⏮️ 📃 & 🚮 ❌ 🍕 ✔️ 🏁 💂♂ 💧.
-
-## 🤚 `username` & `password`
-
-👥 🔜 ⚙️ **FastAPI** 💂♂ 🚙 🤚 `username` & `password`.
-
-Oauth2️⃣ ✔ 👈 🕐❔ ⚙️ "🔐 💧" (👈 👥 ⚙️) 👩💻/👩💻 🔜 📨 `username` & `password` 🏑 📨 💽.
-
-& 🔌 💬 👈 🏑 ✔️ 🌟 💖 👈. `user-name` ⚖️ `email` 🚫🔜 👷.
-
-✋️ 🚫 😟, 👆 💪 🎦 ⚫️ 👆 🎋 👆 🏁 👩💻 🕸.
-
-& 👆 💽 🏷 💪 ⚙️ 🙆 🎏 📛 👆 💚.
-
-✋️ 💳 *➡ 🛠️*, 👥 💪 ⚙️ 👉 📛 🔗 ⏮️ 🔌 (& 💪, 🖼, ⚙️ 🛠️ 🛠️ 🧾 ⚙️).
-
-🔌 🇵🇸 👈 `username` & `password` 🔜 📨 📨 💽 (, 🙅♂ 🎻 📥).
-
-### `scope`
-
-🔌 💬 👈 👩💻 💪 📨 ➕1️⃣ 📨 🏑 "`scope`".
-
-📨 🏑 📛 `scope` (⭐), ✋️ ⚫️ 🤙 📏 🎻 ⏮️ "↔" 🎏 🚀.
-
-🔠 "↔" 🎻 (🍵 🚀).
-
-👫 🛎 ⚙️ 📣 🎯 💂♂ ✔, 🖼:
-
-* `users:read` ⚖️ `users:write` ⚠ 🖼.
-* `instagram_basic` ⚙️ 👱📔 / 👱📔.
-* `https://www.googleapis.com/auth/drive` ⚙️ 🇺🇸🔍.
-
-/// info
-
-Oauth2️⃣ "↔" 🎻 👈 📣 🎯 ✔ ✔.
-
-⚫️ 🚫 🤔 🚥 ⚫️ ✔️ 🎏 🦹 💖 `:` ⚖️ 🚥 ⚫️ 📛.
-
-👈 ℹ 🛠️ 🎯.
-
-Oauth2️⃣ 👫 🎻.
-
-///
-
-## 📟 🤚 `username` & `password`
-
-🔜 ➡️ ⚙️ 🚙 🚚 **FastAPI** 🍵 👉.
-
-### `OAuth2PasswordRequestForm`
-
-🥇, 🗄 `OAuth2PasswordRequestForm`, & ⚙️ ⚫️ 🔗 ⏮️ `Depends` *➡ 🛠️* `/token`:
-
-{* ../../docs_src/security/tutorial003.py hl[4,76] *}
-
-`OAuth2PasswordRequestForm` 🎓 🔗 👈 📣 📨 💪 ⏮️:
-
-* `username`.
-* `password`.
-* 📦 `scope` 🏑 🦏 🎻, ✍ 🎻 🎏 🚀.
-* 📦 `grant_type`.
-
-/// tip
-
-Oauth2️⃣ 🔌 🤙 *🚚* 🏑 `grant_type` ⏮️ 🔧 💲 `password`, ✋️ `OAuth2PasswordRequestForm` 🚫 🛠️ ⚫️.
-
-🚥 👆 💪 🛠️ ⚫️, ⚙️ `OAuth2PasswordRequestFormStrict` ↩️ `OAuth2PasswordRequestForm`.
-
-///
-
-* 📦 `client_id` (👥 🚫 💪 ⚫️ 👆 🖼).
-* 📦 `client_secret` (👥 🚫 💪 ⚫️ 👆 🖼).
-
-/// info
-
-`OAuth2PasswordRequestForm` 🚫 🎁 🎓 **FastAPI** `OAuth2PasswordBearer`.
-
-`OAuth2PasswordBearer` ⚒ **FastAPI** 💭 👈 ⚫️ 💂♂ ⚖. ⚫️ 🚮 👈 🌌 🗄.
-
-✋️ `OAuth2PasswordRequestForm` 🎓 🔗 👈 👆 💪 ✔️ ✍ 👆, ⚖️ 👆 💪 ✔️ 📣 `Form` 🔢 🔗.
-
-✋️ ⚫️ ⚠ ⚙️ 💼, ⚫️ 🚚 **FastAPI** 🔗, ⚒ ⚫️ ⏩.
-
-///
-
-### ⚙️ 📨 💽
-
-/// tip
-
-👐 🔗 🎓 `OAuth2PasswordRequestForm` 🏆 🚫 ✔️ 🔢 `scope` ⏮️ 📏 🎻 👽 🚀, ↩️, ⚫️ 🔜 ✔️ `scopes` 🔢 ⏮️ ☑ 📇 🎻 🔠 ↔ 📨.
-
-👥 🚫 ⚙️ `scopes` 👉 🖼, ✋️ 🛠️ 📤 🚥 👆 💪 ⚫️.
-
-///
-
-🔜, 🤚 👩💻 📊 ⚪️➡️ (❌) 💽, ⚙️ `username` ⚪️➡️ 📨 🏑.
-
-🚥 📤 🙅♂ ✅ 👩💻, 👥 📨 ❌ 💬 "❌ 🆔 ⚖️ 🔐".
-
-❌, 👥 ⚙️ ⚠ `HTTPException`:
-
-{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
-
-### ✅ 🔐
-
-👉 ☝ 👥 ✔️ 👩💻 📊 ⚪️➡️ 👆 💽, ✋️ 👥 🚫 ✅ 🔐.
-
-➡️ 🚮 👈 💽 Pydantic `UserInDB` 🏷 🥇.
-
-👆 🔜 🙅 🖊 🔢 🔐,, 👥 🔜 ⚙️ (❌) 🔐 🔁 ⚙️.
-
-🚥 🔐 🚫 🏏, 👥 📨 🎏 ❌.
-
-#### 🔐 🔁
-
-"🔁" ⛓: 🏭 🎚 (🔐 👉 💼) 🔘 🔁 🔢 (🎻) 👈 👀 💖 🙃.
-
-🕐❔ 👆 🚶♀️ ⚫️❔ 🎏 🎚 (⚫️❔ 🎏 🔐) 👆 🤚 ⚫️❔ 🎏 🙃.
-
-✋️ 👆 🚫🔜 🗜 ⚪️➡️ 🙃 🔙 🔐.
-
-##### ⚫️❔ ⚙️ 🔐 🔁
-
-🚥 👆 💽 📎, 🧙♀ 🏆 🚫 ✔️ 👆 👩💻' 🔢 🔐, 🕴#️⃣.
-
-, 🧙♀ 🏆 🚫 💪 🔄 ⚙️ 👈 🎏 🔐 ➕1️⃣ ⚙️ (📚 👩💻 ⚙️ 🎏 🔐 🌐, 👉 🔜 ⚠).
-
-{* ../../docs_src/security/tutorial003.py hl[80:83] *}
-
-#### 🔃 `**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
-
-🌅 🏁 🔑 `**👩💻_ #️⃣ ` ✅ 🔙 [🧾 **➕ 🏷**](../extra-models.md#user_indict){.internal-link target=_blank}.
-
-///
-
-## 📨 🤝
-
-📨 `token` 🔗 🔜 🎻 🎚.
-
-⚫️ 🔜 ✔️ `token_type`. 👆 💼, 👥 ⚙️ "📨" 🤝, 🤝 🆎 🔜 "`bearer`".
-
-& ⚫️ 🔜 ✔️ `access_token`, ⏮️ 🎻 ⚗ 👆 🔐 🤝.
-
-👉 🙅 🖼, 👥 🔜 🍕 😟 & 📨 🎏 `username` 🤝.
-
-/// tip
-
-⏭ 📃, 👆 🔜 👀 🎰 🔐 🛠️, ⏮️ 🔐 #️⃣ & 🥙 🤝.
-
-✋️ 🔜, ➡️ 🎯 🔛 🎯 ℹ 👥 💪.
-
-///
-
-{* ../../docs_src/security/tutorial003.py hl[85] *}
-
-/// tip
-
-🔌, 👆 🔜 📨 🎻 ⏮️ `access_token` & `token_type`, 🎏 👉 🖼.
-
-👉 🕳 👈 👆 ✔️ 👆 👆 📟, & ⚒ 💭 👆 ⚙️ 📚 🎻 🔑.
-
-⚫️ 🌖 🕴 👜 👈 👆 ✔️ 💭 ☑ 👆, 🛠️ ⏮️ 🔧.
-
-🎂, **FastAPI** 🍵 ⚫️ 👆.
-
-///
-
-## ℹ 🔗
-
-🔜 👥 🔜 ℹ 👆 🔗.
-
-👥 💚 🤚 `current_user` *🕴* 🚥 👉 👩💻 🦁.
-
-, 👥 ✍ 🌖 🔗 `get_current_active_user` 👈 🔄 ⚙️ `get_current_user` 🔗.
-
-👯♂️ 👉 🔗 🔜 📨 🇺🇸🔍 ❌ 🚥 👩💻 🚫 🔀, ⚖️ 🚥 🔕.
-
-, 👆 🔗, 👥 🔜 🕴 🤚 👩💻 🚥 👩💻 🔀, ☑ 🔓, & 🦁:
-
-{* ../../docs_src/security/tutorial003.py hl[58:66,69:72,90] *}
-
-/// info
-
-🌖 🎚 `WWW-Authenticate` ⏮️ 💲 `Bearer` 👥 🛬 📥 🍕 🔌.
-
-🙆 🇺🇸🔍 (❌) 👔 📟 4️⃣0️⃣1️⃣ "⛔" 🤔 📨 `WWW-Authenticate` 🎚.
-
-💼 📨 🤝 (👆 💼), 💲 👈 🎚 🔜 `Bearer`.
-
-👆 💪 🤙 🚶 👈 ➕ 🎚 & ⚫️ 🔜 👷.
-
-✋️ ⚫️ 🚚 📥 🛠️ ⏮️ 🔧.
-
-, 📤 5️⃣📆 🧰 👈 ⌛ & ⚙️ ⚫️ (🔜 ⚖️ 🔮) & 👈 💪 ⚠ 👆 ⚖️ 👆 👩💻, 🔜 ⚖️ 🔮.
-
-👈 💰 🐩...
-
-///
-
-## 👀 ⚫️ 🎯
-
-📂 🎓 🩺: 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"
-}
-```
-
-
-
-🚥 👆 🖊 🔒 ℹ & ⏏, & ⤴️ 🔄 🎏 🛠️ 🔄, 👆 🔜 🤚 🇺🇸🔍 4️⃣0️⃣1️⃣ ❌:
-
-```JSON
-{
- "detail": "Not authenticated"
-}
-```
-
-### 🔕 👩💻
-
-🔜 🔄 ⏮️ 🔕 👩💻, 🔓 ⏮️:
-
-👩💻: `alice`
-
-🔐: `secret2`
-
-& 🔄 ⚙️ 🛠️ `GET` ⏮️ ➡ `/users/me`.
-
-👆 🔜 🤚 "🔕 👩💻" ❌, 💖:
-
-```JSON
-{
- "detail": "Inactive user"
-}
-```
-
-## 🌃
-
-👆 🔜 ✔️ 🧰 🛠️ 🏁 💂♂ ⚙️ ⚓️ 🔛 `username` & `password` 👆 🛠️.
-
-⚙️ 👫 🧰, 👆 💪 ⚒ 💂♂ ⚙️ 🔗 ⏮️ 🙆 💽 & ⏮️ 🙆 👩💻 ⚖️ 💽 🏷.
-
-🕴 ℹ ❌ 👈 ⚫️ 🚫 🤙 "🔐".
-
-⏭ 📃 👆 🔜 👀 ❔ ⚙️ 🔐 🔐 🔁 🗃 & 🥙 🤝.
diff --git a/docs/em/docs/tutorial/static-files.md b/docs/em/docs/tutorial/static-files.md
deleted file mode 100644
index 6ff6e37a9..000000000
--- a/docs/em/docs/tutorial/static-files.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# 🎻 📁
-
-👆 💪 🍦 🎻 📁 🔁 ⚪️➡️ 📁 ⚙️ `StaticFiles`.
-
-## ⚙️ `StaticFiles`
-
-* 🗄 `StaticFiles`.
-* "🗻" `StaticFiles()` 👐 🎯 ➡.
-
-{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
-
-/// note | 📡 ℹ
-
-👆 💪 ⚙️ `from starlette.staticfiles import StaticFiles`.
-
-**FastAPI** 🚚 🎏 `starlette.staticfiles` `fastapi.staticfiles` 🏪 👆, 👩💻. ✋️ ⚫️ 🤙 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-### ⚫️❔ "🗜"
-
-"🗜" ⛓ ❎ 🏁 "🔬" 🈸 🎯 ➡, 👈 ⤴️ ✊ 💅 🚚 🌐 🎧-➡.
-
-👉 🎏 ⚪️➡️ ⚙️ `APIRouter` 🗻 🈸 🍕 🔬. 🗄 & 🩺 ⚪️➡️ 👆 👑 🈸 🏆 🚫 🔌 🕳 ⚪️➡️ 🗻 🈸, ♒️.
-
-👆 💪 ✍ 🌅 🔃 👉 **🏧 👩💻 🦮**.
-
-## ℹ
-
-🥇 `"/static"` 🔗 🎧-➡ 👉 "🎧-🈸" 🔜 "🗻" 🔛. , 🙆 ➡ 👈 ▶️ ⏮️ `"/static"` 🔜 🍵 ⚫️.
-
-`directory="static"` 🔗 📛 📁 👈 🔌 👆 🎻 📁.
-
-`name="static"` 🤝 ⚫️ 📛 👈 💪 ⚙️ 🔘 **FastAPI**.
-
-🌐 👫 🔢 💪 🎏 🌘 "`static`", 🔆 👫 ⏮️ 💪 & 🎯 ℹ 👆 👍 🈸.
-
-## 🌅 ℹ
-
-🌖 ℹ & 🎛 ✅ 💃 🩺 🔃 🎻 📁.
diff --git a/docs/em/docs/tutorial/testing.md b/docs/em/docs/tutorial/testing.md
deleted file mode 100644
index cb4a1ca21..000000000
--- a/docs/em/docs/tutorial/testing.md
+++ /dev/null
@@ -1,185 +0,0 @@
-# 🔬
-
-👏 💃, 🔬 **FastAPI** 🈸 ⏩ & 😌.
-
-⚫️ ⚓️ 🔛 🇸🇲, ❔ 🔄 🏗 ⚓️ 🔛 📨, ⚫️ 📶 😰 & 🏋️.
-
-⏮️ ⚫️, 👆 💪 ⚙️ ✳ 🔗 ⏮️ **FastAPI**.
-
-## ⚙️ `TestClient`
-
-/// info
-
-⚙️ `TestClient`, 🥇 ❎ `httpx`.
-
-🤶 Ⓜ. `pip install httpx`.
-
-///
-
-🗄 `TestClient`.
-
-✍ `TestClient` 🚶♀️ 👆 **FastAPI** 🈸 ⚫️.
-
-✍ 🔢 ⏮️ 📛 👈 ▶️ ⏮️ `test_` (👉 🐩 `pytest` 🏛).
-
-⚙️ `TestClient` 🎚 🎏 🌌 👆 ⏮️ `httpx`.
-
-✍ 🙅 `assert` 📄 ⏮️ 🐩 🐍 🧬 👈 👆 💪 ✅ (🔄, 🐩 `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` 🏪 👆, 👩💻. ✋️ ⚫️ 👟 🔗 ⚪️➡️ 💃.
-
-///
-
-/// tip
-
-🚥 👆 💚 🤙 `async` 🔢 👆 💯 ↖️ ⚪️➡️ 📨 📨 👆 FastAPI 🈸 (✅ 🔁 💽 🔢), ✔️ 👀 [🔁 💯](../advanced/async-tests.md){.internal-link target=_blank} 🏧 🔰.
-
-///
-
-## 🎏 💯
-
-🎰 🈸, 👆 🎲 🔜 ✔️ 👆 💯 🎏 📁.
-
-& 👆 **FastAPI** 🈸 5️⃣📆 ✍ 📚 📁/🕹, ♒️.
-
-### **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` ⏮️ 👆 💯. ⚫️ 💪 🖖 🔛 🎏 🐍 📦 (🎏 📁 ⏮️ `__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** 📱 ✔️ 🎏 **➡ 🛠️**.
-
-⚫️ ✔️ `GET` 🛠️ 👈 💪 📨 ❌.
-
-⚫️ ✔️ `POST` 🛠️ 👈 💪 📨 📚 ❌.
-
-👯♂️ *➡ 🛠️* 🚚 `X-Token` 🎚.
-
-{* ../../docs_src/app_testing/app_b/main.py *}
-
-### ↔ 🔬 📁
-
-👆 💪 ⤴️ ℹ `test_main.py` ⏮️ ↔ 💯:
-
-{* ../../docs_src/app_testing/app_b/test_main.py *}
-
-🕐❔ 👆 💪 👩💻 🚶♀️ ℹ 📨 & 👆 🚫 💭 ❔, 👆 💪 🔎 (🇺🇸🔍) ❔ ⚫️ `httpx`, ⚖️ ❔ ⚫️ ⏮️ `requests`, 🇸🇲 🔧 ⚓️ 🔛 📨' 🔧.
-
-⤴️ 👆 🎏 👆 💯.
-
-🤶 Ⓜ.:
-
-* 🚶♀️ *➡* ⚖️ *🔢* 🔢, 🚮 ⚫️ 📛 ⚫️.
-* 🚶♀️ 🎻 💪, 🚶♀️ 🐍 🎚 (✅ `dict`) 🔢 `json`.
-* 🚥 👆 💪 📨 *📨 💽* ↩️ 🎻, ⚙️ `data` 🔢 ↩️.
-* 🚶♀️ *🎚*, ⚙️ `dict` `headers` 🔢.
-* *🍪*, `dict` `cookies` 🔢.
-
-🌖 ℹ 🔃 ❔ 🚶♀️ 💽 👩💻 (⚙️ `httpx` ⚖️ `TestClient`) ✅ 🇸🇲 🧾.
-
-/// info
-
-🗒 👈 `TestClient` 📨 💽 👈 💪 🗜 🎻, 🚫 Pydantic 🏷.
-
-🚥 👆 ✔️ Pydantic 🏷 👆 💯 & 👆 💚 📨 🚮 💽 🈸 ⏮️ 🔬, 👆 💪 ⚙️ `jsonable_encoder` 🔬 [🎻 🔗 🔢](encoder.md){.internal-link target=_blank}.
-
-///
-
-## 🏃 ⚫️
-
-⏮️ 👈, 👆 💪 ❎ `pytest`:
-
-+With great-* Do not change the paths in links to images, code files, Markdown documents. +Avoid inadvertently doing harm. -* However, when a Markdown document is translated, the `#hash-parts` in links to its headings may change. Update these links if possible. - * Search for such links in the translated document using the regex `#[^# ]`. - * Search in all documents already translated into your language for `your-translated-document.md`. For example VS Code has an option "Edit" -> "Find in Files". - * When translating a document, do not "pre-translate" `#hash-parts` that link to headings in untranslated documents. +You have amazing tools at hand, use them wisely to help effectively. diff --git a/docs/en/docs/css/custom.css b/docs/en/docs/css/custom.css index a38df772f..87111ff64 100644 --- a/docs/en/docs/css/custom.css +++ b/docs/en/docs/css/custom.css @@ -1,3 +1,18 @@ +/* Fira Code, including characters used by Rich output, like the "heavy right-pointing angle bracket ornament", not included in Google Fonts */ +@import url(https://cdn.jsdelivr.net/npm/firacode@6.2.0/distr/fira_code.css); +/* Noto Color Emoji for emoji support with the same font everywhere */ +@import url(https://fonts.googleapis.com/css2?family=Noto+Color+Emoji&display=swap); + +/* Override default code font in Material for MkDocs to Fira Code */ +:root { + --md-code-font: "Fira Code", monospace, "Noto Color Emoji"; +} + +/* Override default regular font in Material for MkDocs to include Noto Color Emoji */ +:root { + --md-text-font: "Roboto", "Noto Color Emoji"; +} + .termynal-comment { color: #4a968f; font-style: italic; diff --git a/docs/en/docs/css/termynal.css b/docs/en/docs/css/termynal.css index 8534f9102..a2564e286 100644 --- a/docs/en/docs/css/termynal.css +++ b/docs/en/docs/css/termynal.css @@ -20,7 +20,7 @@ /* font-size: 18px; */ font-size: 15px; /* font-family: 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; */ - font-family: 'Roboto Mono', 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; + font-family: var(--md-code-font-family), 'Roboto Mono', 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; border-radius: 4px; padding: 75px 45px 35px; position: relative; diff --git a/docs/en/docs/deployment/cloud.md b/docs/en/docs/deployment/cloud.md index c88c4b51a..4f5c23e4b 100644 --- a/docs/en/docs/deployment/cloud.md +++ b/docs/en/docs/deployment/cloud.md @@ -4,13 +4,21 @@ You can use virtually **any cloud provider** to deploy your FastAPI application. In most of the cases, the main cloud providers have guides to deploy FastAPI with them. -## Cloud Providers - Sponsors { #cloud-providers-sponsors } +## FastAPI Cloud { #fastapi-cloud } + +**FastAPI Cloud** is built by the same author and team behind **FastAPI**. + +It streamlines the process of **building**, **deploying**, and **accessing** an API with minimal effort. -Some cloud 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**. +It brings the same **developer experience** of building apps with FastAPI to **deploying** them to the cloud. 🎉 + +FastAPI Cloud is the primary sponsor and funding provider for the *FastAPI and friends* open source projects. ✨ + +## Cloud Providers - Sponsors { #cloud-providers-sponsors } -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. 🙇 +Some other cloud providers ✨ [**sponsor FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ too. 🙇 -You might want to try their services and follow their guides: +You might also want to consider them to follow their guides and try their services: * Render * Railway diff --git a/docs/en/docs/deployment/fastapicloud.md b/docs/en/docs/deployment/fastapicloud.md new file mode 100644 index 000000000..b0889974f --- /dev/null +++ b/docs/en/docs/deployment/fastapicloud.md @@ -0,0 +1,65 @@ +# FastAPI Cloud { #fastapi-cloud } + +You can deploy your FastAPI app to FastAPI Cloud with **one command**, go and join the waiting list if you haven't. 🚀 + +## Login { #login } + +Make sure you already have a **FastAPI Cloud** account (we invited you from the waiting list 😉). + +Then log in: + +powertools comes great responsibility. +
+
## **Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }
@@ -123,7 +135,7 @@ If you are building a CLI app to be
FastAPI stands on the shoulders of giants:
-* Starlette for the web parts.
+* Starlette for the web parts.
* Pydantic for the data parts.
## Installation { #installation }
@@ -229,7 +241,7 @@ INFO: Application startup complete.
fastapi dev main.py...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.
+* 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[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to FastAPI Cloud.
diff --git a/docs/en/docs/js/custom.js b/docs/en/docs/js/custom.js
index 48e95901d..be326d302 100644
--- a/docs/en/docs/js/custom.js
+++ b/docs/en/docs/js/custom.js
@@ -81,8 +81,14 @@ function setupTermynal() {
}
}
saveBuffer();
+ const inputCommands = useLines
+ .filter(line => line.type === "input")
+ .map(line => line.value)
+ .join("\n");
+ node.textContent = inputCommands;
const div = document.createElement("div");
- node.replaceWith(div);
+ node.style.display = "none";
+ node.after(div);
const termynal = new Termynal(div, {
lineData: useLines,
noInit: true,
diff --git a/docs/en/docs/management-tasks.md b/docs/en/docs/management-tasks.md
index 05cd5d27d..fc6e1eb28 100644
--- a/docs/en/docs/management-tasks.md
+++ b/docs/en/docs/management-tasks.md
@@ -74,7 +74,7 @@ Make sure you use a supported label from the `translate.yml`.
-* The title is correct following the instructions above.
-* It has the labels `lang-all` and `lang-{lang code}`.
-* The PR changes only one Markdown file adding a translation.
- * Or in some cases, at most two files, if they are small, for the same language, and people reviewed them.
- * If it's the first translation for that language, it will have additional `mkdocs.yml` files, for those cases follow the instructions below.
-* The PR doesn't add any additional or extraneous files.
-* The translation seems to have a similar structure as the original English file.
-* The translation doesn't seem to change the original content, for example with obvious additional documentation sections.
-* The translation doesn't use different Markdown structures, for example adding HTML tags when the original didn't have them.
-* The "admonition" sections, like `tip`, `info`, etc. are not changed or translated. For example:
-
-```
-/// tip
-
-This is a tip.
-
-///
-
-```
-
-looks like this:
-
-/// tip
-
-This is a tip.
-
-///
-
-...it could be translated as:
-
-```
-/// tip
-
-Esto es un consejo.
-
-///
-
-```
-
-...but needs to keep the exact `tip` keyword. If it was translated to `consejo`, like:
-
-```
-/// consejo
-
-Esto es un consejo.
-
-///
-
-```
-
-it would change the style to the default one, it would look like:
-
-/// consejo
-
-Esto es un consejo.
-
-///
-
-Those don't have to be translated, but if they are, they need to be written as:
+For these language translation PRs, confirm that:
-```
-/// tip | consejo
-
-Esto es un consejo.
-
-///
-
-```
-
-Which looks like:
-
-/// tip | consejo
-
-Esto es un consejo.
-
-///
-
-## First Translation PR
-
-When there's a first translation for a language, it will have a `docs/{lang code}/docs/index.md` translated file and a `docs/{lang code}/mkdocs.yml`.
-
-For example, for Bosnian, it would be:
-
-* `docs/bs/docs/index.md`
-* `docs/bs/mkdocs.yml`
-
-The `mkdocs.yml` file will have only the following content:
-
-```YAML
-INHERIT: ../en/mkdocs.yml
-```
-
-The language code would normally be in the ISO 639-1 list of language codes.
-
-In any case, the language code should be in the file docs/language_names.yml.
-
-There won't be yet a label for the language code, for example, if it was Bosnian, there wouldn't be a `lang-bs`. Before creating the label and adding it to the PR, create the GitHub Discussion:
-
-* Go to the Translations GitHub Discussions
-* Create a new discussion with the title `Bosnian Translations` (or the language name in English)
-* A description of:
-
-```Markdown
-## Bosnian translations
-
-This is the issue to track translations of the docs to Bosnian. 🚀
-
-Here are the [PRs to review with the label `lang-bs`](https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Alang-bs+label%3A%22awaiting-review%22). 🤓
-```
-
-Update "Bosnian" with the new language.
-
-And update the search link to point to the new language label that will be created, like `lang-bs`.
-
-Create and add the label to that new Discussion just created, like `lang-bs`.
+* The PR was automated (authored by @tiangolo), not made by another user.
+* It has the labels `lang-all` and `lang-{lang code}`.
+* If the PR is approved by at least one native speaker, you can merge it.
-Then go back to the PR, and add the label, like `lang-bs`, and `lang-all` and `awaiting-review`.
+## Review PRs
-Now the GitHub action will automatically detect the label `lang-bs` and will post in that Discussion that this PR is waiting to be reviewed.
+* If a PR doesn't explain what it does or why, if it seems like it could be useful, ask for more information. Otherwise, feel free to close it.
-## Review PRs
+* If a PR seems to be spam, meaningless, only to change statistics (to appear as "contributor") or similar, you can simply mark it as `invalid`, and it will be automatically closed.
-If a PR doesn't explain what it does or why, ask for more information.
+* If a PR seems to be AI generated, and seems like reviewing it would take more time from you than the time it took to write the prompt, mark it as `maybe-ai`, and it will be automatically closed.
-A PR should have a specific use case that it is solving.
+* A PR should have a specific use case that it is solving.
* If the PR is for a feature, it should have docs.
* Unless it's a feature we want to discourage, like support for a corner case that we don't want users to use.
* The docs should include a source example file, not write Python directly in Markdown.
-* If the source example(s) file can have different syntax for Python 3.8, 3.9, 3.10, there should be different versions of the file, and they should be shown in tabs in the docs.
+* If the source example(s) file can have different syntax for different Python versions, there should be different versions of the file, and they should be shown in tabs in the docs.
* There should be tests testing the source example.
* Before the PR is applied, the new tests should fail.
* After applying the PR, the new tests should pass.
@@ -254,27 +144,12 @@ Every month, a GitHub Action updates the FastAPI People data. Those PRs look lik
If the tests are passing, you can merge it right away.
-## External Links PRs
-
-When people add external links they edit this file external_links.yml.
-
-* Make sure the new link is in the correct category (e.g. "Podcasts") and language (e.g. "Japanese").
-* A new link should be at the top of its list.
-* The link URL should work (it should not return a 404).
-* The content of the link should be about FastAPI.
-* The new addition should have these fields:
- * `author`: The name of the author.
- * `link`: The URL with the content.
- * `title`: The title of the link (the title of the article, podcast, etc).
-
-After checking all these things and ensuring the PR has the right labels, you can merge it.
-
## Dependabot PRs
Dependabot will create PRs to update dependencies for several things, and those PRs all look similar, but some are way more delicate than others.
-* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml`, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed.
-* If the PR updates one of the internal dependencies, for example it's modifying `requirements.txt` files, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎
+* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml` in the main dependencies, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed.
+* If the PR updates one of the internal dependencies, for example the group `dev` in `pyproject.toml`, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎
## Mark GitHub Discussions Answers
diff --git a/docs/en/docs/project-generation.md b/docs/en/docs/project-generation.md
index 44f058b90..610d23ccb 100644
--- a/docs/en/docs/project-generation.md
+++ b/docs/en/docs/project-generation.md
@@ -9,18 +9,18 @@ GitHub Repository: Concatenates them with a space in the middle.
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
### Edit it { #edit-it }
@@ -78,7 +78,7 @@ That's it.
Those are the "type hints":
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
That is not the same as declaring default values like would be with:
@@ -106,7 +106,7 @@ With that, you can scroll, seeing the options, until you find the one that "ring
Check this function, it already has type hints:
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
Because the editor knows the types of the variables, you don't only get completion, you also get error checks:
@@ -114,7 +114,7 @@ Because the editor knows the types of the variables, you don't only get completi
Now you know that you have to fix it, convert `age` to a string with `str(age)`:
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
## Declaring types { #declaring-types }
@@ -133,7 +133,7 @@ You can use, for example:
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
### Generic types with type parameters { #generic-types-with-type-parameters }
@@ -161,56 +161,24 @@ If you can use the **latest versions of Python**, use the examples for the lates
For example, let's define a variable to be a `list` of `str`.
-//// tab | Python 3.9+
-
Declare the variable, with the same colon (`:`) syntax.
As the type, put `list`.
As the list is a type that contains some internal types, you put them in square brackets:
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-From `typing`, import `List` (with a capital `L`):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-Declare the variable, with the same colon (`:`) syntax.
-
-As the type, put the `List` that you imported from `typing`.
-
-As the list is a type that contains some internal types, you put them in square brackets:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
/// info
Those internal types in the square brackets are called "type parameters".
-In this case, `str` is the type parameter passed to `List` (or `list` in Python 3.9 and above).
+In this case, `str` is the type parameter passed to `list`.
///
That means: "the variable `items` is a `list`, and each of the items in this list is a `str`".
-/// tip
-
-If you use Python 3.9 or above, you don't have to import `List` from `typing`, you can use the same regular `list` type instead.
-
-///
-
By doing that, your editor can provide support even while processing items from the list:
@@ -225,21 +193,7 @@ And still, the editor knows it is a `str`, and provides support for that.
You would do the same to declare `tuple`s and `set`s:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
This means:
@@ -254,21 +208,7 @@ The first type parameter is for the keys of the `dict`.
The second type parameter is for the values of the `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_py39.py hl[1] *}
This means:
@@ -292,10 +232,10 @@ In Python 3.10 there's also a **new syntax** where you can put the possible type
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
```
////
@@ -309,7 +249,7 @@ You can declare that a value could have a type, like `str`, but that it could al
In Python 3.6 and above (including Python 3.10) you can declare it by importing and using `Optional` from the `typing` module.
```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009_py39.py!}
```
Using `Optional[str]` instead of just `str` will let the editor help you detect errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.
@@ -326,18 +266,18 @@ This also means that in Python 3.10, you can use `Something | None`:
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
////
-//// tab | Python 3.8+ alternative
+//// tab | Python 3.9+ alternative
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
```
////
@@ -357,7 +297,7 @@ It's just about the words and names. But those words can affect how you and your
As an example, let's take this function:
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *}
The parameter `name` is defined as `Optional[str]`, but it is **not optional**, you cannot call the function without the parameter:
@@ -390,10 +330,10 @@ You can use the same builtin types as generics (with square brackets and types i
* `set`
* `dict`
-And the same as with Python 3.8, from the `typing` module:
+And the same as with previous Python versions, from the `typing` module:
* `Union`
-* `Optional` (the same as with Python 3.8)
+* `Optional`
* ...and others.
In Python 3.10, as an alternative to using the generics `Union` and `Optional`, you can use the vertical bar (`|`) to declare unions of types, that's a lot better and simpler.
@@ -409,7 +349,7 @@ You can use the same builtin types as generics (with square brackets and types i
* `set`
* `dict`
-And the same as with Python 3.8, from the `typing` module:
+And generics from the `typing` module:
* `Union`
* `Optional`
@@ -417,29 +357,17 @@ And the same as with Python 3.8, from the `typing` module:
////
-//// tab | Python 3.8+
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...and others.
-
-////
-
### Classes as types { #classes-as-types }
You can also declare a class as the type of a variable.
Let's say you have a class `Person`, with a name:
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
Then you can declare a variable to be of type `Person`:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
And then, again, you get all the editor support:
@@ -463,29 +391,7 @@ And you get all the editor support with that resulting object.
An example from the official Pydantic docs:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial011_py310.py *}
/// info
@@ -507,27 +413,9 @@ Pydantic has a special behavior when you use `Optional` or `Union[Something, Non
Python also has a feature that allows putting **additional metadata** in these type hints using `Annotated`.
-//// tab | Python 3.9+
-
-In Python 3.9, `Annotated` is part of the standard library, so you can import it from `typing`.
+Since Python 3.9, `Annotated` is a part of the standard library, so you can import it from `typing`.
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-In versions below Python 3.9, you import `Annotated` from `typing_extensions`.
-
-It will already be installed with **FastAPI**.
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013.py!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
Python itself doesn't do anything with this `Annotated`. And for editors and other tools, the type is still `str`.
diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md
index 29112649c..1fefe908b 100644
--- a/docs/en/docs/release-notes.md
+++ b/docs/en/docs/release-notes.md
@@ -7,6 +7,606 @@ hide:
## Latest Changes
+### Docs
+
+* 🐛 Fix copy button in custom.js. PR [#14722](https://github.com/fastapi/fastapi/pull/14722) by [@fcharrier](https://github.com/fcharrier).
+* 📝 Add contribution instructions about LLM generated code and comments and automated tools for PRs. PR [#14706](https://github.com/fastapi/fastapi/pull/14706) by [@tiangolo](https://github.com/tiangolo).
+* 📝 Update docs for management tasks. PR [#14705](https://github.com/fastapi/fastapi/pull/14705) by [@tiangolo](https://github.com/tiangolo).
+* 📝 Update docs about managing translations. PR [#14704](https://github.com/fastapi/fastapi/pull/14704) by [@tiangolo](https://github.com/tiangolo).
+* 📝 Update docs for contributing with translations. PR [#14701](https://github.com/fastapi/fastapi/pull/14701) by [@tiangolo](https://github.com/tiangolo).
+* 📝 Specify language code for code block. PR [#14656](https://github.com/fastapi/fastapi/pull/14656) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+### Translations
+
+* 🌐 Update `llm-prompt.md` for Korean language. PR [#14763](https://github.com/fastapi/fastapi/pull/14763) by [@seuthootDev](https://github.com/seuthootDev).
+* 🌐 Update translations for ko (update outdated, found by fixer tool). PR [#14738](https://github.com/fastapi/fastapi/pull/14738) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Update translations for de (update-outdated). PR [#14690](https://github.com/fastapi/fastapi/pull/14690) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update LLM prompt for Russian translations. PR [#14733](https://github.com/fastapi/fastapi/pull/14733) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Update translations for ru (update-outdated). PR [#14693](https://github.com/fastapi/fastapi/pull/14693) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for pt (update-outdated). PR [#14724](https://github.com/fastapi/fastapi/pull/14724) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update Korean LLM prompt. PR [#14740](https://github.com/fastapi/fastapi/pull/14740) by [@hard-coders](https://github.com/hard-coders).
+* 🌐 Improve LLM prompt for Turkish translations. PR [#14728](https://github.com/fastapi/fastapi/pull/14728) by [@Kadermiyanyedi](https://github.com/Kadermiyanyedi).
+* 🌐 Update portuguese llm-prompt.md. PR [#14702](https://github.com/fastapi/fastapi/pull/14702) by [@ceb10n](https://github.com/ceb10n).
+* 🌐 Update LLM prompt instructions file for French. PR [#14618](https://github.com/fastapi/fastapi/pull/14618) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for ko (add-missing). PR [#14699](https://github.com/fastapi/fastapi/pull/14699) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for ko (update-outdated). PR [#14589](https://github.com/fastapi/fastapi/pull/14589) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for uk (update-outdated). PR [#14587](https://github.com/fastapi/fastapi/pull/14587) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for es (update-outdated). PR [#14686](https://github.com/fastapi/fastapi/pull/14686) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add LLM prompt file for Turkish, generated from the existing translations. PR [#14547](https://github.com/fastapi/fastapi/pull/14547) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add LLM prompt file for Traditional Chinese, generated from the existing translations. PR [#14550](https://github.com/fastapi/fastapi/pull/14550) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add LLM prompt file for Simplified Chinese, generated from the existing translations. PR [#14549](https://github.com/fastapi/fastapi/pull/14549) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* 🔧 Ensure that an edit to `uv.lock` gets the `internal` label. PR [#14759](https://github.com/fastapi/fastapi/pull/14759) by [@svlandeg](https://github.com/svlandeg).
+* 🔧 Update sponsors: remove Requestly. PR [#14735](https://github.com/fastapi/fastapi/pull/14735) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Update sponsors, LambdaTest changes to TestMu AI. PR [#14734](https://github.com/fastapi/fastapi/pull/14734) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump actions/cache from 4 to 5. PR [#14511](https://github.com/fastapi/fastapi/pull/14511) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump actions/upload-artifact from 5 to 6. PR [#14525](https://github.com/fastapi/fastapi/pull/14525) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump actions/download-artifact from 6 to 7. PR [#14526](https://github.com/fastapi/fastapi/pull/14526) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* 👷 Tweak CI input names. PR [#14688](https://github.com/fastapi/fastapi/pull/14688) by [@tiangolo](https://github.com/tiangolo).
+* 🔨 Refactor translation script to allow committing in place. PR [#14687](https://github.com/fastapi/fastapi/pull/14687) by [@tiangolo](https://github.com/tiangolo).
+* 🐛 Fix translation script path. PR [#14685](https://github.com/fastapi/fastapi/pull/14685) by [@tiangolo](https://github.com/tiangolo).
+* ✅ Enable tests in CI for scripts. PR [#14684](https://github.com/fastapi/fastapi/pull/14684) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add pre-commit local script to fix language translations. PR [#14683](https://github.com/fastapi/fastapi/pull/14683) by [@tiangolo](https://github.com/tiangolo).
+* ⬆️ Migrate to uv. PR [#14676](https://github.com/fastapi/fastapi/pull/14676) by [@DoctorJohn](https://github.com/DoctorJohn).
+* 🔨 Add LLM translations tool fixer. PR [#14652](https://github.com/fastapi/fastapi/pull/14652) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 👥 Update FastAPI People - Sponsors. PR [#14626](https://github.com/fastapi/fastapi/pull/14626) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI GitHub topic repositories. PR [#14630](https://github.com/fastapi/fastapi/pull/14630) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI People - Contributors and Translators. PR [#14625](https://github.com/fastapi/fastapi/pull/14625) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translation prompts. PR [#14619](https://github.com/fastapi/fastapi/pull/14619) by [@tiangolo](https://github.com/tiangolo).
+* 🔨 Update LLM translation script to guide reviewers to change the prompt. PR [#14614](https://github.com/fastapi/fastapi/pull/14614) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Do not run translations on cron while finishing updating existing languages. PR [#14613](https://github.com/fastapi/fastapi/pull/14613) by [@tiangolo](https://github.com/tiangolo).
+* 🔥 Remove test variants for Pydantic v1 in test_request_params. PR [#14612](https://github.com/fastapi/fastapi/pull/14612) by [@tiangolo](https://github.com/tiangolo).
+* 🔥 Remove Pydantic v1 specific test variants. PR [#14611](https://github.com/fastapi/fastapi/pull/14611) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.128.0
+
+### Breaking Changes
+
+* ➖ Drop support for `pydantic.v1`. PR [#14609](https://github.com/fastapi/fastapi/pull/14609) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* ✅ Run performance tests only on Pydantic v2. PR [#14608](https://github.com/fastapi/fastapi/pull/14608) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.127.1
+
+### Refactors
+
+* 🔊 Add a custom `FastAPIDeprecationWarning`. PR [#14605](https://github.com/fastapi/fastapi/pull/14605) by [@tiangolo](https://github.com/tiangolo).
+
+### Docs
+
+* 📝 Add documentary to website. PR [#14600](https://github.com/fastapi/fastapi/pull/14600) by [@tiangolo](https://github.com/tiangolo).
+
+### Translations
+
+* 🌐 Update translations for de (update-outdated). PR [#14602](https://github.com/fastapi/fastapi/pull/14602) by [@nilslindemann](https://github.com/nilslindemann).
+* 🌐 Update translations for de (update-outdated). PR [#14581](https://github.com/fastapi/fastapi/pull/14581) by [@nilslindemann](https://github.com/nilslindemann).
+
+### Internal
+
+* 🔧 Update pre-commit to use local Ruff instead of hook. PR [#14604](https://github.com/fastapi/fastapi/pull/14604) by [@tiangolo](https://github.com/tiangolo).
+* ✅ Add missing tests for code examples. PR [#14569](https://github.com/fastapi/fastapi/pull/14569) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 👷 Remove `lint` job from `test` CI workflow. PR [#14593](https://github.com/fastapi/fastapi/pull/14593) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 👷 Update secrets check. PR [#14592](https://github.com/fastapi/fastapi/pull/14592) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Run CodSpeed tests in parallel to other tests to speed up CI. PR [#14586](https://github.com/fastapi/fastapi/pull/14586) by [@tiangolo](https://github.com/tiangolo).
+* 🔨 Update scripts and pre-commit to autofix files. PR [#14585](https://github.com/fastapi/fastapi/pull/14585) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.127.0
+
+### Breaking Changes
+
+* 🔊 Add deprecation warnings when using `pydantic.v1`. PR [#14583](https://github.com/fastapi/fastapi/pull/14583) by [@tiangolo](https://github.com/tiangolo).
+
+### Translations
+
+* 🔧 Add LLM prompt file for Korean, generated from the existing translations. PR [#14546](https://github.com/fastapi/fastapi/pull/14546) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add LLM prompt file for Japanese, generated from the existing translations. PR [#14545](https://github.com/fastapi/fastapi/pull/14545) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* ⬆️ Upgrade OpenAI model for translations to gpt-5.2. PR [#14579](https://github.com/fastapi/fastapi/pull/14579) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.126.0
+
+### Upgrades
+
+* ➖ Drop support for Pydantic v1, keeping short temporary support for Pydantic v2's `pydantic.v1`. PR [#14575](https://github.com/fastapi/fastapi/pull/14575) by [@tiangolo](https://github.com/tiangolo).
+ * The minimum version of Pydantic installed is now `pydantic >=2.7.0`.
+ * The `standard` dependencies now include `pydantic-settings >=2.0.0` and `pydantic-extra-types >=2.0.0`.
+
+### Docs
+
+* 📝 Fix duplicated variable in `docs_src/python_types/tutorial005_py39.py`. PR [#14565](https://github.com/fastapi/fastapi/pull/14565) by [@paras-verma7454](https://github.com/paras-verma7454).
+
+### Translations
+
+* 🔧 Add LLM prompt file for Ukrainian, generated from the existing translations. PR [#14548](https://github.com/fastapi/fastapi/pull/14548) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* 🔧 Tweak pre-commit to allow committing release-notes. PR [#14577](https://github.com/fastapi/fastapi/pull/14577) by [@tiangolo](https://github.com/tiangolo).
+* ⬆️ Use prek as a pre-commit alternative. PR [#14572](https://github.com/fastapi/fastapi/pull/14572) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Add performance tests with CodSpeed. PR [#14558](https://github.com/fastapi/fastapi/pull/14558) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.125.0
+
+### Breaking Changes
+
+* 🔧 Drop support for Python 3.8. PR [#14563](https://github.com/fastapi/fastapi/pull/14563) by [@tiangolo](https://github.com/tiangolo).
+ * This would actually not be a _breaking_ change as no code would really break. Any Python 3.8 installer would just refuse to install the latest version of FastAPI and would only install 0.124.4. Only marking it as a "breaking change" to make it visible.
+
+### Refactors
+
+* ♻️ Upgrade internal syntax to Python 3.9+ 🎉. PR [#14564](https://github.com/fastapi/fastapi/pull/14564) by [@tiangolo](https://github.com/tiangolo).
+
+### Docs
+
+* ⚰️ Remove Python 3.8 from CI and remove Python 3.8 examples from source docs. PR [#14559](https://github.com/fastapi/fastapi/pull/14559) by [@YuriiMotov](https://github.com/YuriiMotov) and [@tiangolo](https://github.com/tiangolo).
+
+### Translations
+
+* 🌐 Update translations for pt (add-missing). PR [#14539](https://github.com/fastapi/fastapi/pull/14539) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Add LLM prompt file for French, generated from the existing French docs. PR [#14544](https://github.com/fastapi/fastapi/pull/14544) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Sync Portuguese docs (pages found with script). PR [#14554](https://github.com/fastapi/fastapi/pull/14554) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Sync Spanish docs (outdated pages found with script). PR [#14553](https://github.com/fastapi/fastapi/pull/14553) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Sync German docs. PR [#14519](https://github.com/fastapi/fastapi/pull/14519) by [@nilslindemann](https://github.com/nilslindemann).
+* 🔥 Remove inactive/scarce translations to Vietnamese. PR [#14543](https://github.com/fastapi/fastapi/pull/14543) by [@tiangolo](https://github.com/tiangolo).
+* 🔥 Remove inactive/scarce translations to Persian. PR [#14542](https://github.com/fastapi/fastapi/pull/14542) by [@tiangolo](https://github.com/tiangolo).
+* 🔥 Remove translation to emoji to simplify the new setup with LLM autotranslations. PR [#14541](https://github.com/fastapi/fastapi/pull/14541) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for pt (update-outdated). PR [#14537](https://github.com/fastapi/fastapi/pull/14537) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for es (update-outdated). PR [#14532](https://github.com/fastapi/fastapi/pull/14532) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Update translations for es (add-missing). PR [#14533](https://github.com/fastapi/fastapi/pull/14533) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Remove translations for removed docs. PR [#14516](https://github.com/fastapi/fastapi/pull/14516) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* ⬆ Bump `markdown-include-variants` from 0.0.7 to 0.0.8. PR [#14556](https://github.com/fastapi/fastapi/pull/14556) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🔧 Temporarily disable translations still in progress, being migrated to the new LLM setup. PR [#14555](https://github.com/fastapi/fastapi/pull/14555) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🔧 Update test workflow config, remove commented code. PR [#14540](https://github.com/fastapi/fastapi/pull/14540) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Configure coverage, error on main tests, don't wait for Smokeshow. PR [#14536](https://github.com/fastapi/fastapi/pull/14536) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Run Smokeshow always, even on test failures. PR [#14538](https://github.com/fastapi/fastapi/pull/14538) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Make Pydantic versions customizable in CI. PR [#14535](https://github.com/fastapi/fastapi/pull/14535) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Fix checkout GitHub Action fetch-depth for LLM translations, enable cron monthly. PR [#14531](https://github.com/fastapi/fastapi/pull/14531) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Fix Typer command for CI LLM translations. PR [#14530](https://github.com/fastapi/fastapi/pull/14530) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update LLM translation CI, add language matrix and extra commands, prepare for scheduled run. PR [#14529](https://github.com/fastapi/fastapi/pull/14529) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update github-actions user for GitHub Actions workflows. PR [#14528](https://github.com/fastapi/fastapi/pull/14528) by [@tiangolo](https://github.com/tiangolo).
+* ➕ Add requirements for translations. PR [#14515](https://github.com/fastapi/fastapi/pull/14515) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.124.4
+
+### Fixes
+
+* 🐛 Fix parameter aliases. PR [#14371](https://github.com/fastapi/fastapi/pull/14371) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.124.3
+
+### Fixes
+
+* 🐛 Fix support for tagged union with discriminator inside of `Annotated` with `Body()`. PR [#14512](https://github.com/fastapi/fastapi/pull/14512) by [@tiangolo](https://github.com/tiangolo).
+
+### Refactors
+
+* ✅ Add set of tests for request parameters and alias. PR [#14358](https://github.com/fastapi/fastapi/pull/14358) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+### Docs
+
+* 📝 Tweak links format. PR [#14505](https://github.com/fastapi/fastapi/pull/14505) by [@tiangolo](https://github.com/tiangolo).
+* 📝 Update docs about re-raising validation errors, do not include string as is to not leak information. PR [#14487](https://github.com/fastapi/fastapi/pull/14487) by [@tiangolo](https://github.com/tiangolo).
+* 🔥 Remove external links section. PR [#14486](https://github.com/fastapi/fastapi/pull/14486) by [@tiangolo](https://github.com/tiangolo).
+
+### Translations
+
+* 🌐 Sync Russian docs. PR [#14509](https://github.com/fastapi/fastapi/pull/14509) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Sync German docs. PR [#14488](https://github.com/fastapi/fastapi/pull/14488) by [@nilslindemann](https://github.com/nilslindemann).
+
+### Internal
+
+* 👷 Tweak coverage to not pass Smokeshow max file size limit. PR [#14507](https://github.com/fastapi/fastapi/pull/14507) by [@tiangolo](https://github.com/tiangolo).
+* ✅ Expand test matrix to include Windows and MacOS. PR [#14171](https://github.com/fastapi/fastapi/pull/14171) by [@svlandeg](https://github.com/svlandeg).
+
+## 0.124.2
+
+### Fixes
+
+* 🐛 Fix support for `if TYPE_CHECKING`, non-evaluated stringified annotations. PR [#14485](https://github.com/fastapi/fastapi/pull/14485) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.124.1
+
+### Fixes
+
+* 🐛 Fix handling arbitrary types when using `arbitrary_types_allowed=True`. PR [#14482](https://github.com/fastapi/fastapi/pull/14482) by [@tiangolo](https://github.com/tiangolo).
+
+### Docs
+
+* 📝 Add variants for code examples in "Advanced User Guide". PR [#14413](https://github.com/fastapi/fastapi/pull/14413) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 📝 Update tech stack in project generation docs. PR [#14472](https://github.com/fastapi/fastapi/pull/14472) by [@alejsdev](https://github.com/alejsdev).
+
+### Internal
+
+* ✅ Add test for Pydantic v2, dataclasses, UUID, and `__annotations__`. PR [#14477](https://github.com/fastapi/fastapi/pull/14477) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.124.0
+
+### Features
+
+* 🚸 Improve tracebacks by adding endpoint metadata. PR [#14306](https://github.com/fastapi/fastapi/pull/14306) by [@savannahostrowski](https://github.com/savannahostrowski).
+
+### Internal
+
+* ✏️ Fix typo in `scripts/mkdocs_hooks.py`. PR [#14457](https://github.com/fastapi/fastapi/pull/14457) by [@yujiteshima](https://github.com/yujiteshima).
+
+## 0.123.10
+
+### Fixes
+
+* 🐛 Fix using class (not instance) dependency that has `__call__` method. PR [#14458](https://github.com/fastapi/fastapi/pull/14458) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🐛 Fix `separate_input_output_schemas=False` with `computed_field`. PR [#14453](https://github.com/fastapi/fastapi/pull/14453) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.123.9
+
+### Fixes
+
+* 🐛 Fix OAuth2 scopes in OpenAPI in extra corner cases, parent dependency with scopes, sub-dependency security scheme without scopes. PR [#14459](https://github.com/fastapi/fastapi/pull/14459) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.123.8
+
+### Fixes
+
+* 🐛 Fix OpenAPI security scheme OAuth2 scopes declaration, deduplicate security schemes with different scopes. PR [#14455](https://github.com/fastapi/fastapi/pull/14455) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.123.7
+
+### Fixes
+
+* 🐛 Fix evaluating stringified annotations in Python 3.10. PR [#11355](https://github.com/fastapi/fastapi/pull/11355) by [@chaen](https://github.com/chaen).
+
+## 0.123.6
+
+### Fixes
+
+* 🐛 Fix support for functools wraps and partial combined, for async and regular functions and classes in path operations and dependencies. PR [#14448](https://github.com/fastapi/fastapi/pull/14448) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.123.5
+
+### Features
+
+* ✨ Allow using dependables with `functools.partial()`. PR [#9753](https://github.com/fastapi/fastapi/pull/9753) by [@lieryan](https://github.com/lieryan).
+* ✨ Add support for wrapped functions (e.g. `@functools.wraps()`) used with forward references. PR [#5077](https://github.com/fastapi/fastapi/pull/5077) by [@lucaswiman](https://github.com/lucaswiman).
+* ✨ Handle wrapped dependencies. PR [#9555](https://github.com/fastapi/fastapi/pull/9555) by [@phy1729](https://github.com/phy1729).
+
+### Fixes
+
+* 🐛 Fix optional sequence handling with new union syntax from Python 3.10. PR [#14430](https://github.com/fastapi/fastapi/pull/14430) by [@Viicos](https://github.com/Viicos).
+
+### Refactors
+
+* 🔥 Remove dangling extra condiitonal no longer needed. PR [#14435](https://github.com/fastapi/fastapi/pull/14435) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Refactor internals, update `is_coroutine` check to reuse internal supported variants (unwrap, check class). PR [#14434](https://github.com/fastapi/fastapi/pull/14434) by [@tiangolo](https://github.com/tiangolo).
+
+### Translations
+
+* 🌐 Sync German docs. PR [#14367](https://github.com/fastapi/fastapi/pull/14367) by [@nilslindemann](https://github.com/nilslindemann).
+
+## 0.123.4
+
+### Fixes
+
+* 🐛 Fix OpenAPI schema support for computed fields when using `separate_input_output_schemas=False`. PR [#13207](https://github.com/fastapi/fastapi/pull/13207) by [@vgrafe](https://github.com/vgrafe).
+
+### Docs
+
+* 📝 Fix docstring of `servers` parameter. PR [#14405](https://github.com/fastapi/fastapi/pull/14405) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.123.3
+
+### Fixes
+
+* 🐛 Fix Query\Header\Cookie parameter model alias. PR [#14360](https://github.com/fastapi/fastapi/pull/14360) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🐛 Fix optional sequence handling in `serialize sequence value` with Pydantic V2. PR [#14297](https://github.com/fastapi/fastapi/pull/14297) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.123.2
+
+### Fixes
+
+* 🐛 Fix unformatted `{type_}` in FastAPIError. PR [#14416](https://github.com/fastapi/fastapi/pull/14416) by [@Just-Helpful](https://github.com/Just-Helpful).
+* 🐛 Fix parsing extra non-body parameter list. PR [#14356](https://github.com/fastapi/fastapi/pull/14356) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🐛 Fix parsing extra `Form` parameter list. PR [#14303](https://github.com/fastapi/fastapi/pull/14303) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🐛 Fix support for form values with empty strings interpreted as missing (`None` if that's the default), for compatibility with HTML forms. PR [#13537](https://github.com/fastapi/fastapi/pull/13537) by [@MarinPostma](https://github.com/MarinPostma).
+
+### Docs
+
+* 📝 Add tip on how to install `pip` in case of `No module named pip` error in `virtual-environments.md`. PR [#14211](https://github.com/fastapi/fastapi/pull/14211) by [@zadevhub](https://github.com/zadevhub).
+* 📝 Update Primary Key notes for the SQL databases tutorial to avoid confusion. PR [#14120](https://github.com/fastapi/fastapi/pull/14120) by [@FlaviusRaducu](https://github.com/FlaviusRaducu).
+* 📝 Clarify estimation note in documentation. PR [#14070](https://github.com/fastapi/fastapi/pull/14070) by [@SaisakthiM](https://github.com/SaisakthiM).
+
+## 0.123.1
+
+### Fixes
+
+* 🐛 Avoid accessing non-existing "$ref" key for Pydantic v2 compat remapping. PR [#14361](https://github.com/fastapi/fastapi/pull/14361) by [@svlandeg](https://github.com/svlandeg).
+* 🐛 Fix `TypeError` when encoding a decimal with a `NaN` or `Infinity` value. PR [#12935](https://github.com/fastapi/fastapi/pull/12935) by [@kentwelcome](https://github.com/kentwelcome).
+
+### Internal
+
+* 🐛 Fix Windows UnicodeEncodeError in CLI test. PR [#14295](https://github.com/fastapi/fastapi/pull/14295) by [@hemanth-thirthahalli](https://github.com/hemanth-thirthahalli).
+* 🔧 Update sponsors: add Greptile. PR [#14429](https://github.com/fastapi/fastapi/pull/14429) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI GitHub topic repositories. PR [#14426](https://github.com/fastapi/fastapi/pull/14426) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump markdown-include-variants from 0.0.6 to 0.0.7. PR [#14423](https://github.com/fastapi/fastapi/pull/14423) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 👥 Update FastAPI People - Sponsors. PR [#14422](https://github.com/fastapi/fastapi/pull/14422) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI People - Contributors and Translators. PR [#14420](https://github.com/fastapi/fastapi/pull/14420) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.123.0
+
+### Fixes
+
+* 🐛 Cache dependencies that don't use scopes and don't have sub-dependencies with scopes. PR [#14419](https://github.com/fastapi/fastapi/pull/14419) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.122.1
+
+### Fixes
+
+* 🐛 Fix hierarchical security scope propagation. PR [#5624](https://github.com/fastapi/fastapi/pull/5624) by [@kristjanvalur](https://github.com/kristjanvalur).
+
+### Docs
+
+* 💅 Update CSS to explicitly use emoji font. PR [#14415](https://github.com/fastapi/fastapi/pull/14415) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* ⬆ Bump markdown-include-variants from 0.0.5 to 0.0.6. PR [#14418](https://github.com/fastapi/fastapi/pull/14418) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.122.0
+
+### Fixes
+
+* 🐛 Use `401` status code in security classes when credentials are missing. PR [#13786](https://github.com/fastapi/fastapi/pull/13786) by [@YuriiMotov](https://github.com/YuriiMotov).
+ * If your code depended on these classes raising the old (less correct) `403` status code, check the new docs about how to override the classes, to use the same old behavior: [Use Old 403 Authentication Error Status Codes](https://fastapi.tiangolo.com/how-to/authentication-error-status-code/).
+
+### Internal
+
+* 🔧 Configure labeler to exclude files that start from underscore for `lang-all` label. PR [#14213](https://github.com/fastapi/fastapi/pull/14213) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 👷 Add pre-commit config with local script for permalinks. PR [#14398](https://github.com/fastapi/fastapi/pull/14398) by [@tiangolo](https://github.com/tiangolo).
+* 💄 Use font Fira Code to fix display of Rich panels in docs in Windows. PR [#14387](https://github.com/fastapi/fastapi/pull/14387) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Add custom pre-commit CI. PR [#14397](https://github.com/fastapi/fastapi/pull/14397) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump actions/checkout from 5 to 6. PR [#14381](https://github.com/fastapi/fastapi/pull/14381) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* 👷 Upgrade `latest-changes` GitHub Action and pin `actions/checkout@v5`. PR [#14403](https://github.com/fastapi/fastapi/pull/14403) by [@svlandeg](https://github.com/svlandeg).
+* 🛠️ Add `add-permalinks` and `add-permalinks-page` to `scripts/docs.py`. PR [#14033](https://github.com/fastapi/fastapi/pull/14033) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🔧 Upgrade Material for MkDocs and remove insiders. PR [#14375](https://github.com/fastapi/fastapi/pull/14375) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.121.3
+
+### Refactors
+
+* ♻️ Make the result of `Depends()` and `Security()` hashable, as a workaround for other tools interacting with these internal parts. PR [#14372](https://github.com/fastapi/fastapi/pull/14372) by [@tiangolo](https://github.com/tiangolo).
+
+### Upgrades
+
+* ⬆️ Bump Starlette to <`0.51.0`. PR [#14282](https://github.com/fastapi/fastapi/pull/14282) by [@musicinmybrain](https://github.com/musicinmybrain).
+
+### Docs
+
+* 📝 Add missing hash part. PR [#14369](https://github.com/fastapi/fastapi/pull/14369) by [@nilslindemann](https://github.com/nilslindemann).
+* 📝 Fix typos in code comments. PR [#14364](https://github.com/fastapi/fastapi/pull/14364) by [@Edge-Seven](https://github.com/Edge-Seven).
+* 📝 Add docs for using FastAPI Cloud. PR [#14359](https://github.com/fastapi/fastapi/pull/14359) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.121.2
+
+### Fixes
+
+* 🐛 Fix handling of JSON Schema attributes named "$ref". PR [#14349](https://github.com/fastapi/fastapi/pull/14349) by [@tiangolo](https://github.com/tiangolo).
+
+### Docs
+
+* 📝 Add EuroPython talk & podcast episode with Sebastián Ramírez. PR [#14260](https://github.com/fastapi/fastapi/pull/14260) by [@clytaemnestra](https://github.com/clytaemnestra).
+* ✏️ Fix links and add missing permalink in docs. PR [#14217](https://github.com/fastapi/fastapi/pull/14217) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+### Translations
+
+* 🌐 Update Portuguese translations with LLM prompt. PR [#14228](https://github.com/fastapi/fastapi/pull/14228) by [@ceb10n](https://github.com/ceb10n).
+* 🔨 Add Portuguese translations LLM prompt. PR [#14208](https://github.com/fastapi/fastapi/pull/14208) by [@ceb10n](https://github.com/ceb10n).
+* 🌐 Sync Russian docs. PR [#14331](https://github.com/fastapi/fastapi/pull/14331) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Sync German docs. PR [#14317](https://github.com/fastapi/fastapi/pull/14317) by [@nilslindemann](https://github.com/nilslindemann).
+
+## 0.121.1
+
+### Fixes
+
+* 🐛 Fix `Depends(func, scope='function')` for top level (parameterless) dependencies. PR [#14301](https://github.com/fastapi/fastapi/pull/14301) by [@luzzodev](https://github.com/luzzodev).
+
+### Docs
+
+* 📝 Upate docs for advanced dependencies with `yield`, noting the changes in 0.121.0, adding `scope`. PR [#14287](https://github.com/fastapi/fastapi/pull/14287) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* ⬆ Bump ruff from 0.13.2 to 0.14.3. PR [#14276](https://github.com/fastapi/fastapi/pull/14276) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#14289](https://github.com/fastapi/fastapi/pull/14289) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+
+## 0.121.0
+
+### Features
+
+* ✨ Add support for dependencies with scopes, support `scope="request"` for dependencies with `yield` that exit before the response is sent. PR [#14262](https://github.com/fastapi/fastapi/pull/14262) by [@tiangolo](https://github.com/tiangolo).
+ * New docs: [Dependencies with `yield` - Early exit and `scope`](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#early-exit-and-scope).
+
+### Internal
+
+* 👥 Update FastAPI People - Contributors and Translators. PR [#14273](https://github.com/fastapi/fastapi/pull/14273) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI People - Sponsors. PR [#14274](https://github.com/fastapi/fastapi/pull/14274) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI GitHub topic repositories. PR [#14280](https://github.com/fastapi/fastapi/pull/14280) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump mkdocs-macros-plugin from 1.4.0 to 1.4.1. PR [#14277](https://github.com/fastapi/fastapi/pull/14277) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump mkdocstrings[python] from 0.26.1 to 0.30.1. PR [#14279](https://github.com/fastapi/fastapi/pull/14279) by [@dependabot[bot]](https://github.com/apps/dependabot).
+
+## 0.120.4
+
+### Fixes
+
+* 🐛 Fix security schemes in OpenAPI when added at the top level app. PR [#14266](https://github.com/fastapi/fastapi/pull/14266) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.120.3
+
+### Refactors
+
+* ♻️ Reduce internal cyclic recursion in dependencies, from 2 functions calling each other to 1 calling itself. PR [#14256](https://github.com/fastapi/fastapi/pull/14256) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Refactor internals of dependencies, simplify code and remove `get_param_sub_dependant`. PR [#14255](https://github.com/fastapi/fastapi/pull/14255) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Refactor internals of dependencies, simplify using dataclasses. PR [#14254](https://github.com/fastapi/fastapi/pull/14254) by [@tiangolo](https://github.com/tiangolo).
+
+### Docs
+
+* 📝 Update note for untranslated pages. PR [#14257](https://github.com/fastapi/fastapi/pull/14257) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.120.2
+
+### Fixes
+
+* 🐛 Fix separation of schemas with nested models introduced in 0.119.0. PR [#14246](https://github.com/fastapi/fastapi/pull/14246) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* 🔧 Add sponsor: SerpApi. PR [#14248](https://github.com/fastapi/fastapi/pull/14248) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump actions/download-artifact from 5 to 6. PR [#14236](https://github.com/fastapi/fastapi/pull/14236) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#14237](https://github.com/fastapi/fastapi/pull/14237) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* ⬆ Bump actions/upload-artifact from 4 to 5. PR [#14235](https://github.com/fastapi/fastapi/pull/14235) by [@dependabot[bot]](https://github.com/apps/dependabot).
+
+## 0.120.1
+
+### Upgrades
+
+* ⬆️ Bump Starlette to <`0.50.0`. PR [#14234](https://github.com/fastapi/fastapi/pull/14234) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+### Internal
+
+* 🔧 Add `license` and `license-files` to `pyproject.toml`, remove `License` from `classifiers`. PR [#14230](https://github.com/fastapi/fastapi/pull/14230) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.120.0
+
+There are no major nor breaking changes in this release. ☕️
+
+The internal reference documentation now uses `annotated_doc.Doc` instead of `typing_extensions.Doc`, this adds a new (very small) dependency on [`annotated-doc`](https://github.com/fastapi/annotated-doc), a package made just to provide that `Doc` documentation utility class.
+
+I would expect `typing_extensions.Doc` to be deprecated and then removed at some point from `typing_extensions`, for that reason there's the new `annotated-doc` micro-package. If you are curious about this, you can read more in the repo for [`annotated-doc`](https://github.com/fastapi/annotated-doc).
+
+This new version `0.120.0` only contains that transition to the new home package for that utility class `Doc`.
+
+### Translations
+
+* 🌐 Sync German docs. PR [#14188](https://github.com/fastapi/fastapi/pull/14188) by [@nilslindemann](https://github.com/nilslindemann).
+
+### Internal
+
+* ➕ Migrate internal reference documentation from `typing_extensions.Doc` to `annotated_doc.Doc`. PR [#14222](https://github.com/fastapi/fastapi/pull/14222) by [@tiangolo](https://github.com/tiangolo).
+* 🛠️ Update German LLM prompt and test file. PR [#14189](https://github.com/fastapi/fastapi/pull/14189) by [@nilslindemann](https://github.com/nilslindemann).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#14181](https://github.com/fastapi/fastapi/pull/14181) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+
+## 0.119.1
+
+### Fixes
+
+* 🐛 Fix internal Pydantic v1 compatibility (warnings) for Python 3.14 and Pydantic 2.12.1. PR [#14186](https://github.com/fastapi/fastapi/pull/14186) by [@svlandeg](https://github.com/svlandeg).
+
+### Docs
+
+* 📝 Replace `starlette.io` by `starlette.dev` and `uvicorn.org` by `uvicorn.dev`. PR [#14176](https://github.com/fastapi/fastapi/pull/14176) by [@Kludex](https://github.com/Kludex).
+
+### Internal
+
+* 🔧 Add sponsor Requestly. PR [#14205](https://github.com/fastapi/fastapi/pull/14205) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Configure reminder for `waiting` label in `issue-manager`. PR [#14156](https://github.com/fastapi/fastapi/pull/14156) by [@YuriiMotov](https://github.com/YuriiMotov).
+
+## 0.119.0
+
+FastAPI now (temporarily) supports both Pydantic v2 models and `pydantic.v1` models at the same time in the same app, to make it easier for any FastAPI apps still using Pydantic v1 to gradually but quickly **migrate to Pydantic v2**.
+
+```Python
+from fastapi import FastAPI
+from pydantic import BaseModel as BaseModelV2
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+
+
+class ItemV2(BaseModelV2):
+ title: str
+ summary: str | None = None
+
+
+app = FastAPI()
+
+
+@app.post("/items/", response_model=ItemV2)
+def create_item(item: Item):
+ return {"title": item.name, "summary": item.description}
+```
+
+Adding this feature was a big effort with the main objective of making it easier for the few applications still stuck in Pydantic v1 to migrate to Pydantic v2.
+
+And with this, support for **Pydantic v1 is now deprecated** and will be **removed** from FastAPI in a future version soon.
+
+**Note**: have in mind that the Pydantic team already stopped supporting Pydantic v1 for recent versions of Python, starting with Python 3.14.
+
+You can read in the docs more about how to [Migrate from Pydantic v1 to Pydantic v2](https://fastapi.tiangolo.com/how-to/migrate-from-pydantic-v1-to-pydantic-v2/).
+
+### Features
+
+* ✨ Add support for `from pydantic.v1 import BaseModel`, mixed Pydantic v1 and v2 models in the same app. PR [#14168](https://github.com/fastapi/fastapi/pull/14168) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.118.3
+
+### Upgrades
+
+* ⬆️ Add support for Python 3.14. PR [#14165](https://github.com/fastapi/fastapi/pull/14165) by [@svlandeg](https://github.com/svlandeg).
+
+## 0.118.2
+
+### Fixes
+
+* 🐛 Fix tagged discriminated union not recognized as body field. PR [#12942](https://github.com/fastapi/fastapi/pull/12942) by [@frankie567](https://github.com/frankie567).
+
+### Internal
+
+* ⬆ Bump astral-sh/setup-uv from 6 to 7. PR [#14167](https://github.com/fastapi/fastapi/pull/14167) by [@dependabot[bot]](https://github.com/apps/dependabot).
+
+## 0.118.1
+
+### Upgrades
+
+* 👽️ Ensure compatibility with Pydantic 2.12.0. PR [#14036](https://github.com/fastapi/fastapi/pull/14036) by [@cjwatson](https://github.com/cjwatson).
+
+### Docs
+
+* 📝 Add External Link: Getting started with logging in FastAPI. PR [#14152](https://github.com/fastapi/fastapi/pull/14152) by [@itssimon](https://github.com/itssimon).
+
+### Translations
+
+* 🔨 Add Russian translations LLM prompt. PR [#13936](https://github.com/fastapi/fastapi/pull/13936) by [@tiangolo](https://github.com/tiangolo).
+* 🌐 Sync German docs. PR [#14149](https://github.com/fastapi/fastapi/pull/14149) by [@nilslindemann](https://github.com/nilslindemann).
+* 🌐 Add Russian translations for missing pages (LLM-generated). PR [#14135](https://github.com/fastapi/fastapi/pull/14135) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Update Russian translations for existing pages (LLM-generated). PR [#14123](https://github.com/fastapi/fastapi/pull/14123) by [@YuriiMotov](https://github.com/YuriiMotov).
+* 🌐 Remove configuration files for inactive translations. PR [#14130](https://github.com/fastapi/fastapi/pull/14130) by [@tiangolo](https://github.com/tiangolo).
+
+### Internal
+
+* 🔨 Move local coverage logic to its own script. PR [#14166](https://github.com/fastapi/fastapi/pull/14166) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#14161](https://github.com/fastapi/fastapi/pull/14161) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* ⬆ Bump griffe-typingdoc from 0.2.8 to 0.2.9. PR [#14144](https://github.com/fastapi/fastapi/pull/14144) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump mkdocs-macros-plugin from 1.3.9 to 1.4.0. PR [#14145](https://github.com/fastapi/fastapi/pull/14145) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump markdown-include-variants from 0.0.4 to 0.0.5. PR [#14146](https://github.com/fastapi/fastapi/pull/14146) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#14126](https://github.com/fastapi/fastapi/pull/14126) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* 👥 Update FastAPI GitHub topic repositories. PR [#14150](https://github.com/fastapi/fastapi/pull/14150) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI People - Sponsors. PR [#14139](https://github.com/fastapi/fastapi/pull/14139) by [@tiangolo](https://github.com/tiangolo).
+* 👥 Update FastAPI People - Contributors and Translators. PR [#14138](https://github.com/fastapi/fastapi/pull/14138) by [@tiangolo](https://github.com/tiangolo).
+* ⬆ Bump ruff from 0.12.7 to 0.13.2. PR [#14147](https://github.com/fastapi/fastapi/pull/14147) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump sqlmodel from 0.0.24 to 0.0.25. PR [#14143](https://github.com/fastapi/fastapi/pull/14143) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump tiangolo/issue-manager from 0.5.1 to 0.6.0. PR [#14148](https://github.com/fastapi/fastapi/pull/14148) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* 👷 Update docs previews comment, single comment, add failure status. PR [#14129](https://github.com/fastapi/fastapi/pull/14129) by [@tiangolo](https://github.com/tiangolo).
+* 🔨 Modify `mkdocs_hooks.py` to add `title` to page's metadata (remove permalinks in social cards). PR [#14125](https://github.com/fastapi/fastapi/pull/14125) by [@YuriiMotov](https://github.com/YuriiMotov).
+
## 0.118.0
### Fixes
@@ -5435,7 +6035,7 @@ Note: all the previous parameters are still there, so it's still possible to dec
* Upgrade the compatible version of Starlette to `0.12.0`.
* This includes support for ASGI 3 (the latest version of the standard).
- * It's now possible to use [Starlette's `StreamingResponse`](https://www.starlette.io/responses/#streamingresponse) with iterators, like [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objects (as those returned by `open()`).
+ * It's now possible to use [Starlette's `StreamingResponse`](https://www.starlette.dev/responses/#streamingresponse) with iterators, like [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objects (as those returned by `open()`).
* It's now possible to use the low level utility `iterate_in_threadpool` from `starlette.concurrency` (for advanced scenarios).
* PR [#243](https://github.com/tiangolo/fastapi/pull/243).
diff --git a/docs/en/docs/resources/index.md b/docs/en/docs/resources/index.md
index caefdf125..f7d48576f 100644
--- a/docs/en/docs/resources/index.md
+++ b/docs/en/docs/resources/index.md
@@ -1,3 +1,3 @@
# Resources { #resources }
-Additional resources, external links, articles and more. ✈️
+Additional resources, external links, and more. ✈️
diff --git a/docs/en/docs/tutorial/background-tasks.md b/docs/en/docs/tutorial/background-tasks.md
index 6e16410a3..be7ecd587 100644
--- a/docs/en/docs/tutorial/background-tasks.md
+++ b/docs/en/docs/tutorial/background-tasks.md
@@ -15,7 +15,7 @@ This includes, for example:
First, import `BackgroundTasks` and define a parameter in your *path operation function* with a type declaration of `BackgroundTasks`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.
@@ -31,13 +31,13 @@ In this case, the task function will write to a file (simulating sending an emai
And as the write operation doesn't use `async` and `await`, we define the function with normal `def`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
## Add the background task { #add-the-background-task }
Inside of your *path operation function*, pass your task function to the *background tasks* object with the method `.add_task()`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
`.add_task()` receives as arguments:
@@ -63,7 +63,7 @@ And then another background task generated at the *path operation function* will
## Technical Details { #technical-details }
-The class `BackgroundTasks` comes directly from `starlette.background`.
+The class `BackgroundTasks` comes directly from `starlette.background`.
It is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.
@@ -71,7 +71,7 @@ By only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible t
It's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.
-You can see more details in Starlette's official docs for Background Tasks.
+You can see more details in Starlette's official docs for Background Tasks.
## Caveat { #caveat }
diff --git a/docs/en/docs/tutorial/bigger-applications.md b/docs/en/docs/tutorial/bigger-applications.md
index 74daa5483..f6cee8036 100644
--- a/docs/en/docs/tutorial/bigger-applications.md
+++ b/docs/en/docs/tutorial/bigger-applications.md
@@ -56,7 +56,7 @@ from app.routers import items
The same file structure with comments:
-```
+```bash
.
├── app # "app" is a Python package
│ ├── __init__.py # this file makes "app" a "Python package"
@@ -85,9 +85,7 @@ You can create the *path operations* for that module using `APIRouter`.
You import it and create an "instance" the same way you would with the class `FastAPI`:
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
### *Path operations* with `APIRouter` { #path-operations-with-apirouter }
@@ -95,9 +93,7 @@ And then you use it to declare your *path operations*.
Use it the same way you would use the `FastAPI` class:
-```Python hl_lines="6 11 16" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
You can think of `APIRouter` as a "mini `FastAPI`" class.
@@ -121,35 +117,7 @@ So we put them in their own `dependencies` module (`app/dependencies.py`).
We will now use a simple dependency to read a custom `X-Token` header:
-//// 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
-
-Prefer to use the `Annotated` version if possible.
-
-///
-
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!> ../../docs_src/bigger_applications/app/dependencies.py!}
-```
-
-////
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
/// tip
@@ -181,9 +149,7 @@ We know all the *path operations* in this module have the same:
So, instead of adding all that to each *path operation*, we can add it to the `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_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
As the path of each *path operation* has to start with `/`, like in:
@@ -242,9 +208,7 @@ And we need to get the dependency function from the module `app.dependencies`, t
So we use a relative import with `..` for the dependencies:
-```Python hl_lines="3" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
#### How relative imports work { #how-relative-imports-work }
@@ -315,9 +279,7 @@ We are not adding the prefix `/items` nor the `tags=["items"]` to each *path ope
But we can still add _more_ `tags` that will be applied to a specific *path operation*, and also some extra `responses` specific to that *path operation*:
-```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
/// tip
@@ -343,17 +305,13 @@ You import and create a `FastAPI` class as normally.
And we can even declare [global dependencies](dependencies/global-dependencies.md){.internal-link target=_blank} that will be combined with the dependencies for each `APIRouter`:
-```Python hl_lines="1 3 7" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
### Import the `APIRouter` { #import-the-apirouter }
Now we import the other submodules that have `APIRouter`s:
-```Python hl_lines="4-5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *}
As the files `app/routers/users.py` and `app/routers/items.py` are submodules that are part of the same Python package `app`, we can use a single dot `.` to import them using "relative imports".
@@ -416,17 +374,13 @@ the `router` from `users` would overwrite the one from `items` and we wouldn't b
So, to be able to use both of them in the same file, we import the submodules directly:
-```Python hl_lines="5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *}
### Include the `APIRouter`s for `users` and `items` { #include-the-apirouters-for-users-and-items }
Now, let's include the `router`s from the submodules `users` and `items`:
-```Python hl_lines="10-11" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[10:11] title["app/main.py"] *}
/// info
@@ -466,17 +420,13 @@ It contains an `APIRouter` with some admin *path operations* that your organizat
For this example it will be super simple. But let's say that because it is shared with other projects in the organization, we cannot modify it and add a `prefix`, `dependencies`, `tags`, etc. directly to the `APIRouter`:
-```Python hl_lines="3" title="app/internal/admin.py"
-{!../../docs_src/bigger_applications/app/internal/admin.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *}
But we still want to set a custom `prefix` when including the `APIRouter` so that all its *path operations* start with `/admin`, we want to secure it with the `dependencies` we already have for this project, and we want to include `tags` and `responses`.
We can declare all that without having to modify the original `APIRouter` by passing those parameters to `app.include_router()`:
-```Python hl_lines="14-17" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[14:17] title["app/main.py"] *}
That way, the original `APIRouter` will stay unmodified, so we can still share that same `app/internal/admin.py` file with other projects in the organization.
@@ -497,9 +447,7 @@ We can also add *path operations* directly to the `FastAPI` app.
Here we do it... just to show that we can 🤷:
-```Python hl_lines="21-23" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[21:23] title["app/main.py"] *}
and it will work correctly, together with all the other *path operations* added with `app.include_router()`.
diff --git a/docs/en/docs/tutorial/body-nested-models.md b/docs/en/docs/tutorial/body-nested-models.md
index 445235a42..5fd83a8f3 100644
--- a/docs/en/docs/tutorial/body-nested-models.md
+++ b/docs/en/docs/tutorial/body-nested-models.md
@@ -14,35 +14,15 @@ This will make `tags` be a list, although it doesn't declare the type of the ele
But Python has a specific way to declare lists with internal types, or "type parameters":
-### Import typing's `List` { #import-typings-list }
-
-In Python 3.9 and above you can use the standard `list` to declare these type annotations as we'll see below. 💡
-
-But in Python versions before 3.9 (3.6 and above), you first need to import `List` from standard Python's `typing` module:
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
### Declare a `list` with a type parameter { #declare-a-list-with-a-type-parameter }
-To declare types that have type parameters (internal types), like `list`, `dict`, `tuple`:
-
-* If you are in a Python version lower than 3.9, import their equivalent version from the `typing` module
-* Pass the internal type(s) as "type parameters" using square brackets: `[` and `]`
-
-In Python 3.9 it would be:
+To declare types that have type parameters (internal types), like `list`, `dict`, `tuple`,
+pass the internal type(s) as "type parameters" using square brackets: `[` and `]`
```Python
my_list: list[str]
```
-In versions of Python before 3.9, it would be:
-
-```Python
-from typing import List
-
-my_list: List[str]
-```
-
That's all standard Python syntax for type declarations.
Use that same standard syntax for model attributes with internal types.
@@ -178,12 +158,6 @@ Notice how `Offer` has a list of `Item`s, which in turn have an optional list of
If the top level value of the JSON body you expect is a JSON `array` (a Python `list`), you can declare the type in the parameter of the function, the same as in Pydantic models:
-```Python
-images: List[Image]
-```
-
-or in Python 3.9 and above:
-
```Python
images: list[Image]
```
diff --git a/docs/en/docs/tutorial/body-updates.md b/docs/en/docs/tutorial/body-updates.md
index baeb53ec6..1b7fd7066 100644
--- a/docs/en/docs/tutorial/body-updates.md
+++ b/docs/en/docs/tutorial/body-updates.md
@@ -50,14 +50,6 @@ If you want to receive partial updates, it's very useful to use the parameter `e
Like `item.model_dump(exclude_unset=True)`.
-/// info
-
-In Pydantic v1 the method was called `.dict()`, it was deprecated (but still supported) in Pydantic v2, and renamed to `.model_dump()`.
-
-The examples here use `.dict()` for compatibility with Pydantic v1, but you should use `.model_dump()` instead if you can use Pydantic v2.
-
-///
-
That would generate a `dict` with only the data that was set when creating the `item` model, excluding default values.
Then you can use this to generate a `dict` with only the data that was set (sent in the request), omitting default values:
@@ -68,14 +60,6 @@ Then you can use this to generate a `dict` with only the data that was set (sent
Now, you can create a copy of the existing model using `.model_copy()`, and pass the `update` parameter with a `dict` containing the data to update.
-/// info
-
-In Pydantic v1 the method was called `.copy()`, it was deprecated (but still supported) in Pydantic v2, and renamed to `.model_copy()`.
-
-The examples here use `.copy()` for compatibility with Pydantic v1, but you should use `.model_copy()` instead if you can use Pydantic v2.
-
-///
-
Like `stored_item_model.model_copy(update=update_data)`:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
diff --git a/docs/en/docs/tutorial/body.md b/docs/en/docs/tutorial/body.md
index a820802f7..2d0dfcbb5 100644
--- a/docs/en/docs/tutorial/body.md
+++ b/docs/en/docs/tutorial/body.md
@@ -128,14 +128,6 @@ Inside of the function, you can access all the attributes of the model object di
{* ../../docs_src/body/tutorial002_py310.py *}
-/// info
-
-In Pydantic v1 the method was called `.dict()`, it was deprecated (but still supported) in Pydantic v2, and renamed to `.model_dump()`.
-
-The examples here use `.dict()` for compatibility with Pydantic v1, but you should use `.model_dump()` instead if you can use Pydantic v2.
-
-///
-
## Request body + path parameters { #request-body-path-parameters }
You can declare path parameters and request body at the same time.
@@ -163,7 +155,7 @@ The function parameters will be recognized as follows:
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`.
+The `str | None` (Python 3.10+) or `Union` in `Union[str, None]` (Python 3.9+) 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.
diff --git a/docs/en/docs/tutorial/cookie-param-models.md b/docs/en/docs/tutorial/cookie-param-models.md
index 96dc5cf3d..016a65d7f 100644
--- a/docs/en/docs/tutorial/cookie-param-models.md
+++ b/docs/en/docs/tutorial/cookie-param-models.md
@@ -50,7 +50,7 @@ Your API now has the power to control its own > dep_req: Start request
+ Note over dep_req: Run code up to yield
+ dep_req ->> dep_func: Pass dependency
+ Note over dep_func: Run code up to yield
+ dep_func ->> operation: Run path operation with dependency
+ operation ->> dep_func: Return from path operation
+ Note over dep_func: Run code after yield
+ Note over dep_func: ✅ Dependency closed
+ dep_func ->> client: Send response to client
+ Note over client: Response sent
+ Note over dep_req: Run code after yield
+ Note over dep_req: ✅ Dependency closed
+```
+
## Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }
Dependencies with `yield` have evolved over time to cover different use cases and fix some issues.
@@ -224,7 +269,7 @@ In Python, you can create Context Managers by FastAPI Cloud, go and join the waiting list if you haven't. 🚀
+
+If you already have a **FastAPI Cloud** account (we invited you from the waiting list 😉), you can deploy your application with one command.
+
+Before deploying, make sure you are logged in:
+
+kwargs. Even if they don't have a default value.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
### Better with `Annotated` { #better-with-annotated }
diff --git a/docs/en/docs/tutorial/path-params.md b/docs/en/docs/tutorial/path-params.md
index 457cc2713..ea4307900 100644
--- a/docs/en/docs/tutorial/path-params.md
+++ b/docs/en/docs/tutorial/path-params.md
@@ -2,7 +2,7 @@
You can declare path "parameters" or "variables" with the same syntax used by Python format strings:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
The value of the path parameter `item_id` will be passed to your function as the argument `item_id`.
@@ -16,7 +16,7 @@ So, if you run this example and go to Enumerations (or enums) are available in Python since version 3.4.
-
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip
@@ -158,7 +152,7 @@ If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine
Then create a *path parameter* with a type annotation using the enum class you created (`ModelName`):
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
### Check the docs { #check-the-docs }
@@ -174,13 +168,13 @@ The value of the *path parameter* will be an *enumeration member*.
You can compare it with the *enumeration member* in your created enum `ModelName`:
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
#### Get the *enumeration value* { #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`:
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip
@@ -194,7 +188,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:
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}
In your client you will get a JSON response like:
@@ -233,7 +227,7 @@ In this case, the name of the parameter is `file_path`, and the last part, `:pat
So, you can use it with:
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}
/// tip
diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md
index adf08a924..4b8cc9d29 100644
--- a/docs/en/docs/tutorial/query-params-str-validations.md
+++ b/docs/en/docs/tutorial/query-params-str-validations.md
@@ -55,7 +55,7 @@ q: str | None = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Union[str, None] = None
@@ -73,7 +73,7 @@ q: Annotated[str | None] = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Annotated[Union[str, None]] = None
@@ -206,20 +206,6 @@ If you feel lost with all these **"regular expression"** ideas, don't worry. The
Now you know that whenever you need them you can use them in **FastAPI**.
-### Pydantic v1 `regex` instead of `pattern` { #pydantic-v1-regex-instead-of-pattern }
-
-Before Pydantic version 2 and before FastAPI 0.100.0, the parameter was called `regex` instead of `pattern`, but it's now deprecated.
-
-You could still see some code using it:
-
-//// tab | Pydantic v1
-
-{* ../../docs_src/query_params_str_validations/tutorial004_regex_an_py310.py hl[11] *}
-
-////
-
-But know that this is deprecated and it should be updated to use the new parameter `pattern`. 🤓
-
## Default values { #default-values }
You can, of course, use default values other than `None`.
diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md
index 2323b83c7..3c9c225fb 100644
--- a/docs/en/docs/tutorial/query-params.md
+++ b/docs/en/docs/tutorial/query-params.md
@@ -2,7 +2,7 @@
When you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *}
The query is the set of key-value pairs that go after the `?` in a URL, separated by `&` characters.
@@ -128,7 +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:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
Here the query parameter `needy` is a required query parameter of type `str`.
diff --git a/docs/en/docs/tutorial/response-model.md b/docs/en/docs/tutorial/response-model.md
index 5090dbcdf..b287cdf50 100644
--- a/docs/en/docs/tutorial/response-model.md
+++ b/docs/en/docs/tutorial/response-model.md
@@ -183,7 +183,7 @@ 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}.
-{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.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`.
@@ -193,7 +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:
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *}
This will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case.
@@ -252,20 +252,6 @@ 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()`.
-
-The examples here use `.dict()` for compatibility with Pydantic v1, but you should use `.model_dump()` instead if you can use Pydantic v2.
-
-///
-
-/// info
-
-FastAPI uses Pydantic model's `.dict()` with its `exclude_unset` parameter to achieve this.
-
-///
-
-/// info
-
You can also use:
* `response_model_exclude_defaults=True`
diff --git a/docs/en/docs/tutorial/response-status-code.md b/docs/en/docs/tutorial/response-status-code.md
index a2d9757b2..638959248 100644
--- a/docs/en/docs/tutorial/response-status-code.md
+++ b/docs/en/docs/tutorial/response-status-code.md
@@ -8,7 +8,7 @@ The same way you can specify a response model, you can also declare the HTTP sta
* `@app.delete()`
* etc.
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
/// note
@@ -74,7 +74,7 @@ To know more about each status code and which code is for what, check the Pydantic's docs: Configuration.
+You can 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`.
-////
-
-//// tab | Pydantic v1
-
-In Pydantic version 1, you would use an internal class `Config` and `schema_extra`, as described in Pydantic's docs: Schema customization.
-
-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`.
-
-////
-
/// tip
You could use the same technique to extend the JSON Schema and add your own custom extra info.
diff --git a/docs/en/docs/tutorial/sql-databases.md b/docs/en/docs/tutorial/sql-databases.md
index cfa1c9073..b42e9ba2f 100644
--- a/docs/en/docs/tutorial/sql-databases.md
+++ b/docs/en/docs/tutorial/sql-databases.md
@@ -65,7 +65,7 @@ There are a few differences:
* `Field(primary_key=True)` tells SQLModel that the `id` is the **primary key** in the SQL database (you can learn more about SQL primary keys in the SQLModel docs).
- By having the type as `int | None`, SQLModel will know that this column should be an `INTEGER` in the SQL database and that it should be `NULLABLE`.
+ **Note:** We use `int | None` for the primary key field so that in Python code we can *create an object without an `id`* (`id=None`), assuming the database will *generate it when saving*. SQLModel understands that the database will provide the `id` and *defines the column as a non-null `INTEGER`* in the database schema. See SQLModel docs on primary keys for details.
* `Field(index=True)` tells SQLModel that it should create a **SQL index** for this column, that would allow faster lookups in the database when reading data filtered by this column.
diff --git a/docs/en/docs/tutorial/static-files.md b/docs/en/docs/tutorial/static-files.md
index 5b75d048b..8cf5a5a8a 100644
--- a/docs/en/docs/tutorial/static-files.md
+++ b/docs/en/docs/tutorial/static-files.md
@@ -7,7 +7,7 @@ You can serve static files automatically from a directory using `StaticFiles`.
* Import `StaticFiles`.
* "Mount" a `StaticFiles()` instance in a specific path.
-{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *}
/// note | Technical Details
@@ -37,4 +37,4 @@ All these parameters can be different than "`static`", adjust them with the need
## More info { #more-info }
-For more details and options check Starlette's docs about Static Files.
+For more details and options check Starlette's docs about Static Files.
diff --git a/docs/en/docs/tutorial/testing.md b/docs/en/docs/tutorial/testing.md
index 1e333c8f1..f61e62ac5 100644
--- a/docs/en/docs/tutorial/testing.md
+++ b/docs/en/docs/tutorial/testing.md
@@ -1,6 +1,6 @@
# Testing { #testing }
-Thanks to Starlette, testing **FastAPI** applications is easy and enjoyable.
+Thanks to Starlette, testing **FastAPI** applications is easy and enjoyable.
It is based on HTTPX, which in turn is designed based on Requests, so it's very familiar and intuitive.
@@ -30,7 +30,7 @@ Use the `TestClient` object the same way as you do with `httpx`.
Write simple `assert` statements with the standard Python expressions that you need to check (again, standard `pytest`).
-{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
+{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *}
/// tip
@@ -76,7 +76,7 @@ Let's say you have a file structure as described in [Bigger Applications](bigger
In the file `main.py` you have your **FastAPI** app:
-{* ../../docs_src/app_testing/main.py *}
+{* ../../docs_src/app_testing/app_a_py39/main.py *}
### Testing file { #testing-file }
@@ -92,7 +92,7 @@ Then you could have a file `test_main.py` with your tests. It could live on the
Because this file is in the same package, you can use relative imports to import the object `app` from the `main` module (`main.py`):
-{* ../../docs_src/app_testing/test_main.py hl[3] *}
+{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *}
...and have the code for the tests just like before.
@@ -121,63 +121,13 @@ It has a `POST` operation that could return several errors.
Both *path operations* require an `X-Token` header.
-//// 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
-
-Prefer to use the `Annotated` version if possible.
-
-///
-
-```Python
-{!> ../../docs_src/app_testing/app_b_py310/main.py!}
-```
-
-////
-
-//// tab | Python 3.8+ non-Annotated
-
-/// tip
-
-Prefer to use the `Annotated` version if possible.
-
-///
-
-```Python
-{!> ../../docs_src/app_testing/app_b/main.py!}
-```
-
-////
+{* ../../docs_src/app_testing/app_b_an_py310/main.py *}
### Extended testing file { #extended-testing-file }
You could then update `test_main.py` with the extended tests:
-{* ../../docs_src/app_testing/app_b/test_main.py *}
+{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *}
Whenever you need the client to pass information in the request and you don't know how to, you can search (Google) how to do it in `httpx`, or even how to do it with `requests`, as HTTPX's design is based on Requests' design.
diff --git a/docs/en/docs/virtual-environments.md b/docs/en/docs/virtual-environments.md
index e9b0a9fc4..c02e43ab9 100644
--- a/docs/en/docs/virtual-environments.md
+++ b/docs/en/docs/virtual-environments.md
@@ -242,6 +242,26 @@ $ python -m pip install --upgrade pip
+ 
+ lt
+* XWT
+* PSGI
+
+### El abbr da una explicación { #the-abbr-gives-an-explanation }
+
+* clúster
+* Deep Learning
+
+### El abbr da una frase completa y una explicación { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | Info
+
+Los atributos "title" de los elementos "abbr" se traducen siguiendo instrucciones específicas.
+
+Las traducciones pueden añadir sus propios elementos "abbr" que el LLM no debe eliminar. P. ej., para explicar palabras en inglés.
+
+Consulta la sección `### HTML abbr elements` en el prompt general en `scripts/translate.py`.
+
+////
+
+## Encabezados { #headings }
+
+//// tab | Prueba
+
+### Desarrolla una webapp - un tutorial { #develop-a-webapp-a-tutorial }
+
+Hola.
+
+### Anotaciones de tipos y -anotaciones { #type-hints-and-annotations }
+
+Hola de nuevo.
+
+### Superclases y subclases { #super-and-subclasses }
+
+Hola de nuevo.
+
+////
+
+//// tab | Info
+
+La única regla estricta para los encabezados es que el LLM deje la parte del hash dentro de llaves sin cambios, lo que asegura que los enlaces no se rompan.
+
+Consulta la sección `### Headings` en el prompt general en `scripts/translate.py`.
+
+Para instrucciones específicas del idioma, mira p. ej. la sección `### Headings` en `docs/de/llm-prompt.md`.
+
+////
+
+## Términos usados en la documentación { #terms-used-in-the-docs }
+
+//// tab | Prueba
+
+* tú
+* tu
+
+* p. ej.
+* etc.
+
+* `foo` como un `int`
+* `bar` como un `str`
+* `baz` como una `list`
+
+* el Tutorial - Guía de usuario
+* la Guía de usuario avanzada
+* la documentación de SQLModel
+* la documentación de la API
+* la documentación automática
+
+* Ciencia de datos
+* Deep Learning
+* Machine Learning
+* Inyección de dependencias
+* autenticación HTTP Basic
+* HTTP Digest
+* formato ISO
+* el estándar JSON Schema
+* el JSON Schema
+* la definición del esquema
+* Flujo de contraseña
+* Móvil
+
+* obsoleto
+* diseñado
+* inválido
+* sobre la marcha
+* estándar
+* por defecto
+* sensible a mayúsculas/minúsculas
+* insensible a mayúsculas/minúsculas
+
+* servir la aplicación
+* servir la página
+
+* la app
+* la aplicación
+
+* la request
+* la response
+* la response de error
+
+* la path operation
+* el decorador de path operation
+* la path operation function
+
+* el body
+* el request body
+* el response body
+* el body JSON
+* el body del formulario
+* el body de archivo
+* el cuerpo de la función
+
+* el parámetro
+* el parámetro del body
+* el parámetro del path
+* el parámetro de query
+* el parámetro de cookie
+* el parámetro de header
+* el parámetro del formulario
+* el parámetro de la función
+
+* el evento
+* el evento de inicio
+* el inicio del servidor
+* el evento de apagado
+* el evento de lifespan
+
+* el manejador
+* el manejador de eventos
+* el manejador de excepciones
+* manejar
+
+* el modelo
+* el modelo de Pydantic
+* el modelo de datos
+* el modelo de base de datos
+* el modelo de formulario
+* el objeto del modelo
+
+* la clase
+* la clase base
+* la clase padre
+* la subclase
+* la clase hija
+* la clase hermana
+* el método de clase
+
+* el header
+* los headers
+* el header de autorización
+* el header `Authorization`
+* el header forwarded
+
+* el sistema de inyección de dependencias
+* la dependencia
+* el dependable
+* el dependiente
+
+* limitado por I/O
+* limitado por CPU
+* concurrencia
+* paralelismo
+* multiprocesamiento
+
+* la env var
+* la variable de entorno
+* el `PATH`
+* la variable `PATH`
+
+* la autenticación
+* el proveedor de autenticación
+* la autorización
+* el formulario de autorización
+* el proveedor de autorización
+* el usuario se autentica
+* el sistema autentica al usuario
+
+* la CLI
+* la interfaz de línea de comandos
+
+* el servidor
+* el cliente
+
+* el proveedor en la nube
+* el servicio en la nube
+
+* el desarrollo
+* las etapas de desarrollo
+
+* el dict
+* el diccionario
+* la enumeración
+* el enum
+* el miembro del enum
+
+* el codificador
+* el decodificador
+* codificar
+* decodificar
+
+* la excepción
+* lanzar
+
+* la expresión
+* el statement
+
+* el frontend
+* el backend
+
+* la discusión de GitHub
+* el issue de GitHub
+
+* el rendimiento
+* la optimización de rendimiento
+
+* el tipo de retorno
+* el valor de retorno
+
+* la seguridad
+* el esquema de seguridad
+
+* la tarea
+* la tarea en segundo plano
+* la función de tarea
+
+* la plantilla
+* el motor de plantillas
+
+* la anotación de tipos
+* las anotaciones de tipos
+
+* el worker del servidor
+* el worker de Uvicorn
+* el Gunicorn Worker
+* el worker process
+* la worker class
+* la carga de trabajo
+
+* el despliegue
+* desplegar
+
+* el SDK
+* el kit de desarrollo de software
+
+* el `APIRouter`
+* el `requirements.txt`
+* el Bearer Token
+* el cambio incompatible
+* el bug
+* el botón
+* el invocable
+* el código
+* el commit
+* el context manager
+* la corrutina
+* la sesión de base de datos
+* el disco
+* el dominio
+* el motor
+* el X falso
+* el método HTTP GET
+* el ítem
+* el paquete
+* el lifespan
+* el lock
+* el middleware
+* la aplicación móvil
+* el módulo
+* el montaje
+* la red
+* el origen
+* el override
+* el payload
+* el procesador
+* la propiedad
+* el proxy
+* el pull request
+* la query
+* la RAM
+* la máquina remota
+* el código de estado
+* el string
+* la etiqueta
+* el framework web
+* el comodín
+* devolver
+* validar
+
+////
+
+//// tab | Info
+
+Esta es una lista no completa y no normativa de términos (mayormente) técnicos vistos en la documentación. Puede ayudar a la persona que diseña el prompt a identificar para qué términos el LLM necesita una mano. Por ejemplo cuando sigue revirtiendo una buena traducción a una traducción subóptima. O cuando tiene problemas conjugando/declinando un término en tu idioma.
+
+Mira p. ej. la sección `### List of English terms and their preferred German translations` en `docs/de/llm-prompt.md`.
+
+////
diff --git a/docs/es/docs/about/index.md b/docs/es/docs/about/index.md
index e83400a8d..fa152c62d 100644
--- a/docs/es/docs/about/index.md
+++ b/docs/es/docs/about/index.md
@@ -1,3 +1,3 @@
-# Acerca de
+# Acerca de { #about }
Acerca de FastAPI, su diseño, inspiración y más. 🤓
diff --git a/docs/es/docs/advanced/additional-responses.md b/docs/es/docs/advanced/additional-responses.md
index 7788bccd9..d0baa97a4 100644
--- a/docs/es/docs/advanced/additional-responses.md
+++ b/docs/es/docs/advanced/additional-responses.md
@@ -1,4 +1,4 @@
-# Responses Adicionales en OpenAPI
+# Responses Adicionales en OpenAPI { #additional-responses-in-openapi }
/// warning | Advertencia
@@ -14,7 +14,7 @@ Esos responses adicionales se incluirán en el esquema de OpenAPI, por lo que ta
Pero para esos responses adicionales tienes que asegurarte de devolver un `Response` como `JSONResponse` directamente, con tu código de estado y contenido.
-## Response Adicional con `model`
+## Response Adicional con `model` { #additional-response-with-model }
Puedes pasar a tus *decoradores de path operation* un parámetro `responses`.
@@ -26,7 +26,7 @@ Cada uno de esos `dict`s de response puede tener una clave `model`, conteniendo
Por ejemplo, para declarar otro response con un código de estado `404` y un modelo Pydantic `Message`, puedes escribir:
-{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
+{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
/// note | Nota
@@ -169,13 +169,13 @@ Los esquemas se referencian a otro lugar dentro del esquema de OpenAPI:
}
```
-## Media types adicionales para el response principal
+## Media types adicionales para el response principal { #additional-media-types-for-the-main-response }
Puedes usar este mismo parámetro `responses` para agregar diferentes media type para el mismo response principal.
Por ejemplo, puedes agregar un media type adicional de `image/png`, declarando que tu *path operation* puede devolver un objeto JSON (con media type `application/json`) o una imagen PNG:
-{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
+{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
/// note | Nota
@@ -191,25 +191,25 @@ Pero si has especificado una clase de response personalizada con `None` como su
///
-## Combinando información
+## Combinando información { #combining-information }
También puedes combinar información de response de múltiples lugares, incluyendo los parámetros `response_model`, `status_code`, y `responses`.
-Puedes declarar un `response_model`, usando el código de estado predeterminado `200` (o uno personalizado si lo necesitas), y luego declarar información adicional para ese mismo response en `responses`, directamente en el esquema de OpenAPI.
+Puedes declarar un `response_model`, usando el código de estado por defecto `200` (o uno personalizado si lo necesitas), y luego declarar información adicional para ese mismo response en `responses`, directamente en el esquema de OpenAPI.
-**FastAPI** manterá la información adicional de `responses` y la combinará con el JSON Schema de tu modelo.
+**FastAPI** mantendrá la información adicional de `responses` y la combinará con el JSON Schema de tu modelo.
Por ejemplo, puedes declarar un response con un código de estado `404` que usa un modelo Pydantic y tiene una `description` personalizada.
Y un response con un código de estado `200` que usa tu `response_model`, pero incluye un `example` personalizado:
-{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
+{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
Todo se combinará e incluirá en tu OpenAPI, y se mostrará en la documentación de la API:
-## Combina responses predefinidos y personalizados
+## Combina responses predefinidos y personalizados { #combine-predefined-responses-and-custom-ones }
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*.
@@ -237,9 +237,9 @@ Puedes usar esa técnica para reutilizar algunos responses predefinidos en tus *
Por ejemplo:
-{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
-## Más información sobre responses OpenAPI
+## Más información sobre responses OpenAPI { #more-information-about-openapi-responses }
Para ver exactamente qué puedes incluir en los responses, puedes revisar estas secciones en la especificación OpenAPI:
diff --git a/docs/es/docs/advanced/additional-status-codes.md b/docs/es/docs/advanced/additional-status-codes.md
index df7737aac..9adfa65cf 100644
--- a/docs/es/docs/advanced/additional-status-codes.md
+++ b/docs/es/docs/advanced/additional-status-codes.md
@@ -1,10 +1,10 @@
-# Códigos de Estado Adicionales
+# Códigos de Estado Adicionales { #additional-status-codes }
Por defecto, **FastAPI** devolverá los responses usando un `JSONResponse`, colocando el contenido que devuelves desde tu *path operation* dentro de ese `JSONResponse`.
Usará el código de estado por defecto o el que configures en tu *path operation*.
-## Códigos de estado adicionales
+## Códigos de estado adicionales { #additional-status-codes_1 }
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.
@@ -34,7 +34,7 @@ También podrías usar `from starlette.responses import JSONResponse`.
///
-## OpenAPI y documentación de API
+## OpenAPI y documentación de API { #openapi-and-api-docs }
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.
diff --git a/docs/es/docs/advanced/advanced-dependencies.md b/docs/es/docs/advanced/advanced-dependencies.md
index dd3c63a37..622a2caa2 100644
--- a/docs/es/docs/advanced/advanced-dependencies.md
+++ b/docs/es/docs/advanced/advanced-dependencies.md
@@ -1,6 +1,6 @@
-# Dependencias Avanzadas
+# Dependencias Avanzadas { #advanced-dependencies }
-## Dependencias con parámetros
+## Dependencias con parámetros { #parameterized-dependencies }
Todas las dependencias que hemos visto son una función o clase fija.
@@ -10,7 +10,7 @@ Imaginemos que queremos tener una dependencia que revise si el parámetro de que
Pero queremos poder parametrizar ese contenido fijo.
-## Una *instance* "callable"
+## Una *instance* "callable" { #a-callable-instance }
En Python hay una forma de hacer que una instance de una clase sea un "callable".
@@ -22,7 +22,7 @@ Para hacer eso, declaramos un método `__call__`:
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
+## Parametrizar la instance { #parameterize-the-instance }
Y ahora, podemos usar `__init__` para declarar los parámetros de la instance que podemos usar para "parametrizar" la dependencia:
@@ -30,7 +30,7 @@ Y ahora, podemos usar `__init__` para declarar los parámetros de la instance qu
En este caso, **FastAPI** nunca tocará ni se preocupará por `__init__`, lo usaremos directamente en nuestro código.
-## Crear una instance
+## Crear una instance { #create-an-instance }
Podríamos crear una instance de esta clase con:
@@ -38,7 +38,7 @@ Podríamos crear una instance de esta clase con:
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
+## Usar la instance como una dependencia { #use-the-instance-as-a-dependency }
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í.
@@ -63,3 +63,101 @@ En los capítulos sobre seguridad, hay funciones utilitarias que se implementan
Si entendiste todo esto, ya sabes cómo funcionan por debajo esas herramientas de utilidad para seguridad.
///
+
+## Dependencias con `yield`, `HTTPException`, `except` y Tareas en segundo plano { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | Advertencia
+
+Muy probablemente no necesites estos detalles técnicos.
+
+Estos detalles son útiles principalmente si tenías una aplicación de FastAPI anterior a la 0.121.0 y estás enfrentando problemas con dependencias con `yield`.
+
+///
+
+Las dependencias con `yield` han evolucionado con el tiempo para cubrir diferentes casos de uso y arreglar algunos problemas; aquí tienes un resumen de lo que ha cambiado.
+
+### Dependencias con `yield` y `scope` { #dependencies-with-yield-and-scope }
+
+En la versión 0.121.0, FastAPI agregó soporte para `Depends(scope="function")` para dependencias con `yield`.
+
+Usando `Depends(scope="function")`, el código de salida después de `yield` se ejecuta justo después de que la *path operation function* termina, antes de que la response se envíe de vuelta al cliente.
+
+Y al usar `Depends(scope="request")` (el valor por defecto), el código de salida después de `yield` se ejecuta después de que la response es enviada.
+
+Puedes leer más al respecto en la documentación de [Dependencias con `yield` - Salida temprana y `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).
+
+### Dependencias con `yield` y `StreamingResponse`, detalles técnicos { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+Antes de FastAPI 0.118.0, si usabas una dependencia con `yield`, ejecutaba el código de salida después de que la *path operation function* retornaba pero justo antes de enviar la response.
+
+La intención era evitar retener recursos por más tiempo del necesario, esperando a que la response viajara por la red.
+
+Este cambio también significaba que si retornabas un `StreamingResponse`, el código de salida de la dependencia con `yield` ya se habría ejecutado.
+
+Por ejemplo, si tenías una sesión de base de datos en una dependencia con `yield`, el `StreamingResponse` no podría usar esa sesión mientras hace streaming de datos porque la sesión ya se habría cerrado en el código de salida después de `yield`.
+
+Este comportamiento se revirtió en la 0.118.0, para hacer que el código de salida después de `yield` se ejecute después de que la response sea enviada.
+
+/// info | Información
+
+Como verás abajo, esto es muy similar al comportamiento anterior a la versión 0.106.0, pero con varias mejoras y arreglos de bugs para casos límite.
+
+///
+
+#### Casos de uso con salida temprana del código { #use-cases-with-early-exit-code }
+
+Hay algunos casos de uso con condiciones específicas que podrían beneficiarse del comportamiento antiguo de ejecutar el código de salida de dependencias con `yield` antes de enviar la response.
+
+Por ejemplo, imagina que tienes código que usa una sesión de base de datos en una dependencia con `yield` solo para verificar un usuario, pero la sesión de base de datos no se vuelve a usar en la *path operation function*, solo en la dependencia, y la response tarda mucho en enviarse, como un `StreamingResponse` que envía datos lentamente, pero que por alguna razón no usa la base de datos.
+
+En este caso, la sesión de base de datos se mantendría hasta que la response termine de enviarse, pero si no la usas, entonces no sería necesario mantenerla.
+
+Así es como se vería:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+El código de salida, el cierre automático de la `Session` en:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+...se ejecutaría después de que la response termine de enviar los datos lentos:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+Pero como `generate_stream()` no usa la sesión de base de datos, no es realmente necesario mantener la sesión abierta mientras se envía la response.
+
+Si tienes este caso de uso específico usando SQLModel (o SQLAlchemy), podrías cerrar explícitamente la sesión después de que ya no la necesites:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+De esa manera la sesión liberaría la conexión a la base de datos, para que otras requests puedan usarla.
+
+Si tienes un caso de uso diferente que necesite salir temprano desde una dependencia con `yield`, por favor crea una Pregunta de Discusión en GitHub con tu caso de uso específico y por qué te beneficiaría tener cierre temprano para dependencias con `yield`.
+
+Si hay casos de uso convincentes para el cierre temprano en dependencias con `yield`, consideraría agregar una nueva forma de optar por el cierre temprano.
+
+### Dependencias con `yield` y `except`, detalles técnicos { #dependencies-with-yield-and-except-technical-details }
+
+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 elevar la excepción, la excepción se elevaría/remitiría automáticamente a cualquier manejador de excepciones o al manejador de error interno del servidor.
+
+Esto cambió en la versión 0.110.0 para arreglar consumo de memoria no manejado por excepciones reenviadas sin un manejador (errores internos del servidor), y para hacerlo consistente con el comportamiento del código Python normal.
+
+### Tareas en segundo plano y dependencias con `yield`, detalles técnicos { #background-tasks-and-dependencies-with-yield-technical-details }
+
+Antes de FastAPI 0.106.0, elevar excepciones después de `yield` no era posible, el código de salida en dependencias con `yield` se ejecutaba después de que la response era enviada, por lo que [Manejadores de Excepciones](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} ya habrían corrido.
+
+Esto se diseñó así principalmente para permitir usar los mismos objetos devueltos con `yield` por las dependencias dentro de tareas en segundo plano, porque el código de salida se ejecutaría después de que las tareas en segundo plano terminaran.
+
+Esto cambió en FastAPI 0.106.0 con la intención de no retener recursos mientras se espera a que la response viaje por la red.
+
+/// tip | Consejo
+
+Adicionalmente, una tarea en segundo plano normalmente es un conjunto independiente de lógica que debería manejarse por separado, con sus propios recursos (por ejemplo, su propia conexión a la base de datos).
+
+Así, probablemente tendrás un código más limpio.
+
+///
+
+Si solías depender de este comportamiento, ahora deberías crear los recursos para las tareas en segundo plano dentro de la propia tarea en segundo plano, y usar internamente solo datos que no dependan de los recursos de 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 segundo plano, y obtendrías los objetos de la base de datos usando esta nueva sesión. Y entonces, en lugar de pasar el objeto de la base de datos como parámetro a la función de la tarea en segundo plano, pasarías el ID de ese objeto y luego obtendrías el objeto de nuevo dentro de la función de la tarea en segundo plano.
diff --git a/docs/es/docs/advanced/async-tests.md b/docs/es/docs/advanced/async-tests.md
index f89db1533..4627e9bd1 100644
--- a/docs/es/docs/advanced/async-tests.md
+++ b/docs/es/docs/advanced/async-tests.md
@@ -1,4 +1,4 @@
-# Tests Asíncronos
+# Tests Asíncronos { #async-tests }
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`.
@@ -6,11 +6,11 @@ Poder usar funciones asíncronas en tus tests puede ser útil, por ejemplo, cuan
Veamos cómo podemos hacer que esto funcione.
-## pytest.mark.anyio
+## pytest.mark.anyio { #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
+## HTTPX { #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.
@@ -18,7 +18,7 @@ El `TestClient` hace algo de magia interna para llamar a la aplicación FastAPI
El `TestClient` está basado en HTTPX, y afortunadamente, podemos usarlo directamente para probar la API.
-## Ejemplo
+## Ejemplo { #example }
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}:
@@ -32,13 +32,13 @@ Para un ejemplo simple, consideremos una estructura de archivos similar a la des
El archivo `main.py` tendría:
-{* ../../docs_src/async_tests/main.py *}
+{* ../../docs_src/async_tests/app_a_py39/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 *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py *}
-## Ejecútalo
+## Ejecútalo { #run-it }
Puedes ejecutar tus tests como de costumbre vía:
@@ -52,21 +52,21 @@ $ pytest
-## En Detalle
+## En Detalle { #in-detail }
El marcador `@pytest.mark.anyio` le dice a pytest que esta función de test debe ser llamada asíncronamente:
-{* ../../docs_src/async_tests/test_main.py hl[7] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[7] *}
/// tip | Consejo
-Note que la función de test ahora es `async def` en lugar de solo `def` como antes al usar el `TestClient`.
+Nota que la función de test ahora es `async def` en lugar de solo `def` como antes al usar el `TestClient`.
///
Luego podemos crear un `AsyncClient` con la app y enviar requests asíncronos a ella, usando `await`.
-{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[9:12] *}
Esto es equivalente a:
@@ -88,12 +88,12 @@ Si tu aplicación depende de eventos de lifespan, el `AsyncClient` no activará
///
-## Otras Llamadas a Funciones Asíncronas
+## Otras Llamadas a Funciones Asíncronas { #other-asynchronous-function-calls }
Al ser la función de test asíncrona, ahora también puedes llamar (y `await`) otras funciones `async` además de enviar requests a tu aplicación FastAPI en tus tests, exactamente como las llamarías en cualquier otro lugar de tu código.
/// tip | Consejo
-Si encuentras un `RuntimeError: Task attached to a different loop` al integrar llamadas a funciones asíncronas en tus tests (por ejemplo, cuando usas MotorClient de MongoDB), recuerda crear instances de objetos que necesiten un loop de eventos solo dentro de funciones async, por ejemplo, en un callback `'@app.on_event("startup")`.
+Si encuentras un `RuntimeError: Task attached to a different loop` al integrar llamadas a funciones asíncronas en tus tests (por ejemplo, cuando usas MotorClient de MongoDB), recuerda crear instances de objetos que necesiten un loop de eventos solo dentro de funciones async, por ejemplo, en un callback `@app.on_event("startup")`.
///
diff --git a/docs/es/docs/advanced/behind-a-proxy.md b/docs/es/docs/advanced/behind-a-proxy.md
index 8c590cbe8..f81c16ee8 100644
--- a/docs/es/docs/advanced/behind-a-proxy.md
+++ b/docs/es/docs/advanced/behind-a-proxy.md
@@ -1,6 +1,105 @@
-# Detrás de un Proxy
+# Detrás de un Proxy { #behind-a-proxy }
-En algunas situaciones, podrías necesitar usar un **proxy** como Traefik o Nginx con una configuración que añade un prefijo de path extra que no es visto por tu aplicación.
+En muchas situaciones, usarías un **proxy** como Traefik o Nginx delante de tu app de FastAPI.
+
+Estos proxies podrían manejar certificados HTTPS y otras cosas.
+
+## Headers reenviados por el Proxy { #proxy-forwarded-headers }
+
+Un **proxy** delante de tu aplicación normalmente establecería algunos headers sobre la marcha antes de enviar los requests a tu **server** para que el servidor sepa que el request fue **reenviado** por el proxy, informándole la URL original (pública), incluyendo el dominio, que está usando HTTPS, etc.
+
+El programa **server** (por ejemplo **Uvicorn** a través de **FastAPI CLI**) es capaz de interpretar esos headers, y luego pasar esa información a tu aplicación.
+
+Pero por seguridad, como el server no sabe que está detrás de un proxy confiable, no interpretará esos headers.
+
+/// note | Detalles Técnicos
+
+Los headers del proxy son:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+### Habilitar headers reenviados por el Proxy { #enable-proxy-forwarded-headers }
+
+Puedes iniciar FastAPI CLI con la *Opción de CLI* `--forwarded-allow-ips` y pasar las direcciones IP que deberían ser confiables para leer esos headers reenviados.
+
+Si lo estableces a `--forwarded-allow-ips="*"`, confiaría en todas las IPs entrantes.
+
+Si tu **server** está detrás de un **proxy** confiable y solo el proxy le habla, esto haría que acepte cualquiera que sea la IP de ese **proxy**.
+
+
-## Responses disponibles
+## Responses disponibles { #available-responses }
Aquí hay algunos de los responses disponibles.
@@ -121,7 +121,7 @@ También podrías usar `from starlette.responses import HTMLResponse`.
///
-### `Response`
+### `Response` { #response }
La clase principal `Response`, todos los otros responses heredan de ella.
@@ -136,25 +136,25 @@ Acepta los siguientes parámetros:
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] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-### `HTMLResponse`
+### `HTMLResponse` { #htmlresponse }
Toma algún texto o bytes y devuelve un response HTML, como leíste arriba.
-### `PlainTextResponse`
+### `PlainTextResponse` { #plaintextresponse }
Toma algún texto o bytes y devuelve un response de texto plano.
-{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
-### `JSONResponse`
+### `JSONResponse` { #jsonresponse }
Toma algunos datos y devuelve un response codificado como `application/json`.
-Este es el response predeterminado usado en **FastAPI**, como leíste arriba.
+Este es el response usado por defecto en **FastAPI**, como leíste arriba.
-### `ORJSONResponse`
+### `ORJSONResponse` { #orjsonresponse }
Un response JSON rápido alternativo usando `orjson`, como leíste arriba.
@@ -164,7 +164,7 @@ Esto requiere instalar `orjson`, por ejemplo, con `pip install orjson`.
///
-### `UJSONResponse`
+### `UJSONResponse` { #ujsonresponse }
Un response JSON alternativo usando `ujson`.
@@ -180,7 +180,7 @@ Esto requiere instalar `ujson`, por ejemplo, con `pip install ujson`.
///
-{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *}
/// tip | Consejo
@@ -188,45 +188,45 @@ Es posible que `ORJSONResponse` sea una alternativa más rápida.
///
-### `RedirectResponse`
+### `RedirectResponse` { #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] *}
+{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *}
---
O puedes usarlo en el parámetro `response_class`:
-{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006b_py39.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`.
+En este caso, el `status_code` utilizado será el por defecto 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] *}
+{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *}
-### `StreamingResponse`
+### `StreamingResponse` { #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] *}
+{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *}
-#### Usando `StreamingResponse` con objetos similares a archivos
+#### Usando `StreamingResponse` con objetos similares a archivos { #using-streamingresponse-with-file-like-objects }
-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.
+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] *}
+{* ../../docs_src/custom_response/tutorial008_py39.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.
@@ -242,7 +242,7 @@ Nota que aquí como estamos usando `open()` estándar que no admite `async` y `a
///
-### `FileResponse`
+### `FileResponse` { #fileresponse }
Transmite un archivo asincrónicamente como response.
@@ -255,15 +255,15 @@ Toma un conjunto diferente de argumentos para crear un instance que los otros ti
Los responses de archivos incluirán los headers apropiados `Content-Length`, `Last-Modified` y `ETag`.
-{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *}
También puedes usar el parámetro `response_class`:
-{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *}
En este caso, puedes devolver la path del archivo directamente desde tu *path operation* function.
-## Clase de response personalizada
+## Clase de response personalizada { #custom-response-class }
Puedes crear tu propia clase de response personalizada, heredando de `Response` y usándola.
@@ -273,7 +273,7 @@ Digamos que quieres que devuelva JSON con sangría y formato, por lo que quieres
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] *}
+{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *}
Ahora en lugar de devolver:
@@ -291,7 +291,7 @@ Ahora en lugar de devolver:
Por supuesto, probablemente encontrarás formas mucho mejores de aprovechar esto que formatear JSON. 😉
-## Clase de response predeterminada
+## Clase de response por defecto { #default-response-class }
Al crear una instance de la clase **FastAPI** o un `APIRouter`, puedes especificar qué clase de response usar por defecto.
@@ -299,7 +299,7 @@ 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] *}
+{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *}
/// tip | Consejo
@@ -307,6 +307,6 @@ Todavía puedes sobrescribir `response_class` en *path operations* como antes.
///
-## Documentación adicional
+## Documentación adicional { #additional-documentation }
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
index 0ca1fd3b6..3a07482ad 100644
--- a/docs/es/docs/advanced/dataclasses.md
+++ b/docs/es/docs/advanced/dataclasses.md
@@ -1,10 +1,10 @@
-# Usando Dataclasses
+# Usando Dataclasses { #using-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] *}
+{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
Esto sigue siendo soportado gracias a **Pydantic**, ya que tiene soporte interno para `dataclasses`.
@@ -28,11 +28,11 @@ Pero si tienes un montón de dataclasses por ahí, este es un buen truco para us
///
-## Dataclasses en `response_model`
+## Dataclasses en `response_model` { #dataclasses-in-response-model }
También puedes usar `dataclasses` en el parámetro `response_model`:
-{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}
El dataclass será automáticamente convertido a un dataclass de Pydantic.
@@ -40,7 +40,7 @@ De esta manera, su esquema aparecerá en la interfaz de usuario de la documentac
-## Dataclasses en Estructuras de Datos Anidadas
+## Dataclasses en Estructuras de Datos Anidadas { #dataclasses-in-nested-data-structures }
También puedes combinar `dataclasses` con otras anotaciones de tipos para crear estructuras de datos anidadas.
@@ -48,7 +48,7 @@ En algunos casos, todavía podrías tener que usar la versión de `dataclasses`
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] *}
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
1. Todavía importamos `field` de los `dataclasses` estándar.
@@ -64,7 +64,7 @@ En ese caso, simplemente puedes intercambiar los `dataclasses` estándar con `py
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.
+ 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`.
@@ -84,12 +84,12 @@ Puedes combinar `dataclasses` con otras anotaciones de tipos en muchas combinaci
Revisa las anotaciones en el código arriba para ver más detalles específicos.
-## Aprende Más
+## Aprende Más { #learn-more }
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
+## Versión { #version }
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
index 022fb5a42..c2002a6f5 100644
--- a/docs/es/docs/advanced/events.md
+++ b/docs/es/docs/advanced/events.md
@@ -1,4 +1,4 @@
-# Eventos de Lifespan
+# Eventos de Lifespan { #lifespan-events }
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**.
@@ -8,7 +8,7 @@ Debido a que este código se ejecuta antes de que la aplicación **comience** a
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
+## Caso de Uso { #use-case }
Empecemos con un ejemplo de **caso de uso** y luego veamos cómo resolverlo con esto.
@@ -22,7 +22,7 @@ Podrías cargarlo en el nivel superior del módulo/archivo, pero eso también si
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
+## Lifespan { #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).
@@ -30,7 +30,7 @@ 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] *}
+{* ../../docs_src/events/tutorial003_py39.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*.
@@ -44,25 +44,25 @@ Quizás necesites iniciar una nueva versión, o simplemente te cansaste de ejecu
///
-### Función de Lifespan
+### Función de Lifespan { #lifespan-function }
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] *}
+{* ../../docs_src/events/tutorial003_py39.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
+### Async Context Manager { #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] *}
+{* ../../docs_src/events/tutorial003_py39.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:
+Un **context manager** en Python es algo que puedes usar en un statement `with`, por ejemplo, `open()` puede ser usado como un context manager:
```Python
with open("file.txt") as file:
@@ -82,9 +82,9 @@ En nuestro ejemplo de código arriba, no lo usamos directamente, pero se lo pasa
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] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[22] *}
-## Eventos Alternativos (obsoleto)
+## Eventos Alternativos (obsoleto) { #alternative-events-deprecated }
/// warning | Advertencia
@@ -100,11 +100,11 @@ Puedes definir manejadores de eventos (funciones) que necesitan ser ejecutadas a
Estas funciones pueden ser declaradas con `async def` o `def` normal.
-### Evento `startup`
+### Evento `startup` { #startup-event }
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] *}
+{* ../../docs_src/events/tutorial001_py39.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.
@@ -112,11 +112,11 @@ 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`
+### Evento `shutdown` { #shutdown-event }
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] *}
+{* ../../docs_src/events/tutorial002_py39.py hl[6] *}
Aquí, la función manejadora del evento `shutdown` escribirá una línea de texto `"Application shutdown"` a un archivo `log.txt`.
@@ -138,7 +138,7 @@ Por eso, declaramos la función manejadora del evento con `def` estándar en vez
///
-### `startup` y `shutdown` juntos
+### `startup` y `shutdown` juntos { #startup-and-shutdown-together }
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.
@@ -146,7 +146,7 @@ Hacer eso en funciones separadas que no comparten lógica o variables juntas es
Debido a eso, ahora se recomienda en su lugar usar el `lifespan` como se explicó arriba.
-## Detalles Técnicos
+## Detalles Técnicos { #technical-details }
Solo un detalle técnico para los nerds curiosos. 🤓
@@ -154,12 +154,12 @@ Por debajo, en la especificación técnica ASGI, esto es parte del la documentación de `Lifespan` de Starlette.
+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
+## Sub Aplicaciones { #sub-applications }
🚨 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
index b664bceac..daf6cefed 100644
--- a/docs/es/docs/advanced/generate-clients.md
+++ b/docs/es/docs/advanced/generate-clients.md
@@ -1,115 +1,76 @@
-# Genera Clientes
+# Generando SDKs { #generating-sdks }
-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).
+Como **FastAPI** está basado en la especificación **OpenAPI**, sus APIs se pueden describir en un formato estándar que muchas herramientas entienden.
-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.
+Esto facilita generar **documentación** actualizada, paquetes de cliente (**SDKs**) en múltiples lenguajes y **escribir pruebas** o **flujos de automatización** que se mantengan sincronizados con tu código.
-## Generadores de Clientes OpenAPI
+En esta guía, aprenderás a generar un **SDK de TypeScript** para tu backend con FastAPI.
-Hay muchas herramientas para generar clientes desde **OpenAPI**.
+## Generadores de SDKs de código abierto { #open-source-sdk-generators }
-Una herramienta común es OpenAPI Generator.
+Una opción versátil es el OpenAPI Generator, que soporta **muchos lenguajes de programación** y puede generar SDKs a partir de tu especificación OpenAPI.
-Si estás construyendo un **frontend**, una alternativa muy interesante es openapi-ts.
+Para **clientes de TypeScript**, Hey API es una solución diseñada específicamente, que ofrece una experiencia optimizada para el ecosistema de TypeScript.
-## Generadores de Clientes y SDKs - Sponsor
+Puedes descubrir más generadores de SDK en OpenAPI.Tools.
-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.
+/// tip | Consejo
+
+FastAPI genera automáticamente especificaciones **OpenAPI 3.1**, así que cualquier herramienta que uses debe soportar esta versión.
+
+///
+
+## Generadores de SDKs de sponsors de FastAPI { #sdk-generators-from-fastapi-sponsors }
+
+Esta sección destaca soluciones **respaldadas por empresas** y **venture-backed** de compañías que sponsorean FastAPI. Estos productos ofrecen **funcionalidades adicionales** e **integraciones** además de SDKs 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**.
+Al ✨ [**sponsorear FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, estas compañías ayudan a asegurar que el framework y su **ecosistema** se mantengan saludables y **sustentables**.
-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. 🙇
+Su sponsorship también demuestra un fuerte compromiso con la **comunidad** de FastAPI (tú), mostrando que no solo les importa ofrecer un **gran servicio**, sino también apoyar un **framework robusto y próspero**, FastAPI. 🙇
Por ejemplo, podrías querer probar:
* Speakeasy
-* Stainless
-* liblab
+* Stainless
+* liblab
-También hay varias otras empresas que ofrecen servicios similares que puedes buscar y encontrar en línea. 🤓
+Algunas de estas soluciones también pueden ser open source u ofrecer niveles gratuitos, así que puedes probarlas sin un compromiso financiero. Hay otros generadores de SDK comerciales disponibles y se pueden encontrar en línea. 🤓
-## Genera un Cliente Frontend en TypeScript
+## Crea un SDK de TypeScript { #create-a-typescript-sdk }
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`.
+Nota que las *path operations* definen los modelos que usan para el payload del request y el payload del response, usando los modelos `Item` y `ResponseMessage`.
-### Documentación de la API
+### Documentación de la API { #api-docs }
-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:
+Si vas a `/docs`, verás que tiene los **esquemas** para los datos a enviar en requests y recibir en responses:
-Puedes ver esos esquemas porque fueron declarados con los modelos en la aplicación.
+Puedes ver esos esquemas porque fueron declarados con los modelos en la app.
-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).
+Esa información está disponible en el **OpenAPI schema** de la app, y luego se muestra en la documentación de la API.
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:
-
-
@@ -131,17 +92,17 @@ El objeto de response también tendrá autocompletado:
-## App de FastAPI con Tags
+## App de FastAPI con tags { #fastapi-app-with-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*.
+En muchos casos tu app 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:
+Por ejemplo, podrías tener una sección para **items** y otra sección para **users**, y podrían estar separadas por tags:
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
-### Genera un Cliente TypeScript con Tags
+### Genera un Cliente TypeScript con tags { #generate-a-typescript-client-with-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.
+Si generas un cliente para una app 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:
@@ -152,7 +113,7 @@ En este caso tienes:
* `ItemsService`
* `UsersService`
-### Nombres de los Métodos del Cliente
+### Nombres de los métodos del cliente { #client-method-names }
Ahora mismo los nombres de los métodos generados como `createItemItemsPost` no se ven muy limpios:
@@ -166,15 +127,15 @@ OpenAPI requiere que cada operation ID sea único a través de todas las *path o
Pero te mostraré cómo mejorar eso a continuación. 🤓
-## Operation IDs Personalizados y Mejores Nombres de Métodos
+## Operation IDs personalizados y mejores nombres de métodos { #custom-operation-ids-and-better-method-names }
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).
+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 **name** de la *path operation* (el nombre de la función).
-### Función Personalizada para Generar ID Único
+### Función personalizada para generar ID único { #custom-generate-unique-id-function }
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.
@@ -186,15 +147,15 @@ Puedes entonces pasar esa función personalizada a **FastAPI** como el parámetr
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
-### Generar un Cliente TypeScript con Operation IDs Personalizados
+### Genera un Cliente TypeScript con operation IDs personalizados { #generate-a-typescript-client-with-custom-operation-ids }
-Ahora si generas el cliente de nuevo, verás que tiene los nombres de métodos mejorados:
+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
+### Preprocesa la especificación OpenAPI para el generador de clientes { #preprocess-the-openapi-specification-for-the-client-generator }
El código generado aún tiene algo de **información duplicada**.
@@ -206,7 +167,7 @@ Pero para el cliente generado podríamos **modificar** los operation IDs de Open
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 *}
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
//// tab | Node.js
@@ -218,44 +179,30 @@ Podríamos descargar el JSON de OpenAPI a un archivo `openapi.json` y luego podr
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"
- }
-}
+### Genera un Cliente TypeScript con el OpenAPI preprocesado { #generate-a-typescript-client-with-the-preprocessed-openapi }
+
+Como el resultado final ahora está en un archivo `openapi.json`, necesitas actualizar la ubicación de la entrada:
+
+```sh
+npx @hey-api/openapi-ts -i ./openapi.json -o src/client
```
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
+## Beneficios { #benefits }
-Cuando usas los clientes generados automáticamente obtendrás **autocompletado** para:
+Cuando uses 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.
+* Payloads de request en el body, parámetros de query, etc.
+* Payloads de response.
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.
+Esto también significa que si algo cambió será **reflejado** automáticamente en el código del cliente. Y si haces **build** del cliente, 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 0626a1563..f3f4bb85c 100644
--- a/docs/es/docs/advanced/index.md
+++ b/docs/es/docs/advanced/index.md
@@ -1,6 +1,6 @@
-# Guía avanzada del usuario
+# Guía avanzada del usuario { #advanced-user-guide }
-## Funcionalidades adicionales
+## Funcionalidades adicionales { #additional-features }
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**.
@@ -14,23 +14,8 @@ Y es posible que para tu caso de uso, la solución esté en una de ellas.
///
-## Lee primero el Tutorial
+## Lee primero el Tutorial { #read-the-tutorial-first }
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.
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
index b8fd86185..7eead8ae1 100644
--- a/docs/es/docs/advanced/middleware.md
+++ b/docs/es/docs/advanced/middleware.md
@@ -1,4 +1,4 @@
-# Middleware Avanzado
+# Middleware Avanzado { #advanced-middleware }
En el tutorial principal leíste cómo agregar [Middleware Personalizado](../tutorial/middleware.md){.internal-link target=_blank} a tu aplicación.
@@ -6,9 +6,9 @@ Y luego también leíste cómo manejar [CORS con el `CORSMiddleware`](../tutoria
En esta sección veremos cómo usar otros middlewares.
-## Agregando middlewares ASGI
+## Agregando middlewares ASGI { #adding-asgi-middlewares }
-Como **FastAPI** está basado en Starlette e implementa la especificación ASGI, puedes usar cualquier middleware 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.
@@ -39,7 +39,7 @@ 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
+## Middlewares integrados { #integrated-middlewares }
**FastAPI** incluye varios middlewares para casos de uso común, veremos a continuación cómo usarlos.
@@ -51,40 +51,41 @@ Para los próximos ejemplos, también podrías usar `from starlette.middleware.s
///
-## `HTTPSRedirectMiddleware`
+## `HTTPSRedirectMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *}
-## `TrustedHostMiddleware`
+## `TrustedHostMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial002_py39.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.
+* `www_redirect` - Si se establece en True, las requests a versiones sin www de los hosts permitidos serán redirigidas a sus equivalentes con www. Por defecto es `True`.
Si una request entrante no se valida correctamente, se enviará un response `400`.
-## `GZipMiddleware`
+## `GZipMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial003_py39.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
+## Otros middlewares { #other-middlewares }
Hay muchos otros middlewares ASGI.
@@ -93,4 +94,4 @@ Por ejemplo:
* `ProxyHeadersMiddleware` de Uvicorn
* MessagePack
-Para ver otros middlewares disponibles, revisa la documentación de Middleware de Starlette y la Lista ASGI Awesome.
+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
index 60d5cb3cc..caaa70fa8 100644
--- a/docs/es/docs/advanced/openapi-callbacks.md
+++ b/docs/es/docs/advanced/openapi-callbacks.md
@@ -1,18 +1,18 @@
-# OpenAPI Callbacks
+# Callbacks de OpenAPI { #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).
+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 hace un *callback*, 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
+## Una aplicación con callbacks { #an-app-with-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`.
+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.
@@ -23,15 +23,15 @@ Luego tu API (imaginemos):
* 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**
+## La aplicación normal de **FastAPI** { #the-normal-fastapi-app }
-Primero veamos cómo sería la aplicación API normal antes de agregar el callback.
+Primero veamos cómo se verí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] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *}
/// tip | Consejo
@@ -39,9 +39,9 @@ El parámetro de query `callback_url` utiliza un tipo 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
+### La expresión del path del callback { #the-callback-path-expression }
El *path* del callback puede tener una expresión OpenAPI 3 que puede contener partes del request original enviado a *tu API*.
@@ -134,7 +134,7 @@ con un JSON body de:
}
```
-luego *tu API* procesará la factura, y en algún momento después, enviará un request de callback al `callback_url` (la *API externa*):
+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
@@ -163,13 +163,13 @@ Observa cómo la URL del callback utilizada contiene la URL recibida como parám
///
-### Agregar el router de callback
+### Agrega el router de callback { #add-the-callback-router }
-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.
+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 arriba.
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] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Consejo
@@ -177,7 +177,7 @@ Observa que no estás pasando el router en sí (`invoices_callback_router`) a `c
///
-### Revisa la documentación
+### Revisa la documentación { #check-the-docs }
Ahora puedes iniciar tu aplicación e ir a http://127.0.0.1:8000/docs.
diff --git a/docs/es/docs/advanced/openapi-webhooks.md b/docs/es/docs/advanced/openapi-webhooks.md
index 01235b3ab..c358a1400 100644
--- a/docs/es/docs/advanced/openapi-webhooks.md
+++ b/docs/es/docs/advanced/openapi-webhooks.md
@@ -1,4 +1,4 @@
-# Webhooks de OpenAPI
+# Webhooks de OpenAPI { #openapi-webhooks }
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**.
@@ -6,7 +6,7 @@ Esto significa que en lugar del proceso normal de tus usuarios enviando requests
Esto normalmente se llama un **webhook**.
-## Pasos de los webhooks
+## Pasos de los webhooks { #webhooks-steps }
El proceso normalmente es que **tú defines** en tu código cuál es el mensaje que enviarás, el **body de la request**.
@@ -16,7 +16,7 @@ Y **tus usuarios** definen de alguna manera (por ejemplo en un panel web en alg
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
+## Documentando webhooks con **FastAPI** y OpenAPI { #documenting-webhooks-with-fastapi-and-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.
@@ -28,11 +28,11 @@ Los webhooks están disponibles en OpenAPI 3.1.0 y superiores, soportados por Fa
///
-## Una aplicación con webhooks
+## Una aplicación con webhooks { #an-app-with-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] *}
+{* ../../docs_src/openapi_webhooks/tutorial001_py39.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**.
@@ -46,7 +46,7 @@ Nota que con los webhooks en realidad no estás declarando un *path* (como `/ite
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
+### Revisa la documentación { #check-the-docs }
Ahora puedes iniciar tu app e ir a http://127.0.0.1:8000/docs.
diff --git a/docs/es/docs/advanced/path-operation-advanced-configuration.md b/docs/es/docs/advanced/path-operation-advanced-configuration.md
index 2b20819aa..ea58a300a 100644
--- a/docs/es/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/es/docs/advanced/path-operation-advanced-configuration.md
@@ -1,6 +1,6 @@
-# Configuración Avanzada de Path Operation
+# Configuración Avanzada de Path Operation { #path-operation-advanced-configuration }
-## operationId de OpenAPI
+## operationId de OpenAPI { #openapi-operationid }
/// warning | Advertencia
@@ -10,17 +10,17 @@ Si no eres un "experto" en OpenAPI, probablemente no necesites esto.
Puedes establecer el `operationId` de OpenAPI para ser usado en tu *path operation* con el parámetro `operation_id`.
-Tienes que asegurarte de que sea único para cada operación.
+Tendrías que asegurarte de que sea único para cada operación.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *}
-### Usar el nombre de la *función de path operation* como el operationId
+### Usar el nombre de la *path operation function* como el operationId { #using-the-path-operation-function-name-as-the-operationid }
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`.
Deberías hacerlo después de agregar todas tus *path operations*.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002.py hl[2, 12:21, 24] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *}
/// tip | Consejo
@@ -30,29 +30,29 @@ Si llamas manualmente a `app.openapi()`, deberías actualizar los `operationId`s
/// warning | Advertencia
-Si haces esto, tienes que asegurarte de que cada una de tus *funciones de path operation* tenga un nombre único.
+Si haces esto, tienes que asegurarte de que cada una de tus *path operation functions* tenga un nombre único.
Incluso si están en diferentes módulos (archivos de Python).
///
-## Excluir de OpenAPI
+## Excluir de OpenAPI { #exclude-from-openapi }
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`:
-{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *}
-## Descripción avanzada desde el docstring
+## Descripción avanzada desde el docstring { #advanced-description-from-docstring }
-Puedes limitar las líneas usadas del docstring de una *función de path operation* para OpenAPI.
+Puedes limitar las líneas usadas del docstring de una *path operation function* para OpenAPI.
-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.
+Añadir un `\f` (un carácter "form feed" escapado) hace que **FastAPI** trunque la salida usada para OpenAPI en este punto.
No aparecerá en la documentación, pero otras herramientas (como Sphinx) podrán usar el resto.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
-## Responses Adicionales
+## Responses Adicionales { #additional-responses }
Probablemente has visto cómo declarar el `response_model` y el `status_code` para una *path operation*.
@@ -62,11 +62,11 @@ También puedes declarar responses adicionales con sus modelos, códigos de esta
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
+## OpenAPI Extra { #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
+/// note | Detalles técnicos
En la especificación de OpenAPI se llama el Objeto de Operación.
@@ -88,11 +88,11 @@ Si solo necesitas declarar responses adicionales, una forma más conveniente de
Puedes extender el esquema de OpenAPI para una *path operation* usando el parámetro `openapi_extra`.
-### Extensiones de OpenAPI
+### Extensiones de OpenAPI { #openapi-extensions }
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] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.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.
@@ -129,7 +129,7 @@ Y si ves el OpenAPI resultante (en `/openapi.json` en tu API), verás tu extensi
}
```
-### Esquema de *path operation* personalizada de OpenAPI
+### Esquema de *path operation* personalizada de OpenAPI { #custom-openapi-path-operation-schema }
El diccionario en `openapi_extra` se combinará profundamente con el esquema de OpenAPI generado automáticamente para la *path operation*.
@@ -139,61 +139,29 @@ Por ejemplo, podrías decidir leer y validar el request con tu propio código, s
Podrías hacer eso con `openapi_extra`:
-{* ../../docs_src/path_operation_advanced_configuration/tutorial006.py hl[19:36, 39:40] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.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.
+En este ejemplo, no declaramos ningún modelo Pydantic. De hecho, el request body 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.
+Sin embargo, podemos declarar el esquema esperado para el request body.
-### Tipo de contenido personalizado de OpenAPI
+### Tipo de contenido personalizado de OpenAPI { #custom-openapi-content-type }
-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*.
+Usando este mismo truco, podrías usar un modelo Pydantic para definir el JSON Schema 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:
+Por ejemplo, en esta aplicación no usamos la funcionalidad integrada de FastAPI para extraer el JSON Schema 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_py39.py hl[15:20, 22] *}
-{* ../../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.
+Sin embargo, aunque no estamos usando la funcionalidad integrada por defecto, aún estamos usando un modelo Pydantic para generar manualmente el JSON Schema 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()`.
-
-///
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *}
/// tip | Consejo
diff --git a/docs/es/docs/advanced/response-change-status-code.md b/docs/es/docs/advanced/response-change-status-code.md
index e0889c474..940f1dd3f 100644
--- a/docs/es/docs/advanced/response-change-status-code.md
+++ b/docs/es/docs/advanced/response-change-status-code.md
@@ -1,10 +1,10 @@
-# Response - Cambiar Código de Estado
+# Response - Cambiar Código de Estado { #response-change-status-code }
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 devolver un código de estado diferente al predeterminado.
-## Caso de uso
+## Caso de uso { #use-case }
Por ejemplo, imagina que quieres devolver un código de estado HTTP de "OK" `200` por defecto.
@@ -14,13 +14,13 @@ Pero todavía quieres poder filtrar y convertir los datos que devuelves con un `
Para esos casos, puedes usar un parámetro `Response`.
-## Usa un parámetro `Response`
+## Usa un parámetro `Response` { #use-a-response-parameter }
-Puedes declarar un parámetro de tipo `Response` en tu *función de path operation* (como puedes hacer para cookies y headers).
+Puedes declarar un parámetro de tipo `Response` en tu *path operation function* (como puedes hacer para cookies y headers).
Y luego puedes establecer el `status_code` en ese objeto de response *temporal*.
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *}
Y luego puedes devolver cualquier objeto que necesites, como lo harías normalmente (un `dict`, un modelo de base de datos, etc.).
diff --git a/docs/es/docs/advanced/response-cookies.md b/docs/es/docs/advanced/response-cookies.md
index c4472eaa1..550a5d97a 100644
--- a/docs/es/docs/advanced/response-cookies.md
+++ b/docs/es/docs/advanced/response-cookies.md
@@ -1,12 +1,12 @@
-# Cookies de Response
+# Cookies de Response { #response-cookies }
-## Usar un parámetro `Response`
+## Usar un parámetro `Response` { #use-a-response-parameter }
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] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.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).
@@ -16,7 +16,7 @@ Y si declaraste un `response_model`, todavía se utilizará para filtrar y conve
También puedes declarar el parámetro `Response` en las dependencias, y establecer cookies (y headers) en ellas.
-## Devolver una `Response` directamente
+## Devolver una `Response` directamente { #return-a-response-directly }
También puedes crear cookies al devolver una `Response` directamente en tu código.
@@ -24,7 +24,7 @@ Para hacer eso, puedes crear un response como se describe en [Devolver un Respon
Luego establece Cookies en ella, y luego devuélvela:
-{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
/// tip | Consejo
@@ -36,7 +36,7 @@ Y también que no estés enviando ningún dato que debería haber sido filtrado
///
-### Más información
+### Más información { #more-info }
/// note | Detalles Técnicos
@@ -48,4 +48,4 @@ Y como el `Response` se puede usar frecuentemente para establecer headers y cook
///
-Para ver todos los parámetros y opciones disponibles, revisa la documentación en Starlette.
+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 8594011d6..2da4e84e7 100644
--- a/docs/es/docs/advanced/response-directly.md
+++ b/docs/es/docs/advanced/response-directly.md
@@ -1,4 +1,4 @@
-# Devolver una Response Directamente
+# Devolver una Response Directamente { #return-a-response-directly }
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.
@@ -10,7 +10,7 @@ Pero puedes devolver un `JSONResponse` directamente desde tus *path operations*.
Esto podría ser útil, por ejemplo, para devolver headers o cookies personalizados.
-## Devolver una `Response`
+## Devolver una `Response` { #return-a-response }
De hecho, puedes devolver cualquier `Response` o cualquier subclase de ella.
@@ -26,7 +26,7 @@ No hará ninguna conversión de datos con los modelos de Pydantic, no convertir
Esto te da mucha flexibilidad. Puedes devolver cualquier tipo de datos, sobrescribir cualquier declaración o validación de datos, etc.
-## Usar el `jsonable_encoder` en una `Response`
+## Usar el `jsonable_encoder` en una `Response` { #using-the-jsonable-encoder-in-a-response }
Como **FastAPI** no realiza cambios en una `Response` que devuelves, tienes que asegurarte de que sus contenidos estén listos para ello.
@@ -34,9 +34,9 @@ Por ejemplo, no puedes poner un modelo de Pydantic en un `JSONResponse` sin prim
Para esos casos, puedes usar el `jsonable_encoder` para convertir tus datos antes de pasarlos a un response:
-{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
-/// note | Nota
+/// note | Detalles técnicos
También podrías usar `from starlette.responses import JSONResponse`.
@@ -44,7 +44,7 @@ También podrías usar `from starlette.responses import JSONResponse`.
///
-## Devolver una `Response` personalizada
+## Devolver una `Response` personalizada { #returning-a-custom-response }
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.
@@ -54,9 +54,9 @@ Digamos que quieres devolver un response en usando el prefijo 'X-'.
+Ten en cuenta que los headers propietarios personalizados se pueden agregar usando el prefijo `X-`.
-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.
+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
index 629e6c50a..440c081e0 100644
--- a/docs/es/docs/advanced/security/http-basic-auth.md
+++ b/docs/es/docs/advanced/security/http-basic-auth.md
@@ -1,4 +1,4 @@
-# HTTP Basic Auth
+# HTTP Basic Auth { #http-basic-auth }
Para los casos más simples, puedes usar HTTP Basic Auth.
@@ -12,7 +12,7 @@ Eso le dice al navegador que muestre el prompt integrado para un nombre de usuar
Luego, cuando escribes ese nombre de usuario y contraseña, el navegador los envía automáticamente en el header.
-## Simple HTTP Basic Auth
+## Simple HTTP Basic Auth { #simple-http-basic-auth }
* Importa `HTTPBasic` y `HTTPBasicCredentials`.
* Crea un "esquema de `security`" usando `HTTPBasic`.
@@ -26,7 +26,7 @@ Cuando intentas abrir la URL por primera vez (o haces clic en el botón "Execute
-## Revisa el nombre de usuario
+## Revisa el nombre de usuario { #check-the-username }
Aquí hay un ejemplo más completo.
@@ -46,13 +46,13 @@ Esto sería similar a:
```Python
if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
- # Return some error
+ # Devuelve algún error
...
```
Pero al usar `secrets.compare_digest()` será seguro contra un tipo de ataques llamados "timing attacks".
-### Timing Attacks
+### Timing attacks { #timing-attacks }
¿Pero qué es un "timing attack"?
@@ -80,19 +80,19 @@ 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
+#### El tiempo de respuesta ayuda a los atacantes { #the-time-to-answer-helps-the-attackers }
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"
+#### Un ataque "profesional" { #a-professional-attack }
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()`
+#### Arréglalo con `secrets.compare_digest()` { #fix-it-with-secrets-compare-digest }
Pero en nuestro código estamos usando realmente `secrets.compare_digest()`.
@@ -100,7 +100,7 @@ En resumen, tomará el mismo tiempo comparar `stanleyjobsox` con `stanleyjobson`
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
+### Devuelve el error { #return-the-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:
diff --git a/docs/es/docs/advanced/security/index.md b/docs/es/docs/advanced/security/index.md
index e4ccb5978..8b3e67fac 100644
--- a/docs/es/docs/advanced/security/index.md
+++ b/docs/es/docs/advanced/security/index.md
@@ -1,6 +1,6 @@
-# Seguridad Avanzada
+# Seguridad Avanzada { #advanced-security }
-## Funcionalidades Adicionales
+## Funcionalidades Adicionales { #additional-features }
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}.
@@ -12,8 +12,8 @@ Y es posible que para tu caso de uso, la solución esté en una de ellas.
///
-## Lee primero el Tutorial
+## Lee primero el Tutorial { #read-the-tutorial-first }
-Las siguientes secciones asumen que ya leíste el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank}.
+Las siguientes secciones asumen que ya leíste el [Tutorial - Guía del Usuario: Seguridad](../../tutorial/security/index.md){.internal-link target=_blank} principal.
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
index a8d2f20b6..4e4580fde 100644
--- a/docs/es/docs/advanced/security/oauth2-scopes.md
+++ b/docs/es/docs/advanced/security/oauth2-scopes.md
@@ -1,4 +1,4 @@
-# Scopes de OAuth2
+# Scopes de OAuth2 { #oauth2-scopes }
Puedes usar scopes de OAuth2 directamente con **FastAPI**, están integrados para funcionar de manera fluida.
@@ -26,7 +26,7 @@ Pero si sabes que lo necesitas, o tienes curiosidad, sigue leyendo.
///
-## Scopes de OAuth2 y OpenAPI
+## Scopes de OAuth2 y OpenAPI { #oauth2-scopes-and-openapi }
La especificación de OAuth2 define "scopes" como una lista de strings separados por espacios.
@@ -58,15 +58,15 @@ Para OAuth2 son solo strings.
///
-## Vista global
+## Vista global { #global-view }
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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
Ahora revisemos esos cambios paso a paso.
-## Esquema de seguridad OAuth2
+## Esquema de seguridad OAuth2 { #oauth2-security-scheme }
El primer cambio es que ahora estamos declarando el esquema de seguridad OAuth2 con dos scopes disponibles, `me` y `items`.
@@ -82,7 +82,7 @@ Este es el mismo mecanismo utilizado cuando das permisos al iniciar sesión con
-## Token JWT con scopes
+## Token JWT con scopes { #jwt-token-with-scopes }
Ahora, modifica la *path operation* del token para devolver los scopes solicitados.
@@ -98,9 +98,9 @@ Pero en tu aplicación, por seguridad, deberías asegurarte de añadir solo los
///
-{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}
-## Declarar scopes en *path operations* y dependencias
+## Declarar scopes en *path operations* y dependencias { #declare-scopes-in-path-operations-and-dependencies }
Ahora declaramos que la *path operation* para `/users/me/items/` requiere el scope `items`.
@@ -124,7 +124,7 @@ Lo estamos haciendo aquí para demostrar cómo **FastAPI** maneja scopes declara
///
-{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
/// info | Información Técnica
@@ -136,7 +136,7 @@ Pero cuando importas `Query`, `Path`, `Depends`, `Security` y otros de `fastapi`
///
-## Usar `SecurityScopes`
+## Usar `SecurityScopes` { #use-securityscopes }
Ahora actualiza la dependencia `get_current_user`.
@@ -152,7 +152,7 @@ Esta clase `SecurityScopes` es similar a `Request` (`Request` se usó para obten
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
-## Usar los `scopes`
+## Usar los `scopes` { #use-the-scopes }
El parámetro `security_scopes` será del tipo `SecurityScopes`.
@@ -166,7 +166,7 @@ En esta excepción, incluimos los scopes requeridos (si los hay) como un string
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
-## Verificar el `username` y la forma de los datos
+## Verificar el `username` y la forma de los datos { #verify-the-username-and-data-shape }
Verificamos que obtenemos un `username`, y extraemos los scopes.
@@ -180,17 +180,17 @@ En lugar de, por ejemplo, un `dict`, o algo más, ya que podría romper la aplic
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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}
-## Verificar los `scopes`
+## Verificar los `scopes` { #verify-the-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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
-## Árbol de dependencias y scopes
+## Árbol de dependencias y scopes { #dependency-tree-and-scopes }
Revisemos de nuevo este árbol de dependencias y los scopes.
@@ -223,7 +223,7 @@ Todo depende de los `scopes` declarados en cada *path operation* y cada dependen
///
-## Más detalles sobre `SecurityScopes`
+## Más detalles sobre `SecurityScopes` { #more-details-about-securityscopes }
Puedes usar `SecurityScopes` en cualquier punto, y en múltiples lugares, no tiene que ser en la dependencia "raíz".
@@ -233,7 +233,7 @@ Debido a que `SecurityScopes` tendrá todos los scopes declarados por dependient
Serán verificados independientemente para cada *path operation*.
-## Revisa
+## Revisa { #check-it }
Si abres la documentación de la API, puedes autenticarte y especificar qué scopes deseas autorizar.
@@ -245,7 +245,7 @@ Y si seleccionas el scope `me` pero no el scope `items`, podrás acceder a `/use
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
+## Acerca de las integraciones de terceros { #about-third-party-integrations }
En este ejemplo estamos usando el flujo de OAuth2 "password".
@@ -269,6 +269,6 @@ 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
+## `Security` en `dependencies` del decorador { #security-in-decorator-dependencies }
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
index 7e591cc01..a2d749103 100644
--- a/docs/es/docs/advanced/settings.md
+++ b/docs/es/docs/advanced/settings.md
@@ -1,4 +1,4 @@
-# Configuraciones y Variables de Entorno
+# Configuraciones y Variables de Entorno { #settings-and-environment-variables }
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.
@@ -12,17 +12,17 @@ Para entender las variables de entorno, puedes leer [Variables de Entorno](../en
///
-## Tipos y validación
+## Tipos y validación { #types-and-validation }
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`
+## Pydantic `Settings` { #pydantic-settings }
Afortunadamente, Pydantic proporciona una gran utilidad para manejar estas configuraciones provenientes de variables de entorno con Pydantic: Settings management.
-### Instalar `pydantic-settings`
+### Instalar `pydantic-settings` { #install-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`:
@@ -46,13 +46,7 @@ $ pip install "fastapi[all]"
-### Inicio del Handshake TLS
+### Inicio del Handshake TLS { #tls-handshake-start }
El navegador luego se comunicaría con esa dirección IP en el **puerto 443** (el puerto HTTPS).
@@ -97,7 +97,7 @@ La primera parte de la comunicación es solo para establecer la conexión entre
Esta interacción entre el cliente y el servidor para establecer la conexión TLS se llama **handshake TLS**.
-### TLS con Extensión SNI
+### TLS con Extensión SNI { #tls-with-sni-extension }
**Solo un proceso** en el servidor puede estar escuchando en un **puerto** específico en una **dirección IP** específica. Podría haber otros procesos escuchando en otros puertos en la misma dirección IP, pero solo uno para cada combinación de dirección IP y puerto.
@@ -127,7 +127,7 @@ Ten en cuenta que la encriptación de la comunicación ocurre a nivel de **TCP**
///
-### Request HTTPS
+### Request HTTPS { #https-request }
Ahora que el cliente y el servidor (específicamente el navegador y el TLS Termination Proxy) tienen una **conexión TCP encriptada**, pueden iniciar la **comunicación HTTP**.
@@ -135,19 +135,19 @@ Así que, el cliente envía un **request HTTPS**. Esto es simplemente un request
-### Desencriptar el Request
+### Desencriptar el Request { #decrypt-the-request }
El TLS Termination Proxy usaría la encriptación acordada para **desencriptar el request**, y transmitiría el **request HTTP simple (desencriptado)** al proceso que ejecuta la aplicación (por ejemplo, un proceso con Uvicorn ejecutando la aplicación FastAPI).
-### Response HTTP
+### Response HTTP { #http-response }
La aplicación procesaría el request y enviaría un **response HTTP simple (sin encriptar)** al TLS Termination Proxy.
-### Response HTTPS
+### Response HTTPS { #https-response }
El TLS Termination Proxy entonces **encriptaría el response** usando la criptografía acordada antes (que comenzó con el certificado para `someapp.example.com`), y lo enviaría de vuelta al navegador.
@@ -157,7 +157,7 @@ Luego, el navegador verificaría que el response sea válido y encriptado con la
El cliente (navegador) sabrá que el response proviene del servidor correcto porque está utilizando la criptografía que acordaron usando el **certificado HTTPS** anteriormente.
-### Múltiples Aplicaciones
+### Múltiples Aplicaciones { #multiple-applications }
En el mismo servidor (o servidores), podrían haber **múltiples aplicaciones**, por ejemplo, otros programas API o una base de datos.
@@ -167,7 +167,7 @@ Solo un proceso puede estar gestionando la IP y puerto específica (el TLS Termi
De esa manera, el TLS Termination Proxy podría gestionar HTTPS y certificados para **múltiples dominios**, para múltiples aplicaciones, y luego transmitir los requests a la aplicación correcta en cada caso.
-### Renovación de Certificados
+### Renovación de Certificados { #certificate-renewal }
En algún momento en el futuro, cada certificado **expiraría** (alrededor de 3 meses después de haberlo adquirido).
@@ -190,7 +190,39 @@ Para hacer eso, y para acomodar diferentes necesidades de aplicaciones, hay vari
Todo este proceso de renovación, mientras aún se sirve la aplicación, es una de las principales razones por las que querrías tener un **sistema separado para gestionar el HTTPS** con un TLS Termination Proxy en lugar de simplemente usar los certificados TLS con el servidor de aplicaciones directamente (por ejemplo, Uvicorn).
-## Resumen
+## Headers reenviados por el proxy { #proxy-forwarded-headers }
+
+Al usar un proxy para gestionar HTTPS, tu **servidor de aplicaciones** (por ejemplo Uvicorn vía FastAPI CLI) no sabe nada sobre el proceso HTTPS, se comunica con HTTP simple con el **TLS Termination Proxy**.
+
+Este **proxy** normalmente configuraría algunos headers HTTP sobre la marcha antes de transmitir el request al **servidor de aplicaciones**, para hacerle saber al servidor de aplicaciones que el request está siendo **reenviado** por el proxy.
+
+/// note | Detalles técnicos
+
+Los headers del proxy son:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+Aun así, como el **servidor de aplicaciones** no sabe que está detrás de un **proxy** de confianza, por defecto, no confiaría en esos headers.
+
+Pero puedes configurar el **servidor de aplicaciones** para confiar en los headers reenviados enviados por el **proxy**. Si estás usando FastAPI CLI, puedes usar la *Opción de la CLI* `--forwarded-allow-ips` para indicarle desde qué IPs debería confiar en esos headers reenviados.
+
+Por ejemplo, si el **servidor de aplicaciones** solo está recibiendo comunicación del **proxy** de confianza, puedes establecerlo en `--forwarded-allow-ips="*"` para hacer que confíe en todas las IPs entrantes, ya que solo recibirá requests desde la IP que sea utilizada por el **proxy**.
+
+De esta manera la aplicación podrá saber cuál es su propia URL pública, si está usando HTTPS, el dominio, etc.
+
+Esto sería útil, por ejemplo, para manejar correctamente redirecciones.
+
+/// tip | Consejo
+
+Puedes aprender más sobre esto en la documentación de [Detrás de un proxy - Habilitar headers reenviados por el proxy](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank}
+
+///
+
+## Resumen { #recap }
Tener **HTTPS** es muy importante y bastante **crítico** en la mayoría de los casos. La mayor parte del esfuerzo que como desarrollador tienes que poner en torno a HTTPS es solo sobre **entender estos conceptos** y cómo funcionan.
diff --git a/docs/es/docs/deployment/index.md b/docs/es/docs/deployment/index.md
index 3b6dcc05d..1260c68b9 100644
--- a/docs/es/docs/deployment/index.md
+++ b/docs/es/docs/deployment/index.md
@@ -1,8 +1,8 @@
-# Despliegue
+# Despliegue { #deployment }
Desplegar una aplicación **FastAPI** es relativamente fácil.
-## Qué Significa Despliegue
+## Qué Significa Despliegue { #what-does-deployment-mean }
**Desplegar** una aplicación significa realizar los pasos necesarios para hacerla **disponible para los usuarios**.
@@ -10,12 +10,14 @@ Para una **API web**, normalmente implica ponerla en una **máquina remota**, co
Esto contrasta con las etapas de **desarrollo**, donde estás constantemente cambiando el código, rompiéndolo y arreglándolo, deteniendo y reiniciando el servidor de desarrollo, etc.
-## Estrategias de Despliegue
+## Estrategias de Despliegue { #deployment-strategies }
Hay varias maneras de hacerlo dependiendo de tu caso de uso específico y las herramientas que utilices.
Podrías **desplegar un servidor** tú mismo utilizando una combinación de herramientas, podrías usar un **servicio en la nube** que hace parte del trabajo por ti, u otras opciones posibles.
+Por ejemplo, nosotros, el equipo detrás de FastAPI, construimos **FastAPI Cloud**, para hacer que desplegar aplicaciones de FastAPI en la nube sea lo más ágil posible, con la misma experiencia de desarrollador de trabajar con FastAPI.
+
Te mostraré algunos de los conceptos principales que probablemente deberías tener en cuenta al desplegar una aplicación **FastAPI** (aunque la mayoría se aplica a cualquier otro tipo de aplicación web).
Verás más detalles a tener en cuenta y algunas de las técnicas para hacerlo en las siguientes secciones. ✨
diff --git a/docs/es/docs/deployment/manually.md b/docs/es/docs/deployment/manually.md
index 509b9ebdb..50ba79c22 100644
--- a/docs/es/docs/deployment/manually.md
+++ b/docs/es/docs/deployment/manually.md
@@ -1,51 +1,39 @@
-# Ejecutar un Servidor Manualmente
+# Ejecutar un Servidor Manualmente { #run-a-server-manually }
-## Usa el Comando `fastapi run`
+## Usa el Comando `fastapi run` { #use-the-fastapi-run-command }
En resumen, usa `fastapi run` para servir tu aplicación FastAPI:
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 run --workers 4 main.py + + FastAPI Starting production server 🚀 + + Searching for package file structure from directories with + __init__.py files + Importing from /home/user/code/awesomeapp + + module 🐍 main.py + + code Importing the FastAPI app object from the module with the + following code: + + from main import app + + app Using import string: main:app + + server Server started at http://0.0.0.0:8000 + server Documentation at http://0.0.0.0:8000/docs + + Logs: + + 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 Started server process [27369] + INFO Started server process [27370] + INFO Started server process [27367] + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. ```
-## Cambiar el tema
+## Cambiar el tema { #change-the-theme }
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] *}
+{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *}
Esa configuración cambiaría el tema de color del resaltado de sintaxis:
-## Cambiar los parámetros predeterminados de Swagger UI
+## Cambiar los parámetros predeterminados de Swagger UI { #change-default-swagger-ui-parameters }
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] *}
+{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}
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] *}
+{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *}
-## Otros parámetros de Swagger UI
+## Otros parámetros de Swagger UI { #other-swagger-ui-parameters }
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
+## Configuraciones solo de JavaScript { #javascript-only-settings }
Swagger UI también permite otras configuraciones que son objetos **solo de JavaScript** (por ejemplo, funciones de JavaScript).
diff --git a/docs/es/docs/how-to/custom-docs-ui-assets.md b/docs/es/docs/how-to/custom-docs-ui-assets.md
index 0a03ff330..acd3f8d6d 100644
--- a/docs/es/docs/how-to/custom-docs-ui-assets.md
+++ b/docs/es/docs/how-to/custom-docs-ui-assets.md
@@ -1,26 +1,26 @@
-# Recursos Estáticos Personalizados para la Docs UI (Self-Hosting)
+# Recursos Estáticos Personalizados para la Docs UI (self hosting) { #custom-docs-ui-static-assets-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.
+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
+## CDN Personalizado para JavaScript y CSS { #custom-cdn-for-javascript-and-css }
-Digamos que quieres usar un CDN diferente, por ejemplo, quieres usar `https://unpkg.com/`.
+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
+### Desactiva la documentación automática { #disable-the-automatic-docs }
-El primer paso es desactivar la documentación automática, ya que por defecto, esos usan el CDN predeterminado.
+El primer paso es desactivar la documentación automática, ya que por defecto, 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/tutorial001.py hl[8] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *}
-### Incluye la documentación personalizada
+### Incluye la documentación personalizada { #include-the-custom-docs }
Ahora puedes crear las *path operations* para la documentación personalizada.
@@ -28,13 +28,13 @@ Puedes reutilizar las funciones internas de FastAPI para crear las páginas HTML
* `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.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor por defecto.
* `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] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *}
/// tip | Consejo
@@ -46,23 +46,23 @@ Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar d
///
-### Crea una *path operation* para probarlo
+### Crea una *path operation* para probarlo { #create-a-path-operation-to-test-it }
Ahora, para poder probar que todo funciona, crea una *path operation*:
-{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *}
-### Pruébalo
+### Pruébalo { #test-it }
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
+## self hosting de JavaScript y CSS para la documentación { #self-hosting-javascript-and-css-for-docs }
-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.
+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
+### Estructura de archivos del proyecto { #project-file-structure }
Supongamos que la estructura de archivos de tu proyecto se ve así:
@@ -85,7 +85,7 @@ Tu nueva estructura de archivos podría verse así:
└── static/
```
-### Descarga los archivos
+### Descarga los archivos { #download-the-files }
Descarga los archivos estáticos necesarios para la documentación y ponlos en ese directorio `static/`.
@@ -113,14 +113,14 @@ Después de eso, tu estructura de archivos podría verse así:
└── swagger-ui.css
```
-### Sirve los archivos estáticos
+### Sirve los archivos estáticos { #serve-the-static-files }
* Importa `StaticFiles`.
* "Monta" una instance de `StaticFiles()` en un path específico.
-{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *}
-### Prueba los archivos estáticos
+### Prueba los archivos estáticos { #test-the-static-files }
Inicia tu aplicación y ve a http://127.0.0.1:8000/static/redoc.standalone.js.
@@ -138,15 +138,15 @@ Eso confirma que puedes servir archivos estáticos desde tu aplicación, y que c
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
+### Desactiva la documentación automática para archivos estáticos { #disable-the-automatic-docs-for-static-files }
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] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *}
-### Incluye la documentación personalizada para archivos estáticos
+### Incluye la documentación personalizada para archivos estáticos { #include-the-custom-docs-for-static-files }
Y de la misma manera que con un CDN personalizado, ahora puedes crear las *path operations* para la documentación personalizada.
@@ -154,13 +154,13 @@ Nuevamente, puedes reutilizar las funciones internas de FastAPI para crear las p
* `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.
+* `oauth2_redirect_url`: puedes usar `app.swagger_ui_oauth2_redirect_url` aquí para usar el valor por defecto.
* `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] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[2:6,14:22,25:27,30:36] *}
/// tip | Consejo
@@ -172,13 +172,13 @@ Swagger UI lo manejará detrás de escena para ti, pero necesita este auxiliar d
///
-### Crea una *path operation* para probar archivos estáticos
+### Crea una *path operation* para probar archivos estáticos { #create-a-path-operation-to-test-static-files }
Ahora, para poder probar que todo funciona, crea una *path operation*:
-{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[39:41] *}
-### Prueba la UI de Archivos Estáticos
+### Prueba la UI de Archivos Estáticos { #test-static-files-ui }
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.
diff --git a/docs/es/docs/how-to/custom-request-and-route.md b/docs/es/docs/how-to/custom-request-and-route.md
index 0b479bf00..ff13196f8 100644
--- a/docs/es/docs/how-to/custom-request-and-route.md
+++ b/docs/es/docs/how-to/custom-request-and-route.md
@@ -1,4 +1,4 @@
-# Clase personalizada de Request y APIRoute
+# Clase personalizada de Request y APIRoute { #custom-request-and-apiroute-class }
En algunos casos, puede que quieras sobrescribir la lógica utilizada por las clases `Request` y `APIRoute`.
@@ -14,7 +14,7 @@ Si apenas estás comenzando con **FastAPI**, quizás quieras saltar esta secció
///
-## Casos de uso
+## Casos de uso { #use-cases }
Algunos casos de uso incluyen:
@@ -22,13 +22,13 @@ Algunos casos de uso incluyen:
* Descomprimir cuerpos de requests comprimidos con gzip.
* Registrar automáticamente todos los request bodies.
-## Manejo de codificaciones personalizadas de request body
+## Manejo de codificaciones personalizadas de request body { #handling-custom-request-body-encodings }
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`
+### Crear una clase personalizada `GzipRequest` { #create-a-custom-gziprequest-class }
/// tip | Consejo
@@ -42,9 +42,9 @@ 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] *}
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}
-### Crear una clase personalizada `GzipRoute`
+### Crear una clase personalizada `GzipRoute` { #create-a-custom-gziproute-class }
A continuación, creamos una subclase personalizada de `fastapi.routing.APIRoute` que hará uso de `GzipRequest`.
@@ -54,7 +54,7 @@ Este método devuelve una función. Y esa función es la que recibirá un reques
Aquí lo usamos para crear un `GzipRequest` a partir del request original.
-{* ../../docs_src/custom_request_and_route/tutorial001.py hl[18:26] *}
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *}
/// note | Detalles técnicos
@@ -66,7 +66,7 @@ El `dict` `scope` y la función `receive` son ambos parte de la especificación
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.
+Para aprender más sobre el `Request`, revisa la documentación de Starlette sobre Requests.
///
@@ -78,7 +78,7 @@ 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
+## Accediendo al request body en un manejador de excepciones { #accessing-the-request-body-in-an-exception-handler }
/// tip | Consejo
@@ -92,18 +92,18 @@ También podemos usar este mismo enfoque para acceder al request body en un mane
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] *}
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *}
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] *}
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *}
-## Clase personalizada `APIRoute` en un router
+## Clase personalizada `APIRoute` en un router { #custom-apiroute-class-in-a-router }
También puedes establecer el parámetro `route_class` de un `APIRouter`:
-{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.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] *}
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *}
diff --git a/docs/es/docs/how-to/extending-openapi.md b/docs/es/docs/how-to/extending-openapi.md
index 3dbdd666b..2611b6e1b 100644
--- a/docs/es/docs/how-to/extending-openapi.md
+++ b/docs/es/docs/how-to/extending-openapi.md
@@ -1,10 +1,10 @@
-# Extender OpenAPI
+# Extender OpenAPI { #extending-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 { #the-normal-process }
El proceso normal (por defecto) es el siguiente.
@@ -33,31 +33,31 @@ El parámetro `summary` está disponible en OpenAPI 3.1.0 y versiones superiores
///
-## Sobrescribir los valores por defecto
+## Sobrescribir los valores por defecto { #overriding-the-defaults }
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
+### **FastAPI** normal { #normal-fastapi }
Primero, escribe toda tu aplicación **FastAPI** como normalmente:
-{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[1,4,7:9] *}
-### Generar el esquema de OpenAPI
+### Generar el esquema de OpenAPI { #generate-the-openapi-schema }
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[2,15:21] *}
-### Modificar el esquema de OpenAPI
+### Modificar el esquema de OpenAPI { #modify-the-openapi-schema }
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[22:24] *}
-### Cachear el esquema de OpenAPI
+### Cachear el esquema de OpenAPI { #cache-the-openapi-schema }
Puedes usar la propiedad `.openapi_schema` como un "cache", para almacenar tu esquema generado.
@@ -65,15 +65,15 @@ De esa forma, tu aplicación no tendrá que generar el esquema cada vez que un u
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[13:14,25:26] *}
-### Sobrescribir el método
+### Sobrescribir el método { #override-the-method }
Ahora puedes reemplazar el método `.openapi()` por tu nueva función.
-{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[29] *}
-### Revisa
+### Revisa { #check-it }
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
index e10621ce5..3a3dc8294 100644
--- a/docs/es/docs/how-to/general.md
+++ b/docs/es/docs/how-to/general.md
@@ -1,39 +1,39 @@
-# General - Cómo Hacer - Recetas
+# General - Cómo Hacer - Recetas { #general-how-to-recipes }
Aquí tienes varias indicaciones hacia otros lugares en la documentación, para preguntas generales o frecuentes.
-## Filtrar Datos - Seguridad
+## Filtrar Datos - Seguridad { #filter-data-security }
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
+## Etiquetas de Documentación - OpenAPI { #documentation-tags-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
+## Resumen y Descripción de Documentación - OpenAPI { #documentation-summary-and-description-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
+## Documentación de Descripción de Response - OpenAPI { #documentation-response-description-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
+## Documentar la Deprecación de una *Path Operation* - OpenAPI { #documentation-deprecate-a-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
+## Convertir cualquier Dato a Compatible con JSON { #convert-any-data-to-json-compatible }
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
+## Metadatos OpenAPI - Documentación { #openapi-metadata-docs }
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
+## URL Personalizada de OpenAPI { #openapi-custom-url }
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
+## URLs de Documentación de OpenAPI { #openapi-docs-urls }
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 52f163809..e50c1ae0a 100644
--- a/docs/es/docs/how-to/graphql.md
+++ b/docs/es/docs/how-to/graphql.md
@@ -1,4 +1,4 @@
-# GraphQL
+# GraphQL { #graphql }
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.
@@ -14,7 +14,7 @@ Asegúrate de evaluar si los **beneficios** para tu caso de uso compensan los **
///
-## Paquetes de GraphQL
+## Paquetes de GraphQL { #graphql-libraries }
Aquí algunos de los paquetes de **GraphQL** que tienen soporte **ASGI**. Podrías usarlos con **FastAPI**:
@@ -27,7 +27,7 @@ Aquí algunos de los paquetes de **GraphQL** que tienen soporte **ASGI**. Podrí
* Graphene
* Con starlette-graphene3
-## GraphQL con Strawberry
+## GraphQL con Strawberry { #graphql-with-strawberry }
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**.
@@ -35,13 +35,13 @@ Dependiendo de tu caso de uso, podrías preferir usar un paquete diferente, pero
Aquí tienes una pequeña vista previa de cómo podrías integrar Strawberry con FastAPI:
-{* ../../docs_src/graphql/tutorial001.py hl[3,22,25:26] *}
+{* ../../docs_src/graphql_/tutorial001_py39.py hl[3,22,25] *}
Puedes aprender más sobre Strawberry en la documentación de Strawberry.
Y también la documentación sobre Strawberry con FastAPI.
-## `GraphQLApp` viejo de Starlette
+## `GraphQLApp` viejo de Starlette { #older-graphqlapp-from-starlette }
Las versiones anteriores de Starlette incluían una clase `GraphQLApp` para integrar con Graphene.
@@ -53,7 +53,7 @@ Si necesitas GraphQL, aún te recomendaría revisar documentación oficial de GraphQL.
diff --git a/docs/es/docs/how-to/index.md b/docs/es/docs/how-to/index.md
index 152499af8..6f5988049 100644
--- a/docs/es/docs/how-to/index.md
+++ b/docs/es/docs/how-to/index.md
@@ -1,4 +1,4 @@
-# How To - Recetas
+# Cómo hacer - Recetas { #how-to-recipes }
Aquí verás diferentes recetas o guías de "cómo hacer" para **varios temas**.
@@ -8,6 +8,6 @@ Si algo parece interesante y útil para tu proyecto, adelante y revísalo, pero
/// 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.
+Si quieres **aprender FastAPI** de una manera estructurada (recomendado), ve y lee el [Tutorial - Guía de Usuario](../tutorial/index.md){.internal-link target=_blank} capítulo por capítulo en su lugar.
///
diff --git a/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
new file mode 100644
index 000000000..c862ace90
--- /dev/null
+++ b/docs/es/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
@@ -0,0 +1,135 @@
+# Migra de Pydantic v1 a Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }
+
+Si tienes una app de FastAPI antigua, podrías estar usando Pydantic versión 1.
+
+FastAPI versión 0.100.0 tenía compatibilidad con Pydantic v1 o v2. Usaba la que tuvieras instalada.
+
+FastAPI versión 0.119.0 introdujo compatibilidad parcial con Pydantic v1 desde dentro de Pydantic v2 (como `pydantic.v1`), para facilitar la migración a v2.
+
+FastAPI 0.126.0 eliminó la compatibilidad con Pydantic v1, aunque siguió soportando `pydantic.v1` por un poquito más de tiempo.
+
+/// warning | Advertencia
+
+El equipo de Pydantic dejó de dar soporte a Pydantic v1 para las versiones más recientes de Python, comenzando con **Python 3.14**.
+
+Esto incluye `pydantic.v1`, que ya no está soportado en Python 3.14 y superiores.
+
+Si quieres usar las funcionalidades más recientes de Python, tendrás que asegurarte de usar Pydantic v2.
+
+///
+
+Si tienes una app de FastAPI antigua con Pydantic v1, aquí te muestro cómo migrarla a Pydantic v2, y las **funcionalidades en FastAPI 0.119.0** para ayudarte con una migración gradual.
+
+## Guía oficial { #official-guide }
+
+Pydantic tiene una Guía de migración oficial de v1 a v2.
+
+También incluye qué cambió, cómo las validaciones ahora son más correctas y estrictas, posibles consideraciones, etc.
+
+Puedes leerla para entender mejor qué cambió.
+
+## Tests { #tests }
+
+Asegúrate de tener [tests](../tutorial/testing.md){.internal-link target=_blank} para tu app y de ejecutarlos en integración continua (CI).
+
+Así podrás hacer la actualización y asegurarte de que todo sigue funcionando como esperas.
+
+## `bump-pydantic` { #bump-pydantic }
+
+En muchos casos, cuando usas modelos de Pydantic normales sin personalizaciones, podrás automatizar gran parte del proceso de migración de Pydantic v1 a Pydantic v2.
+
+Puedes usar `bump-pydantic` del mismo equipo de Pydantic.
+
+Esta herramienta te ayudará a cambiar automáticamente la mayor parte del código que necesita cambiarse.
+
+Después de esto, puedes ejecutar los tests y revisa si todo funciona. Si es así, ya terminaste. 😎
+
+## Pydantic v1 en v2 { #pydantic-v1-in-v2 }
+
+Pydantic v2 incluye todo lo de Pydantic v1 como un submódulo `pydantic.v1`. Pero esto ya no está soportado en versiones por encima de Python 3.13.
+
+Esto significa que puedes instalar la versión más reciente de Pydantic v2 e importar y usar los componentes viejos de Pydantic v1 desde este submódulo, como si tuvieras instalado el Pydantic v1 antiguo.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *}
+
+### Compatibilidad de FastAPI con Pydantic v1 en v2 { #fastapi-support-for-pydantic-v1-in-v2 }
+
+Desde FastAPI 0.119.0, también hay compatibilidad parcial para Pydantic v1 desde dentro de Pydantic v2, para facilitar la migración a v2.
+
+Así que podrías actualizar Pydantic a la última versión 2 y cambiar los imports para usar el submódulo `pydantic.v1`, y en muchos casos simplemente funcionaría.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *}
+
+/// warning | Advertencia
+
+Ten en cuenta que, como el equipo de Pydantic ya no da soporte a Pydantic v1 en versiones recientes de Python, empezando por Python 3.14, usar `pydantic.v1` tampoco está soportado en Python 3.14 y superiores.
+
+///
+
+### Pydantic v1 y v2 en la misma app { #pydantic-v1-and-v2-on-the-same-app }
+
+**No está soportado** por Pydantic tener un modelo de Pydantic v2 con sus propios campos definidos como modelos de Pydantic v1 o viceversa.
+
+```mermaid
+graph TB
+ subgraph "❌ Not Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+...pero puedes tener modelos separados usando Pydantic v1 y v2 en la misma app.
+
+```mermaid
+graph TB
+ subgraph "✅ Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+En algunos casos, incluso es posible tener modelos de Pydantic v1 y v2 en la misma **path operation** de tu app de FastAPI:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *}
+
+En el ejemplo anterior, el modelo de entrada es un modelo de Pydantic v1 y el modelo de salida (definido en `response_model=ItemV2`) es un modelo de Pydantic v2.
+
+### Parámetros de Pydantic v1 { #pydantic-v1-parameters }
+
+Si necesitas usar algunas de las herramientas específicas de FastAPI para parámetros como `Body`, `Query`, `Form`, etc. con modelos de Pydantic v1, puedes importarlas de `fastapi.temp_pydantic_v1_params` mientras terminas la migración a Pydantic v2:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *}
+
+### Migra por pasos { #migrate-in-steps }
+
+/// tip | Consejo
+
+Primero prueba con `bump-pydantic`, si tus tests pasan y eso funciona, entonces terminaste con un solo comando. ✨
+
+///
+
+Si `bump-pydantic` no funciona para tu caso de uso, puedes usar la compatibilidad de modelos Pydantic v1 y v2 en la misma app para hacer la migración a Pydantic v2 de forma gradual.
+
+Podrías primero actualizar Pydantic para usar la última versión 2, y cambiar los imports para usar `pydantic.v1` para todos tus modelos.
+
+Luego puedes empezar a migrar tus modelos de Pydantic v1 a v2 por grupos, en pasos graduales. 🚶
diff --git a/docs/es/docs/how-to/separate-openapi-schemas.md b/docs/es/docs/how-to/separate-openapi-schemas.md
index b77915851..903313599 100644
--- a/docs/es/docs/how-to/separate-openapi-schemas.md
+++ b/docs/es/docs/how-to/separate-openapi-schemas.md
@@ -1,18 +1,18 @@
-# Separación de Esquemas OpenAPI para Entrada y Salida o No
+# Separación de Esquemas OpenAPI para Entrada y Salida o No { #separate-openapi-schemas-for-input-and-output-or-not }
-Al usar **Pydantic v2**, el OpenAPI generado es un poco más exacto y **correcto** que antes. 😎
+Desde que se lanzó **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
+## Modelos Pydantic para Entrada y Salida { #pydantic-models-for-input-and-output }
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
+### Modelo para Entrada { #model-for-input }
Si usas este modelo como entrada, como aquí:
@@ -20,7 +20,7 @@ Si usas este modelo como entrada, como aquí:
...entonces el campo `description` **no será requerido**. Porque tiene un valor por defecto de `None`.
-### Modelo de Entrada en la Documentación
+### Modelo de Entrada en la Documentación { #input-model-in-docs }
Puedes confirmar eso en la documentación, el campo `description` no tiene un **asterisco rojo**, no está marcado como requerido:
@@ -28,7 +28,7 @@ Puedes confirmar eso en la documentación, el campo `description` no tiene un **
-### Modelo para Salida
+### Modelo para Salida { #model-for-output }
Pero si usas el mismo modelo como salida, como aquí:
@@ -36,7 +36,7 @@ Pero si usas el mismo modelo como salida, como aquí:
...entonces, porque `description` tiene un valor por defecto, si **no devuelves nada** para ese campo, aún tendrá ese **valor por defecto**.
-### Modelo para Datos de Response de Salida
+### Modelo para Datos de Response de Salida { #model-for-output-response-data }
Si interactúas con la documentación y revisas el response, aunque el código no agregó nada en uno de los campos `description`, el response JSON contiene el valor por defecto (`null`):
@@ -46,7 +46,7 @@ Si interactúas con la documentación y revisas el response, aunque el código n
Esto significa que **siempre tendrá un valor**, solo que a veces el valor podría ser `None` (o `null` en JSON).
-Eso significa que, los clientes que usan tu API no tienen que comprobar si el valor existe o no, pueden **asumir que el campo siempre estará allí**, pero solo que en algunos casos tendrá el valor por defecto de `None`.
+Eso significa que, los clientes que usan tu API no tienen que revisar si el valor existe o no, pueden **asumir que el campo siempre estará allí**, pero solo que en algunos casos tendrá el valor por defecto de `None`.
La forma de describir esto en OpenAPI es marcar ese campo como **requerido**, porque siempre estará allí.
@@ -55,7 +55,7 @@ Debido a eso, el JSON Schema para un modelo puede ser diferente dependiendo de s
* para **entrada** el `description` **no será requerido**
* para **salida** será **requerido** (y posiblemente `None`, o en términos de JSON, `null`)
-### Modelo para Salida en la Documentación
+### Modelo para Salida en la Documentación { #model-for-output-in-docs }
También puedes revisar el modelo de salida en la documentación, **ambos** `name` y `description` están marcados como **requeridos** con un **asterisco rojo**:
@@ -63,7 +63,7 @@ También puedes revisar el modelo de salida en la documentación, **ambos** `nam
-### Modelo para Entrada y Salida en la Documentación
+### Modelo para Entrada y Salida en la Documentación { #model-for-input-and-output-in-docs }
Y si revisas todos los esquemas disponibles (JSON Schemas) en OpenAPI, verás que hay dos, uno `Item-Input` y uno `Item-Output`.
@@ -77,7 +77,7 @@ Pero para `Item-Output`, `description` **es requerido**, tiene un asterisco rojo
Con esta funcionalidad de **Pydantic v2**, la documentación de tu API es más **precisa**, y si tienes clientes y SDKs autogenerados, también serán más precisos, con una mejor **experiencia para desarrolladores** y consistencia. 🎉
-## No Separar Esquemas
+## No Separar Esquemas { #do-not-separate-schemas }
Ahora, hay algunos casos donde podrías querer tener el **mismo esquema para entrada y salida**.
@@ -85,7 +85,7 @@ Probablemente el caso principal para esto es si ya tienes algún código cliente
En ese caso, puedes desactivar esta funcionalidad en **FastAPI**, con el parámetro `separate_input_output_schemas=False`.
-/// info | Información
+/// info
El soporte para `separate_input_output_schemas` fue agregado en FastAPI `0.102.0`. 🤓
@@ -93,12 +93,10 @@ El soporte para `separate_input_output_schemas` fue agregado en FastAPI `0.102.0
{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *}
-### Mismo Esquema para Modelos de Entrada y Salida en la Documentación
+### Mismo Esquema para Modelos de Entrada y Salida en la Documentación { #same-schema-for-input-and-output-models-in-docs }
Y ahora habrá un único esquema para entrada y salida para el modelo, solo `Item`, y tendrá `description` como **no requerido**:
+
-
+
FastAPI framework, alto rendimiento, fácil de aprender, rápido de programar, listo para producción
@@ -27,7 +27,7 @@
---
-**Documentación**: https://fastapi.tiangolo.com
+**Documentación**: https://fastapi.tiangolo.com
**Código Fuente**: https://github.com/fastapi/fastapi
@@ -35,12 +35,12 @@
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.
-Las características clave son:
+Las funcionalidades clave son:
* **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.
+* **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.
@@ -48,24 +48,30 @@ Las características clave son:
* estimación basada en pruebas con un equipo de desarrollo interno, construyendo aplicaciones de producción.
-## Sponsors
+## Sponsors { #sponsors }
-{% if sponsors %}
+### Sponsor Keystone { #keystone-sponsor }
+
+{% for sponsor in sponsors.keystone -%}
+
+{% endfor -%}
+
+### Sponsors Oro y Plata { #gold-and-silver-sponsors }
+
{% for sponsor in sponsors.gold -%}
{% endfor -%}
{%- for sponsor in sponsors.silver -%}
{% endfor %}
-{% endif %}
-Otros sponsors
+Otros sponsors
-## Opiniones
+## Opiniones { #opinions }
"_[...] 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**._"
@@ -87,13 +93,13 @@ Las características clave son:
"_Estoy súper emocionado con **FastAPI**. ¡Es tan divertido!_"
-
+
+## **Typer**, el FastAPI de las CLIs { #typer-the-fastapi-of-clis }
-Si estás construyendo una aplicación de CLI para ser usada en el terminal en lugar de una API web, revisa **Typer**.
+Si estás construyendo una aplicación de CLI para ser usada en la terminal en lugar de una API web, revisa **Typer**.
**Typer** es el hermano pequeño de FastAPI. Y está destinado a ser el **FastAPI de las CLIs**. ⌨️ 🚀
-## Requisitos
+## Requisitos { #requirements }
FastAPI se apoya en hombros de gigantes:
-* Starlette para las partes web.
+* Starlette para las partes web.
* Pydantic para las partes de datos.
-## Instalación
+## Instalación { #installation }
-Crea y activa un entorno virtual y luego instala FastAPI:
+Crea y activa un entorno virtual y luego instala FastAPI:
fastapi dev main.py...
-### Actualización de la Documentación Alternativa de la API
+### Actualización de la documentación alternativa de la API { #alternative-api-docs-upgrade }
Y ahora, ve a <a href=){kind=link}
httpx - Requerido si deseas usar el `TestClient`.
-* jinja2 - Requerido si deseas usar la configuración de plantilla predeterminada.
+* jinja2 - Requerido si deseas usar la configuración de plantilla por defecto.
* python-multipart - Requerido si deseas soportar "parsing" de forms, con `request.form()`.
-Usadas por FastAPI / Starlette:
+Usadas por FastAPI:
-* 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`.
+* 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[standard]` - para proporcionar el comando `fastapi`.
+ * Esto incluye `fastapi-cloud-cli`, que te permite desplegar tu aplicación de FastAPI en FastAPI Cloud.
-### Sin Dependencias `standard`
+### Sin Dependencias `standard` { #without-standard-dependencies }
Si no deseas incluir las dependencias opcionales `standard`, puedes instalar con `pip install fastapi` en lugar de `pip install "fastapi[standard]"`.
-### Dependencias Opcionales Adicionales
+### Sin `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
+
+Si quieres instalar FastAPI con las dependencias standard pero sin `fastapi-cloud-cli`, puedes instalar con `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
+
+### Dependencias Opcionales Adicionales { #additional-optional-dependencies }
Existen algunas dependencias adicionales que podrías querer instalar.
@@ -491,6 +560,6 @@ Dependencias opcionales adicionales de FastAPI:
* orjson - Requerido si deseas usar `ORJSONResponse`.
* ujson - Requerido si deseas usar `UJSONResponse`.
-## Licencia
+## Licencia { #license }
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 cc6c7cc3f..4333bfcf6 100644
--- a/docs/es/docs/learn/index.md
+++ b/docs/es/docs/learn/index.md
@@ -1,4 +1,4 @@
-# Aprende
+# Aprende { #learn }
Aquí están las secciones introductorias y los tutoriales para aprender **FastAPI**.
diff --git a/docs/es/docs/project-generation.md b/docs/es/docs/project-generation.md
index 559995151..b4aa11d0d 100644
--- a/docs/es/docs/project-generation.md
+++ b/docs/es/docs/project-generation.md
@@ -1,4 +1,4 @@
-# Plantilla Full Stack FastAPI
+# Plantilla Full Stack FastAPI { #full-stack-fastapi-template }
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. 🏁
@@ -6,23 +6,23 @@ Puedes usar esta plantilla para comenzar, ya que incluye gran parte de la config
Repositorio de GitHub: Plantilla Full Stack FastAPI
-## Plantilla Full Stack FastAPI - Tecnología y Funcionalidades
+## Plantilla Full Stack FastAPI - Tecnología y Funcionalidades { #full-stack-fastapi-template-technology-stack-and-features }
-- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para la API del backend en Python.
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/es) 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.
+ - 💃 Usando TypeScript, hooks, Vite, y otras partes de una stack moderna de frontend.
+ - 🎨 [Tailwind CSS](https://tailwindcss.com) y [shadcn/ui](https://ui.shadcn.com) para los componentes del frontend.
- 🤖 Un cliente de frontend generado automáticamente.
- - 🧪 [Playwright](https://playwright.dev) para pruebas End-to-End.
+ - 🧪 [Playwright](https://playwright.dev) para escribir 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.
+- 📞 [Traefik](https://traefik.io) como proxy inverso / load balancer.
- 🚢 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 769204f8f..60b50a08f 100644
--- a/docs/es/docs/python-types.md
+++ b/docs/es/docs/python-types.md
@@ -1,4 +1,4 @@
-# Introducción a Tipos en Python
+# Introducción a Tipos en Python { #python-types-intro }
Python tiene soporte para "anotaciones de tipos" opcionales (también llamadas "type hints").
@@ -18,11 +18,11 @@ Si eres un experto en Python, y ya sabes todo sobre las anotaciones de tipos, sa
///
-## Motivación
+## Motivación { #motivation }
Comencemos con un ejemplo simple:
-{* ../../docs_src/python_types/tutorial001.py *}
+{* ../../docs_src/python_types/tutorial001_py39.py *}
Llamar a este programa genera:
@@ -36,9 +36,9 @@ La función hace lo siguiente:
* Convierte la primera letra de cada uno a mayúsculas con `title()`.
* Concatena ambos con un espacio en el medio.
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
-### Edítalo
+### Edítalo { #edit-it }
Es un programa muy simple.
@@ -58,7 +58,7 @@ Pero, tristemente, no obtienes nada útil:
-### Añadir tipos
+### Añadir tipos { #add-types }
Modifiquemos una sola línea de la versión anterior.
@@ -78,7 +78,7 @@ Eso es todo.
Esas son las "anotaciones de tipos":
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
Eso no es lo mismo que declarar valores predeterminados como sería con:
@@ -102,11 +102,11 @@ Con eso, puedes desplazarte, viendo las opciones, hasta que encuentres la que "t
-## Más motivación
+## Más motivación { #more-motivation }
Revisa esta función, ya tiene anotaciones de tipos:
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
Porque el editor conoce los tipos de las variables, no solo obtienes autocompletado, también obtienes chequeo de errores:
@@ -114,15 +114,15 @@ Porque el editor conoce los tipos de las variables, no solo obtienes autocomplet
Ahora sabes que debes corregirlo, convertir `age` a un string con `str(age)`:
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
-## Declaración de tipos
+## Declaración de tipos { #declaring-types }
Acabas de ver el lugar principal para declarar anotaciones de tipos. Como parámetros de función.
Este también es el lugar principal donde los utilizarías con **FastAPI**.
-### Tipos simples
+### Tipos simples { #simple-types }
Puedes declarar todos los tipos estándar de Python, no solo `str`.
@@ -133,9 +133,9 @@ Puedes usar, por ejemplo:
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
-### Tipos genéricos con parámetros de tipo
+### Tipos genéricos con parámetros de tipo { #generic-types-with-type-parameters }
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.
@@ -143,7 +143,7 @@ Estos tipos que tienen tipos internos se denominan tipos "**genéricos**". Y es
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
+#### Versiones más recientes de Python { #newer-versions-of-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.
@@ -157,60 +157,28 @@ Por ejemplo, "**Python 3.6+**" significa que es compatible con Python 3.6 o supe
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
+#### Lista { #list }
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/tutorial006_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-De `typing`, importa `List` (con una `L` mayúscula):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-Declara la variable, con la misma sintaxis de dos puntos (`:`).
-
-Como tipo, pon el `List` que importaste de `typing`.
-
-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_py39.py hl[1] *}
/// info | Información
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).
+En este caso, `str` es el parámetro de tipo pasado a `list`.
///
Eso significa: "la variable `items` es una `list`, y cada uno de los ítems en esta lista es un `str`".
-/// 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:
@@ -221,32 +189,18 @@ 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
+#### Tuple y Set { #tuple-and-set }
Harías lo mismo para declarar `tuple`s y `set`s:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
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 del tipo `bytes`.
-#### Dict
+#### Dict { #dict }
Para definir un `dict`, pasas 2 parámetros de tipo, separados por comas.
@@ -254,21 +208,7 @@ El primer parámetro de tipo es para las claves 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_py39.py hl[1] *}
Esto significa:
@@ -276,7 +216,7 @@ Esto significa:
* 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
+#### Union { #union }
Puedes declarar que una variable puede ser cualquier de **varios tipos**, por ejemplo, un `int` o un `str`.
@@ -292,24 +232,24 @@ En Python 3.10 también hay una **nueva sintaxis** donde puedes poner los posibl
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
```
////
En ambos casos, esto significa que `item` podría ser un `int` o un `str`.
-#### Posiblemente `None`
+#### Posiblemente `None` { #possibly-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!}
+{!../../docs_src/python_types/tutorial009_py39.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`.
@@ -326,23 +266,23 @@ Esto también significa que en Python 3.10, puedes usar `Something | None`:
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
////
-//// tab | Python 3.8+ alternative
+//// tab | Python 3.9+ alternativa
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
```
////
-#### Uso de `Union` u `Optional`
+#### Uso de `Union` u `Optional` { #using-union-or-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**:
@@ -357,7 +297,7 @@ Se trata solo de las palabras y nombres. Pero esas palabras pueden afectar cómo
Como ejemplo, tomemos esta función:
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+{* ../../docs_src/python_types/tutorial009c_py39.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:
@@ -377,7 +317,7 @@ La buena noticia es que, una vez que estés en Python 3.10, no tendrás que preo
Y entonces no tendrás que preocuparte por nombres como `Optional` y `Union`. 😎
-#### Tipos genéricos
+#### Tipos genéricos { #generic-types }
Estos tipos que toman parámetros de tipo en corchetes se llaman **Tipos Genéricos** o **Genéricos**, por ejemplo:
@@ -390,10 +330,10 @@ Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos d
* `set`
* `dict`
-Y lo mismo que con Python 3.8, desde el módulo `typing`:
+Y, como con versiones anteriores de Python, desde el módulo `typing`:
* `Union`
-* `Optional` (lo mismo que con Python 3.8)
+* `Optional`
* ...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.
@@ -409,7 +349,7 @@ Puedes usar los mismos tipos integrados como genéricos (con corchetes y tipos d
* `set`
* `dict`
-Y lo mismo que con Python 3.8, desde el módulo `typing`:
+Y generics desde el módulo `typing`:
* `Union`
* `Optional`
@@ -417,29 +357,17 @@ Y lo mismo que con Python 3.8, desde el módulo `typing`:
////
-//// tab | Python 3.8+
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...y otros.
-
-////
-
-### Clases como tipos
+### Clases como tipos { #classes-as-types }
También puedes declarar una clase como el tipo de una variable.
Digamos que tienes una clase `Person`, con un nombre:
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
Luego puedes declarar una variable para que sea de tipo `Person`:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
Y luego, nuevamente, obtienes todo el soporte del editor:
@@ -449,7 +377,7 @@ Nota que esto significa "`one_person` es una **instance** de la clase `Person`".
No significa "`one_person` es la **clase** llamada `Person`".
-## Modelos Pydantic
+## Modelos Pydantic { #pydantic-models }
Pydantic es un paquete de Python para realizar la validación de datos.
@@ -463,29 +391,7 @@ 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/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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial011_py310.py *}
/// info | Información
@@ -503,31 +409,13 @@ Pydantic tiene un comportamiento especial cuando utilizas `Optional` o `Union[So
///
-## Anotaciones de tipos con metadata
+## Anotaciones de tipos con metadata { #type-hints-with-metadata-annotations }
-Python también tiene una funcionalidad que permite poner **metadata adicional** en estas anotaciones de tipos usando `Annotated`.
+Python también tiene una funcionalidad que permite poner **metadatos 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`.
+Desde Python 3.9, `Annotated` es parte de la standard library, 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
Python en sí no hace nada con este `Annotated`. Y para los editores y otras herramientas, el tipo sigue siendo `str`.
@@ -547,7 +435,7 @@ Y también que tu código será muy compatible con muchas otras herramientas y p
///
-## Anotaciones de tipos en **FastAPI**
+## Anotaciones de tipos en **FastAPI** { #type-hints-in-fastapi }
**FastAPI** aprovecha estas anotaciones de tipos para hacer varias cosas.
diff --git a/docs/es/docs/resources/index.md b/docs/es/docs/resources/index.md
index 92898d319..324009561 100644
--- a/docs/es/docs/resources/index.md
+++ b/docs/es/docs/resources/index.md
@@ -1,3 +1,3 @@
-# Recursos
+# Recursos { #resources }
-Recursos adicionales, enlaces externos, artículos y más. ✈️
+Recursos adicionales, enlaces externos y más. ✈️
diff --git a/docs/es/docs/tutorial/background-tasks.md b/docs/es/docs/tutorial/background-tasks.md
index 3fe961e41..cc8a2c9cb 100644
--- a/docs/es/docs/tutorial/background-tasks.md
+++ b/docs/es/docs/tutorial/background-tasks.md
@@ -1,4 +1,4 @@
-# Tareas en Segundo Plano
+# Tareas en Segundo Plano { #background-tasks }
Puedes definir tareas en segundo plano para que se ejecuten *después* de devolver un response.
@@ -11,15 +11,15 @@ Esto incluye, por ejemplo:
* 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`
+## Usando `BackgroundTasks` { #using-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] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.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
+## Crear una función de tarea { #create-a-task-function }
Crea una función para que se ejecute como la tarea en segundo plano.
@@ -31,13 +31,13 @@ En este caso, la función de tarea escribirá en un archivo (simulando el envío
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] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
-## Agregar la tarea en segundo plano
+## Agregar la tarea en segundo plano { #add-the-background-task }
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] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
`.add_task()` recibe como argumentos:
@@ -45,7 +45,7 @@ Dentro de tu *path operation function*, pasa tu función de tarea al objeto de *
* 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
+## Inyección de Dependencias { #dependency-injection }
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.
@@ -59,9 +59,9 @@ Si hay un query en el request, se escribirá en el log en una tarea en segundo p
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
+## Detalles Técnicos { #technical-details }
-La clase `BackgroundTasks` proviene directamente de `starlette.background`.
+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`.
@@ -69,9 +69,9 @@ Al usar solo `BackgroundTasks` (y no `BackgroundTask`), es posible usarla como u
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.
+Puedes ver más detalles en la documentación oficial de Starlette sobre Background Tasks.
-## Advertencia
+## Advertencia { #caveat }
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.
@@ -79,6 +79,6 @@ Tienden a requerir configuraciones más complejas, un gestor de cola de mensajes
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
+## Resumen { #recap }
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
index c3d8f0686..7938a1215 100644
--- a/docs/es/docs/tutorial/bigger-applications.md
+++ b/docs/es/docs/tutorial/bigger-applications.md
@@ -1,4 +1,4 @@
-# Aplicaciones más grandes - Múltiples archivos
+# Aplicaciones más grandes - Múltiples archivos { #bigger-applications-multiple-files }
Si estás construyendo una aplicación o una API web, rara vez podrás poner todo en un solo archivo.
@@ -10,7 +10,7 @@ Si vienes de Flask, esto sería el equivalente a los Blueprints de Flask.
///
-## Un ejemplo de estructura de archivos
+## Un ejemplo de estructura de archivos { #an-example-file-structure }
Digamos que tienes una estructura de archivos como esta:
@@ -56,7 +56,7 @@ from app.routers import items
La misma estructura de archivos con comentarios:
-```
+```bash
.
├── app # "app" es un paquete de Python
│ ├── __init__.py # este archivo hace que "app" sea un "paquete de Python"
@@ -71,7 +71,7 @@ La misma estructura de archivos con comentarios:
│ └── admin.py # submódulo "admin", por ejemplo import app.internal.admin
```
-## `APIRouter`
+## `APIRouter` { #apirouter }
Digamos que el archivo dedicado solo a manejar usuarios es el submódulo en `/app/routers/users.py`.
@@ -81,23 +81,19 @@ Pero todavía es parte de la misma aplicación/web API de **FastAPI** (es parte
Puedes crear las *path operations* para ese módulo usando `APIRouter`.
-### Importar `APIRouter`
+### Importar `APIRouter` { #import-apirouter }
Lo importas y creas una "instance" de la misma manera que lo harías con la clase `FastAPI`:
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
-### *Path operations* con `APIRouter`
+### *Path operations* con `APIRouter` { #path-operations-with-apirouter }
Y luego lo usas para declarar tus *path operations*.
Úsalo de la misma manera que usarías la clase `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_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
Puedes pensar en `APIRouter` como una clase "mini `FastAPI`".
@@ -113,53 +109,25 @@ En este ejemplo, la variable se llama `router`, pero puedes nombrarla como quier
Vamos a incluir este `APIRouter` en la aplicación principal de `FastAPI`, pero primero, revisemos las dependencias y otro `APIRouter`.
-## Dependencias
+## Dependencias { #dependencies }
Vemos que vamos a necesitar algunas dependencias usadas en varios lugares de la aplicación.
Así que las ponemos en su propio módulo `dependencies` (`app/dependencies.py`).
-Ahora utilizaremos una dependencia simple para leer un encabezado `X-Token` personalizado:
-
-//// 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 | Consejo
-
-Preferiblemente usa la versión `Annotated` si es posible.
+Ahora utilizaremos una dependencia simple para leer un header `X-Token` personalizado:
-///
-
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!> ../../docs_src/bigger_applications/app/dependencies.py!}
-```
-
-////
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
/// tip | Consejo
-Estamos usando un encabezado inventado para simplificar este ejemplo.
+Estamos usando un header inventado para simplificar este ejemplo.
Pero en casos reales obtendrás mejores resultados usando las [utilidades de Seguridad](security/index.md){.internal-link target=_blank} integradas.
///
-## Otro módulo con `APIRouter`
+## Otro módulo con `APIRouter` { #another-module-with-apirouter }
Digamos que también tienes los endpoints dedicados a manejar "items" de tu aplicación en el módulo `app/routers/items.py`.
@@ -181,9 +149,7 @@ Sabemos que todas las *path operations* en este módulo tienen el mismo:
Entonces, en lugar de agregar todo eso a cada *path operation*, podemos agregarlo al `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_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
Como el path de cada *path operation* tiene que empezar con `/`, como en:
@@ -219,7 +185,7 @@ El resultado final es que los paths de item son ahora:
* Todos incluirán las `responses` predefinidas.
* Todas estas *path operations* tendrán la lista de `dependencies` evaluadas/ejecutadas antes de ellas.
* Si también declaras dependencias en una *path operation* específica, **también se ejecutarán**.
- * Las dependencias del router se ejecutan primero, luego las [dependencias en el decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, y luego las dependencias de parámetros normales.
+ * Las dependencias del router se ejecutan primero, luego las [`dependencies` en el decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, y luego las dependencias de parámetros normales.
* También puedes agregar [dependencias de `Security` con `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
/// tip | Consejo
@@ -234,7 +200,7 @@ Los parámetros `prefix`, `tags`, `responses`, y `dependencies` son (como en muc
///
-### Importar las dependencias
+### Importar las dependencias { #import-the-dependencies }
Este código vive en el módulo `app.routers.items`, el archivo `app/routers/items.py`.
@@ -242,15 +208,13 @@ Y necesitamos obtener la función de dependencia del módulo `app.dependencies`,
Así que usamos un import relativo con `..` para las dependencias:
-```Python hl_lines="3" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
-#### Cómo funcionan los imports relativos
+#### Cómo funcionan los imports relativos { #how-relative-imports-work }
/// tip | Consejo
-Si sabes perfectamente cómo funcionan los imports, continúa a la siguiente sección.
+Si sabes perfectamente cómo funcionan los imports, continúa a la siguiente sección abajo.
///
@@ -307,27 +271,25 @@ eso significaría:
Eso se referiría a algún paquete arriba de `app/`, con su propio archivo `__init__.py`, etc. Pero no tenemos eso. Así que, eso lanzaría un error en nuestro ejemplo. 🚨
-Pero ahora sabes cómo funciona, para que puedas usar imports relativos en tus propias aplicaciones sin importar cuán complejas sean. 🤓
+Pero ahora sabes cómo funciona, para que puedas usar imports relativos en tus propias apps sin importar cuán complejas sean. 🤓
-### Agregar algunos `tags`, `responses`, y `dependencies` personalizados
+### Agregar algunos `tags`, `responses`, y `dependencies` personalizados { #add-some-custom-tags-responses-and-dependencies }
No estamos agregando el prefijo `/items` ni los `tags=["items"]` a cada *path operation* porque los hemos añadido al `APIRouter`.
Pero aún podemos agregar _más_ `tags` que se aplicarán a una *path operation* específica, y también algunas `responses` extra específicas para esa *path operation*:
-```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
/// tip | Consejo
-Esta última *path operation* tendrá la combinación de tags: `["items", "custom"]`.
+Esta última path operation tendrá la combinación de tags: `["items", "custom"]`.
Y también tendrá ambas responses en la documentación, una para `404` y otra para `403`.
///
-## El `FastAPI` principal
+## El `FastAPI` principal { #the-main-fastapi }
Ahora, veamos el módulo en `app/main.py`.
@@ -335,27 +297,25 @@ Aquí es donde importas y usas la clase `FastAPI`.
Este será el archivo principal en tu aplicación que conecta todo.
-### Importar `FastAPI`
+Y como la mayor parte de tu lógica ahora vivirá en su propio módulo específico, el archivo principal será bastante simple.
+
+### Importar `FastAPI` { #import-fastapi }
-Importas y creas una clase `FastAPI` como de costumbre.
+Importas y creas una clase `FastAPI` como normalmente.
Y podemos incluso declarar [dependencias globales](dependencies/global-dependencies.md){.internal-link target=_blank} que se combinarán con las dependencias para cada `APIRouter`:
-```Python hl_lines="1 3 7" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
-### Importar el `APIRouter`
+### Importar el `APIRouter` { #import-the-apirouter }
Ahora importamos los otros submódulos que tienen `APIRouter`s:
-```Python hl_lines="4-5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *}
Como los archivos `app/routers/users.py` y `app/routers/items.py` son submódulos que son parte del mismo paquete de Python `app`, podemos usar un solo punto `.` para importarlos usando "imports relativos".
-### Cómo funciona la importación
+### Cómo funciona la importación { #how-the-importing-works }
La sección:
@@ -397,7 +357,7 @@ Para aprender más sobre Paquetes y Módulos de Python, lee
@@ -531,11 +481,11 @@ $ fastapi dev app/main.py
Y abre la documentación en http://127.0.0.1:8000/docs.
-Verás la documentación automática de la API, incluyendo los paths de todos los submódulos, usando los paths correctos (y prefijos) y las tags correctas:
+Verás la documentación automática de la API, incluyendo los paths de todos los submódulos, usando los paths correctos (y prefijos) y los tags correctos:
-## Incluir el mismo router múltiples veces con diferentes `prefix`
+## Incluir el mismo router múltiples veces con diferentes `prefix` { #include-the-same-router-multiple-times-with-different-prefix }
También puedes usar `.include_router()` múltiples veces con el *mismo* router usando diferentes prefijos.
@@ -543,7 +493,7 @@ Esto podría ser útil, por ejemplo, para exponer la misma API bajo diferentes p
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
+## Incluir un `APIRouter` en otro { #include-an-apirouter-in-another }
De la misma manera que puedes incluir un `APIRouter` en una aplicación `FastAPI`, puedes incluir un `APIRouter` en otro `APIRouter` usando:
@@ -551,4 +501,4 @@ De la misma manera que puedes incluir un `APIRouter` en una aplicación `FastAPI
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.
+Asegúrate de hacerlo antes de incluir `router` en la app 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
index d07d214ec..8902ce4e9 100644
--- a/docs/es/docs/tutorial/body-fields.md
+++ b/docs/es/docs/tutorial/body-fields.md
@@ -1,8 +1,8 @@
-# Body - Campos
+# Body - Campos { #body-fields }
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`
+## Importar `Field` { #import-field }
Primero, tienes que importarlo:
@@ -14,7 +14,7 @@ Fíjate que `Field` se importa directamente desde `pydantic`, no desde `fastapi`
///
-## Declarar atributos del modelo
+## Declarar atributos del modelo { #declare-model-attributes }
Después puedes utilizar `Field` con los atributos del modelo:
@@ -40,7 +40,7 @@ Observa cómo cada atributo del modelo con un tipo, un valor por defecto y `Fiel
///
-## Agregar información extra
+## Agregar información extra { #add-extra-information }
Puedes declarar información extra en `Field`, `Query`, `Body`, etc. Y será incluida en el JSON Schema generado.
@@ -53,7 +53,7 @@ Como estas claves no necesariamente tienen que ser parte de la especificación d
///
-## Resumen
+## Resumen { #recap }
Puedes utilizar `Field` de Pydantic para declarar validaciones adicionales y metadatos para los atributos del modelo.
diff --git a/docs/es/docs/tutorial/body-multiple-params.md b/docs/es/docs/tutorial/body-multiple-params.md
index df6560b62..57cec1674 100644
--- a/docs/es/docs/tutorial/body-multiple-params.md
+++ b/docs/es/docs/tutorial/body-multiple-params.md
@@ -1,24 +1,22 @@
-# Cuerpo - Múltiples Parámetros
+# Cuerpo - Múltiples Parámetros { #body-multiple-parameters }
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
+## Mezclar `Path`, `Query` y parámetros del cuerpo { #mix-path-query-and-body-parameters }
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`:
+Y también puedes declarar parámetros del cuerpo como opcionales, estableciendo el valor por defecto 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
+## Múltiples parámetros del cuerpo { #multiple-body-parameters }
En el ejemplo anterior, las *path operations* esperarían un cuerpo JSON con los atributos de un `Item`, como:
@@ -64,7 +62,7 @@ Ten en cuenta que aunque el `item` se declaró de la misma manera que antes, aho
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
+## Valores singulares en el cuerpo { #singular-values-in-body }
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`.
@@ -96,7 +94,7 @@ En este caso, **FastAPI** esperará un cuerpo como:
Nuevamente, convertirá los tipos de datos, validará, documentará, etc.
-## Múltiples parámetros de cuerpo y query
+## Múltiples parámetros de cuerpo y query { #multiple-body-params-and-query }
Por supuesto, también puedes declarar parámetros adicionales de query siempre que lo necesites, además de cualquier parámetro del cuerpo.
@@ -122,7 +120,7 @@ Por ejemplo:
///
-## Embeber un solo parámetro de cuerpo
+## Embeber un solo parámetro de cuerpo { #embed-a-single-body-parameter }
Supongamos que solo tienes un único parámetro de cuerpo `item` de un modelo Pydantic `Item`.
@@ -162,7 +160,7 @@ en lugar de:
}
```
-## Resumen
+## Resumen { #recap }
Puedes añadir múltiples parámetros de cuerpo a tu *path operation function*, aunque un request solo puede tener un único cuerpo.
diff --git a/docs/es/docs/tutorial/body-nested-models.md b/docs/es/docs/tutorial/body-nested-models.md
index 5b4cfc14c..0dfd6576f 100644
--- a/docs/es/docs/tutorial/body-nested-models.md
+++ b/docs/es/docs/tutorial/body-nested-models.md
@@ -1,8 +1,8 @@
-# Cuerpo - Modelos Anidados
+# Cuerpo - Modelos Anidados { #body-nested-models }
Con **FastAPI**, puedes definir, validar, documentar y usar modelos anidados de manera arbitraria (gracias a Pydantic).
-## Campos de lista
+## Campos de lista { #list-fields }
Puedes definir un atributo como un subtipo. Por ejemplo, una `list` en Python:
@@ -10,39 +10,19 @@ Puedes definir un atributo como un subtipo. Por ejemplo, una `list` en Python:
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
+## Campos de lista con parámetro de tipo { #list-fields-with-type-parameter }
Pero Python tiene una forma específica de declarar listas con tipos internos, o "parámetros de tipo":
-### Importar `List` de typing
+### Declarar una `list` con un parámetro de tipo { #declare-a-list-with-a-type-parameter }
-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:
+Para declarar tipos que tienen parámetros de tipo (tipos internos), como `list`, `dict`, `tuple`,
+pasa el/los tipo(s) interno(s) como "parámetros de tipo" usando corchetes: `[` y `]`
```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.
@@ -51,7 +31,7 @@ Así, en nuestro ejemplo, podemos hacer que `tags` sea específicamente una "lis
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## Tipos de conjunto
+## Tipos de conjunto { #set-types }
Pero luego pensamos en ello, y nos damos cuenta de que los tags no deberían repetirse, probablemente serían strings únicos.
@@ -67,7 +47,7 @@ Y siempre que emitas esos datos, incluso si la fuente tenía duplicados, se emit
Y también se anotará/documentará en consecuencia.
-## Modelos Anidados
+## Modelos Anidados { #nested-models }
Cada atributo de un modelo Pydantic tiene un tipo.
@@ -77,13 +57,13 @@ Así que, puedes declarar "objetos" JSON anidados profundamente con nombres de a
Todo eso, de manera arbitraria.
-### Definir un submodelo
+### Definir un submodelo { #define-a-submodel }
Por ejemplo, podemos definir un modelo `Image`:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### Usar el submodelo como tipo
+### Usar el submodelo como tipo { #use-the-submodel-as-a-type }
Y luego podemos usarlo como el tipo de un atributo:
@@ -112,7 +92,7 @@ Nuevamente, haciendo solo esa declaración, con **FastAPI** obtienes:
* Validación de datos
* Documentación automática
-## Tipos especiales y validación
+## Tipos especiales y validación { #special-types-and-validation }
Además de tipos singulares normales como `str`, `int`, `float`, etc., puedes usar tipos singulares más complejos que heredan de `str`.
@@ -124,7 +104,7 @@ Por ejemplo, como en el modelo `Image` tenemos un campo `url`, podemos declararl
El string será verificado para ser una URL válida, y documentado en JSON Schema / OpenAPI como tal.
-## Atributos con listas de submodelos
+## Atributos con listas de submodelos { #attributes-with-lists-of-submodels }
También puedes usar modelos Pydantic como subtipos de `list`, `set`, etc.:
@@ -162,7 +142,7 @@ Nota cómo la clave `images` ahora tiene una lista de objetos de imagen.
///
-## Modelos anidados profundamente
+## Modelos anidados profundamente { #deeply-nested-models }
Puedes definir modelos anidados tan profundamente como desees:
@@ -174,16 +154,10 @@ Observa cómo `Offer` tiene una lista de `Item`s, que a su vez tienen una lista
///
-## Cuerpos de listas puras
+## Cuerpos de listas puras { #bodies-of-pure-lists }
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]
```
@@ -192,7 +166,7 @@ como en:
{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## Soporte de editor en todas partes
+## Soporte de editor en todas partes { #editor-support-everywhere }
Y obtienes soporte de editor en todas partes.
@@ -204,7 +178,7 @@ No podrías obtener este tipo de soporte de editor si estuvieras trabajando dire
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
+## Cuerpos de `dict`s arbitrarios { #bodies-of-arbitrary-dicts }
También puedes declarar un cuerpo como un `dict` con claves de algún tipo y valores de algún otro tipo.
@@ -234,7 +208,7 @@ Y el `dict` que recibas como `weights` tendrá realmente claves `int` y valores
///
-## Resumen
+## Resumen { #recap }
Con **FastAPI** tienes la máxima flexibilidad proporcionada por los modelos Pydantic, manteniendo tu código simple, corto y elegante.
diff --git a/docs/es/docs/tutorial/body-updates.md b/docs/es/docs/tutorial/body-updates.md
index 26cd3345f..e75e29b54 100644
--- a/docs/es/docs/tutorial/body-updates.md
+++ b/docs/es/docs/tutorial/body-updates.md
@@ -1,6 +1,6 @@
-# Cuerpo - Actualizaciones
+# Body - Actualizaciones { #body-updates }
-## Actualización reemplazando con `PUT`
+## Actualización reemplazando con `PUT` { #update-replacing-with-put }
Para actualizar un ítem puedes utilizar la operación de HTTP `PUT`.
@@ -10,7 +10,7 @@ Puedes usar el `jsonable_encoder` para convertir los datos de entrada en datos q
`PUT` se usa para recibir datos que deben reemplazar los datos existentes.
-### Advertencia sobre el reemplazo
+### Advertencia sobre el reemplazo { #warning-about-replacing }
Esto significa que si quieres actualizar el ítem `bar` usando `PUT` con un body que contenga:
@@ -26,7 +26,7 @@ debido a que no incluye el atributo ya almacenado `"tax": 20.2`, el modelo de en
Y los datos se guardarían con ese "nuevo" `tax` de `10.5`.
-## Actualizaciones parciales con `PATCH`
+## Actualizaciones parciales con `PATCH` { #partial-updates-with-patch }
También puedes usar la operación de HTTP `PATCH` para actualizar *parcialmente* datos.
@@ -44,43 +44,27 @@ 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
+### Uso del parámetro `exclude_unset` de Pydantic { #using-pydantics-exclude-unset-parameter }
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
+### Uso del parámetro `update` de Pydantic { #using-pydantics-update-parameter }
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
+### Resumen de actualizaciones parciales { #partial-updates-recap }
En resumen, para aplicar actualizaciones parciales deberías:
@@ -90,9 +74,9 @@ En resumen, para aplicar actualizaciones parciales deberías:
* 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`).
+* Convertir el modelo copiado en algo que pueda almacenarse en tu DB (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.
+* Guardar los datos en tu DB.
* Devolver el modelo actualizado.
{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
diff --git a/docs/es/docs/tutorial/body.md b/docs/es/docs/tutorial/body.md
index 6d0aa7c60..dde39f78c 100644
--- a/docs/es/docs/tutorial/body.md
+++ b/docs/es/docs/tutorial/body.md
@@ -1,4 +1,4 @@
-# Request Body
+# Request Body { #request-body }
Cuando necesitas enviar datos desde un cliente (digamos, un navegador) a tu API, los envías como un **request body**.
@@ -18,13 +18,13 @@ Como no se recomienda, la documentación interactiva con Swagger UI no mostrará
///
-## Importar `BaseModel` de Pydantic
+## Importar `BaseModel` de Pydantic { #import-pydantics-basemodel }
Primero, necesitas importar `BaseModel` de `pydantic`:
{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## Crea tu modelo de datos
+## Crea tu modelo de datos { #create-your-data-model }
Luego, declaras tu modelo de datos como una clase que hereda de `BaseModel`.
@@ -32,7 +32,8 @@ 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.
+
+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 solo opcional.
Por ejemplo, el modelo anterior declara un “`object`” JSON (o `dict` en Python) como:
@@ -54,7 +55,7 @@ Por ejemplo, el modelo anterior declara un “`object`” JSON (o `dict` en Pyth
}
```
-## Decláralo como un parámetro
+## Decláralo como un parámetro { #declare-it-as-a-parameter }
Para añadirlo a tu *path operation*, decláralo de la misma manera que declaraste parámetros de path y query:
@@ -62,7 +63,7 @@ Para añadirlo a tu *path operation*, decláralo de la misma manera que declaras
...y declara su tipo como el modelo que creaste, `Item`.
-## Resultados
+## Resultados { #results }
Con solo esa declaración de tipo en Python, **FastAPI** hará lo siguiente:
@@ -73,9 +74,9 @@ Con solo esa declaración de tipo en Python, **FastAPI** hará lo siguiente:
* 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.
+* Esos esquemas serán parte del esquema de OpenAPI generado y usados por las UIs de documentación automática.
-## Documentación automática
+## Documentación automática { #automatic-docs }
Los JSON Schemas de tus modelos serán parte del esquema OpenAPI generado y se mostrarán en la documentación API interactiva:
@@ -85,7 +86,7 @@ Y también se utilizarán en la documentación API dentro de cada *path operatio
-## Soporte del editor
+## Soporte del editor { #editor-support }
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):
@@ -121,13 +122,13 @@ Mejora el soporte del editor para modelos de Pydantic, con:
///
-## Usa el modelo
+## Usa el modelo { #use-the-model }
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
+## Request body + parámetros de path { #request-body-path-parameters }
Puedes declarar parámetros de path y request body al mismo tiempo.
@@ -135,7 +136,8 @@ Puedes declarar parámetros de path y request body al mismo tiempo.
{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-## Request body + path + parámetros de query
+
+## Request body + path + parámetros de query { #request-body-path-query-parameters }
También puedes declarar parámetros de **body**, **path** y **query**, todos al mismo tiempo.
@@ -147,18 +149,18 @@ 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**.
+* Si el parámetro se declara como del tipo de un **modelo de Pydantic**, se interpretará como un **body** de request.
/// 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`.
+El `str | None` (Python 3.10+) o `Union` en `Union[str, None]` (Python 3.9+) 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
+## Sin Pydantic { #without-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}.
+Si no quieres usar modelos de Pydantic, también puedes usar parámetros **Body**. Consulta la documentación para [Body - Multiple Parameters: Singular values in 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
index ebdb59265..dab7d8c0a 100644
--- a/docs/es/docs/tutorial/cookie-param-models.md
+++ b/docs/es/docs/tutorial/cookie-param-models.md
@@ -1,4 +1,4 @@
-# Modelos de Cookies
+# Modelos de Cookies { #cookie-parameter-models }
Si tienes un grupo de **cookies** que están relacionadas, puedes crear un **modelo de Pydantic** para declararlas. 🍪
@@ -16,7 +16,7 @@ Esta misma técnica se aplica a `Query`, `Cookie`, y `Header`. 😎
///
-## Cookies con un Modelo de Pydantic
+## Cookies con un Modelo de Pydantic { #cookies-with-a-pydantic-model }
Declara los parámetros de **cookie** que necesites en un **modelo de Pydantic**, y luego declara el parámetro como `Cookie`:
@@ -24,7 +24,7 @@ Declara los parámetros de **cookie** que necesites en un **modelo de Pydantic**
**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
+## Revisa la Documentación { #check-the-docs }
Puedes ver las cookies definidas en la UI de la documentación en `/docs`:
@@ -42,7 +42,7 @@ Pero incluso si **rellenas los datos** y haces clic en "Execute", como la UI de
///
-## Prohibir Cookies Extra
+## Prohibir Cookies Extra { #forbid-extra-cookies }
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** las cookies que deseas recibir.
@@ -50,7 +50,7 @@ Tu API ahora tiene el poder de controlar su propio **cookies** en **FastAPI**. 😎
diff --git a/docs/es/docs/tutorial/cookie-params.md b/docs/es/docs/tutorial/cookie-params.md
index 45b113ff9..598872c0a 100644
--- a/docs/es/docs/tutorial/cookie-params.md
+++ b/docs/es/docs/tutorial/cookie-params.md
@@ -1,14 +1,14 @@
-# Parámetros de Cookie
+# Parámetros de Cookie { #cookie-parameters }
Puedes definir parámetros de Cookie de la misma manera que defines los parámetros `Query` y `Path`.
-## Importar `Cookie`
+## Importar `Cookie` { #import-cookie }
Primero importa `Cookie`:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## Declarar parámetros de `Cookie`
+## Declarar parámetros de `Cookie` { #declare-cookie-parameters }
Luego declara los parámetros de cookie usando la misma estructura que con `Path` y `Query`.
@@ -30,6 +30,16 @@ Para declarar cookies, necesitas usar `Cookie`, porque de lo contrario los pará
///
-## Resumen
+/// info | Información
+
+Ten en cuenta que, como **los navegadores manejan las cookies** de formas especiales y por detrás, **no** permiten fácilmente que **JavaScript** las toque.
+
+Si vas a la **UI de la documentación de la API** en `/docs` podrás ver la **documentación** de cookies para tus *path operations*.
+
+Pero incluso si **rellenas los datos** y haces clic en "Execute", como la UI de la documentación funciona con **JavaScript**, las cookies no se enviarán y verás un mensaje de **error** como si no hubieras escrito ningún valor.
+
+///
+
+## Resumen { #recap }
Declara cookies con `Cookie`, usando el mismo patrón común que `Query` y `Path`.
diff --git a/docs/es/docs/tutorial/cors.md b/docs/es/docs/tutorial/cors.md
index e493d4431..c1a23295e 100644
--- a/docs/es/docs/tutorial/cors.md
+++ b/docs/es/docs/tutorial/cors.md
@@ -1,8 +1,8 @@
-# CORS (Cross-Origin Resource Sharing)
+# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
CORS o "Cross-Origin Resource Sharing" se refiere a situaciones en las que un frontend que se ejecuta en un navegador tiene código JavaScript que se comunica con un backend, y el backend está en un "origen" diferente al frontend.
-## Origen
+## Origen { #origin }
Un origen es la combinación de protocolo (`http`, `https`), dominio (`myapp.com`, `localhost`, `localhost.tiangolo.com`) y puerto (`80`, `443`, `8080`).
@@ -14,7 +14,7 @@ Así que, todos estos son orígenes diferentes:
Aunque todos están en `localhost`, usan protocolos o puertos diferentes, por lo tanto, son "orígenes" diferentes.
-## Pasos
+## Pasos { #steps }
Entonces, digamos que tienes un frontend corriendo en tu navegador en `http://localhost:8080`, y su JavaScript está tratando de comunicarse con un backend corriendo en `http://localhost` (porque no especificamos un puerto, el navegador asumirá el puerto por defecto `80`).
@@ -24,7 +24,7 @@ Para lograr esto, el backend `:80` debe tener una lista de "orígenes permitidos
En este caso, la lista tendría que incluir `http://localhost:8080` para que el frontend `:8080` funcione correctamente.
-## Comodines
+## Comodines { #wildcards }
También es posible declarar la lista como `"*"` (un "comodín") para decir que todos están permitidos.
@@ -32,7 +32,7 @@ Pero eso solo permitirá ciertos tipos de comunicación, excluyendo todo lo que
Así que, para que todo funcione correctamente, es mejor especificar explícitamente los orígenes permitidos.
-## Usa `CORSMiddleware`
+## Usa `CORSMiddleware` { #use-corsmiddleware }
Puedes configurarlo en tu aplicación **FastAPI** usando el `CORSMiddleware`.
@@ -46,7 +46,7 @@ También puedes especificar si tu backend permite:
* Métodos HTTP específicos (`POST`, `PUT`) o todos ellos con el comodín `"*"`.
* Headers HTTP específicos o todos ellos con el comodín `"*"`.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
Los parámetros predeterminados utilizados por la implementación de `CORSMiddleware` son restrictivos por defecto, por lo que necesitarás habilitar explícitamente orígenes, métodos o headers particulares para que los navegadores estén permitidos de usarlos en un contexto de Cross-Domain.
@@ -56,23 +56,26 @@ Se admiten los siguientes argumentos:
* `allow_origin_regex` - Una cadena regex para coincidir con orígenes que deberían estar permitidos para hacer requests cross-origin. por ejemplo, `'https://.*\.example\.org'`.
* `allow_methods` - Una lista de métodos HTTP que deberían estar permitidos para requests cross-origin. Por defecto es `['GET']`. Puedes usar `['*']` para permitir todos los métodos estándar.
* `allow_headers` - Una lista de headers de request HTTP que deberían estar soportados para requests cross-origin. Por defecto es `[]`. Puedes usar `['*']` para permitir todos los headers. Los headers `Accept`, `Accept-Language`, `Content-Language` y `Content-Type` siempre están permitidos para requests CORS simples.
-* `allow_credentials` - Indica que las cookies deberían estar soportadas para requests cross-origin. Por defecto es `False`. Además, `allow_origins` no puede ser configurado a `['*']` para que las credenciales estén permitidas, los orígenes deben ser especificados.
+* `allow_credentials` - Indica que las cookies deberían estar soportadas para requests cross-origin. Por defecto es `False`.
+
+ Ninguno de `allow_origins`, `allow_methods` y `allow_headers` puede establecerse a `['*']` si `allow_credentials` está configurado a `True`. Todos deben ser especificados explícitamente.
+
* `expose_headers` - Indica cualquier header de response que debería ser accesible para el navegador. Por defecto es `[]`.
* `max_age` - Establece un tiempo máximo en segundos para que los navegadores almacenen en caché los responses CORS. Por defecto es `600`.
El middleware responde a dos tipos particulares de request HTTP...
-### Requests de preflight CORS
+### Requests de preflight CORS { #cors-preflight-requests }
Estos son cualquier request `OPTIONS` con headers `Origin` y `Access-Control-Request-Method`.
En este caso, el middleware interceptará el request entrante y responderá con los headers CORS adecuados, y un response `200` o `400` con fines informativos.
-### Requests simples
+### Requests simples { #simple-requests }
Cualquier request con un header `Origin`. En este caso, el middleware pasará el request a través de lo normal, pero incluirá los headers CORS adecuados en el response.
-## Más info
+## Más info { #more-info }
Para más información sobre CORS, revisa la documentación de CORS de Mozilla.
diff --git a/docs/es/docs/tutorial/debugging.md b/docs/es/docs/tutorial/debugging.md
index 2a7544e83..c31daf40f 100644
--- a/docs/es/docs/tutorial/debugging.md
+++ b/docs/es/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# Depuración
+# Depuración { #debugging }
Puedes conectar el depurador en tu editor, por ejemplo con Visual Studio Code o PyCharm.
-## Llama a `uvicorn`
+## Llama a `uvicorn` { #call-uvicorn }
En tu aplicación de FastAPI, importa y ejecuta `uvicorn` directamente:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### Acerca de `__name__ == "__main__"`
+### Acerca de `__name__ == "__main__"` { #about-name-main }
El objetivo principal de `__name__ == "__main__"` es tener algo de código que se ejecute cuando tu archivo es llamado con:
@@ -26,7 +26,7 @@ pero no es llamado cuando otro archivo lo importa, como en:
from myapp import app
```
-#### Más detalles
+#### Más detalles { #more-details }
Supongamos que tu archivo se llama `myapp.py`.
@@ -78,7 +78,7 @@ Para más información, revisa
-## Atajo
+## Atajo { #shortcut }
Pero ves que estamos teniendo algo de repetición de código aquí, escribiendo `CommonQueryParams` dos veces:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -205,7 +205,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ sin `Annotated`
+//// tab | Python 3.9+ sin `Annotated`
/// tip | Consejo
@@ -225,7 +225,7 @@ Para esos casos específicos, puedes hacer lo siguiente:
En lugar de escribir:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -233,7 +233,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ sin `Annotated`
+//// tab | Python 3.9+ sin `Annotated`
/// tip | Consejo
@@ -249,7 +249,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
...escribes:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends()]
@@ -257,7 +257,7 @@ commons: Annotated[CommonQueryParams, Depends()]
////
-//// tab | Python 3.8 sin `Annotated`
+//// tab | Python 3.9+ sin `Annotated`
/// tip | Consejo
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
index fbe17c67a..60baa93a9 100644
--- a/docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/es/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -1,4 +1,4 @@
-# Dependencias en decoradores de *path operation*
+# Dependencias en decoradores de *path operation* { #dependencies-in-path-operation-decorators }
En algunos casos realmente no necesitas el valor de retorno de una dependencia dentro de tu *path operation function*.
@@ -8,7 +8,7 @@ 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*
+## Agregar `dependencies` al decorador de *path operation* { #add-dependencies-to-the-path-operation-decorator }
El decorador de *path operation* recibe un argumento opcional `dependencies`.
@@ -36,23 +36,23 @@ Pero en casos reales, al implementar seguridad, obtendrías más beneficios usan
///
-## Errores de dependencias y valores de retorno
+## Errores de dependencias y valores de retorno { #dependencies-errors-and-return-values }
Puedes usar las mismas *funciones* de dependencia que usas normalmente.
-### Requisitos de dependencia
+### Requisitos de dependencia { #dependency-requirements }
Pueden declarar requisitos de request (como headers) u otras sub-dependencias:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### Lanzar excepciones
+### Lanzar excepciones { #raise-exceptions }
Estas dependencias pueden `raise` excepciones, igual que las dependencias normales:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### Valores de retorno
+### Valores de retorno { #return-values }
Y pueden devolver valores o no, los valores no serán usados.
@@ -60,10 +60,10 @@ Así que, puedes reutilizar una dependencia normal (que devuelve un valor) que y
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## Dependencias para un grupo de *path operations*
+## Dependencias para un grupo de *path operations* { #dependencies-for-a-group-of-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
+## Dependencias Globales { #global-dependencies }
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
index 94290443a..aa645daa4 100644
--- a/docs/es/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/es/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,8 +1,8 @@
-# Dependencias con yield
+# Dependencias con yield { #dependencies-with-yield }
-FastAPI admite dependencias que realizan algunos pasos adicionales después de finalizar.
+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.
+Para hacer esto, usa `yield` en lugar de `return`, y escribe los pasos adicionales (código) después.
/// tip | Consejo
@@ -10,7 +10,7 @@ Asegúrate de usar `yield` una sola vez por dependencia.
///
-/// note | Nota técnica
+/// note | Detalles técnicos
Cualquier función que sea válida para usar con:
@@ -23,21 +23,21 @@ De hecho, FastAPI usa esos dos decoradores internamente.
///
-## Una dependencia de base de datos con `yield`
+## Una dependencia de base de datos con `yield` { #a-database-dependency-with-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] *}
+{* ../../docs_src/dependencies/tutorial007_py39.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] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[4] *}
-El código posterior a la declaración `yield` se ejecuta después de crear el response pero antes de enviarla:
+El código posterior a la declaración `yield` se ejecuta después del response:
-{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[5:6] *}
/// tip | Consejo
@@ -47,7 +47,7 @@ Puedes usar funciones `async` o regulares.
///
-## Una dependencia con `yield` y `try`
+## Una dependencia con `yield` y `try` { #a-dependency-with-yield-and-try }
Si usas un bloque `try` en una dependencia con `yield`, recibirás cualquier excepción que se haya lanzado al usar la dependencia.
@@ -57,9 +57,9 @@ Por lo tanto, puedes buscar esa excepción específica dentro de la dependencia
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] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[3,5] *}
-## Sub-dependencias con `yield`
+## Sub-dependencias con `yield` { #sub-dependencies-with-yield }
Puedes tener sub-dependencias y "árboles" de sub-dependencias de cualquier tamaño y forma, y cualquiera o todas ellas pueden usar `yield`.
@@ -85,7 +85,7 @@ 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
+/// note | Detalles técnicos
Esto funciona gracias a los Context Managers de Python.
@@ -93,15 +93,17 @@ Esto funciona gracias a los > dep_req: Start request
+ Note over dep_req: Run code up to yield
+ dep_req ->> dep_func: Pass dependency
+ Note over dep_func: Run code up to yield
+ dep_func ->> operation: Run path operation with dependency
+ operation ->> dep_func: Return from path operation
+ Note over dep_func: Run code after yield
+ Note over dep_func: ✅ Dependency closed
+ dep_func ->> client: Send response to client
+ Note over client: Response sent
+ Note over dep_req: Run code after yield
+ Note over dep_req: ✅ Dependency closed
+```
-///
+## Dependencias con `yield`, `HTTPException`, `except` y Tareas en Background { #dependencies-with-yield-httpexception-except-and-background-tasks }
-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`.
+Las dependencias con `yield` han evolucionado con el tiempo para cubrir diferentes casos de uso y corregir algunos problemas.
-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.
+Si quieres ver qué ha cambiado en diferentes versiones de FastAPI, puedes leer más al respecto en la guía avanzada, en [Dependencias avanzadas - Dependencias con `yield`, `HTTPException`, `except` y Tareas en Background](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks){.internal-link target=_blank}.
-## Context Managers
+## Context Managers { #context-managers }
-### Qué son los "Context Managers"
+### Qué son los "Context Managers" { #what-are-context-managers }
Los "Context Managers" son aquellos objetos de Python que puedes usar en una declaración `with`.
@@ -240,7 +255,7 @@ Cuando el bloque `with` termina, se asegura de cerrar el archivo, incluso si hub
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`
+### Usando context managers en dependencias con `yield` { #using-context-managers-in-dependencies-with-yield }
/// warning | Advertencia
@@ -255,7 +270,7 @@ En Python, puedes crear Context Managers 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"
+## Qué es la "Inyección de Dependencias" { #what-is-dependency-injection }
**"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".
@@ -19,13 +19,13 @@ Esto es muy útil cuando necesitas:
Todo esto, mientras minimizas la repetición de código.
-## Primeros Pasos
+## Primeros Pasos { #first-steps }
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"
+### Crear una dependencia, o "dependable" { #create-a-dependency-or-dependable }
Primero enfoquémonos en la dependencia.
@@ -61,11 +61,11 @@ Asegúrate de [Actualizar la versión de FastAPI](../../deployment/versions.md#u
///
-### Importar `Depends`
+### Importar `Depends` { #import-depends }
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
-### Declarar la dependencia, en el "dependant"
+### Declarar la dependencia, en el "dependant" { #declare-the-dependency-in-the-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:
@@ -114,7 +114,7 @@ Solo la pasas a `Depends` y **FastAPI** sabe cómo hacer el resto.
///
-## Compartir dependencias `Annotated`
+## Compartir dependencias `Annotated` { #share-annotated-dependencies }
En los ejemplos anteriores, ves que hay un poquito de **duplicación de código**.
@@ -138,9 +138,9 @@ Pero porque **FastAPI** está basado en los estándares de Python, incluido `Ann
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***.
+Esto será especialmente útil cuando lo uses en una **gran code base** donde uses **las mismas dependencias** una y otra vez en **muchas *path operations***.
-## Usar `async` o no usar `async`
+## Usar `async` o no usar `async` { #to-async-or-not-to-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.
@@ -156,7 +156,7 @@ Si no lo sabes, revisa la sección [Async: *"¿Con prisa?"*](../../async.md#in-a
///
-## Integración con OpenAPI
+## Integración con OpenAPI { #integrated-with-openapi }
Todas las declaraciones de request, validaciones y requisitos de tus dependencias (y sub-dependencias) se integrarán en el mismo esquema de OpenAPI.
@@ -164,7 +164,7 @@ Así, la documentación interactiva tendrá toda la información de estas depend
-## Uso simple
+## Uso simple { #simple-usage }
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.
@@ -182,7 +182,7 @@ Otros términos comunes para esta misma idea de "inyección de dependencias" son
* inyectables
* componentes
-## Plug-ins de **FastAPI**
+## Plug-ins de **FastAPI** { #fastapi-plug-ins }
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*.
@@ -190,7 +190,7 @@ Y las dependencias se pueden crear de una manera muy simple e intuitiva que te p
Verás ejemplos de esto en los próximos capítulos, sobre bases de datos relacionales y NoSQL, seguridad, etc.
-## Compatibilidad de **FastAPI**
+## Compatibilidad de **FastAPI** { #fastapi-compatibility }
La simplicidad del sistema de inyección de dependencias hace que **FastAPI** sea compatible con:
@@ -203,7 +203,7 @@ La simplicidad del sistema de inyección de dependencias hace que **FastAPI** se
* sistemas de inyección de datos de response
* etc.
-## Simple y Poderoso
+## Simple y Poderoso { #simple-and-powerful }
Aunque el sistema de inyección de dependencias jerárquico es muy simple de definir y usar, sigue siendo muy poderoso.
@@ -243,7 +243,7 @@ admin_user --> activate_user
paying_user --> pro_items
```
-## Integrado con **OpenAPI**
+## Integrado con **OpenAPI** { #integrated-with-openapi_1 }
Todas estas dependencias, al declarar sus requisitos, también añaden parámetros, validaciones, etc. a tus *path operations*.
diff --git a/docs/es/docs/tutorial/dependencies/sub-dependencies.md b/docs/es/docs/tutorial/dependencies/sub-dependencies.md
index bba532207..e74d65d7e 100644
--- a/docs/es/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/es/docs/tutorial/dependencies/sub-dependencies.md
@@ -1,4 +1,4 @@
-# Sub-dependencias
+# Sub-dependencias { #sub-dependencies }
Puedes crear dependencias que tengan **sub-dependencias**.
@@ -6,7 +6,7 @@ Pueden ser tan **profundas** como necesites.
**FastAPI** se encargará de resolverlas.
-## Primera dependencia "dependable"
+## Primera dependencia "dependable" { #first-dependency-dependable }
Podrías crear una primera dependencia ("dependable") así:
@@ -16,7 +16,7 @@ Declara un parámetro de query opcional `q` como un `str`, y luego simplemente l
Esto es bastante simple (no muy útil), pero nos ayudará a centrarnos en cómo funcionan las sub-dependencias.
-## Segunda dependencia, "dependable" y "dependant"
+## Segunda dependencia, "dependable" y "dependant" { #second-dependency-dependable-and-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"):
@@ -29,7 +29,7 @@ Centrémonos en los parámetros declarados:
* 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
+## Usa la dependencia { #use-the-dependency }
Entonces podemos usar la dependencia con:
@@ -54,7 +54,7 @@ read_query["/items/"]
query_extractor --> query_or_cookie_extractor --> read_query
```
-## Usando la misma dependencia múltiples veces
+## Usando la misma dependencia múltiples veces { #using-the-same-dependency-multiple-times }
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.
@@ -62,7 +62,7 @@ Y guardará el valor devuelto en un ISO.
+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`.
diff --git a/docs/es/docs/tutorial/extra-data-types.md b/docs/es/docs/tutorial/extra-data-types.md
index 28775780f..e876921ba 100644
--- a/docs/es/docs/tutorial/extra-data-types.md
+++ b/docs/es/docs/tutorial/extra-data-types.md
@@ -1,4 +1,4 @@
-# Tipos de Datos Extra
+# Tipos de Datos Extra { #extra-data-types }
Hasta ahora, has estado usando tipos de datos comunes, como:
@@ -17,7 +17,7 @@ Y seguirás teniendo las mismas funcionalidades como hasta ahora:
* Validación de datos.
* Anotación y documentación automática.
-## Otros tipos de datos
+## Otros tipos de datos { #other-data-types }
Aquí hay algunos de los tipos de datos adicionales que puedes usar:
@@ -51,7 +51,7 @@ Aquí hay algunos de los tipos de datos adicionales que puedes usar:
* 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
+## Ejemplo { #example }
Aquí tienes un ejemplo de una *path operation* con parámetros usando algunos de los tipos anteriores.
diff --git a/docs/es/docs/tutorial/extra-models.md b/docs/es/docs/tutorial/extra-models.md
index 0380b9690..d72c73e24 100644
--- a/docs/es/docs/tutorial/extra-models.md
+++ b/docs/es/docs/tutorial/extra-models.md
@@ -1,4 +1,4 @@
-# Modelos Extra
+# Modelos Extra { #extra-models }
Continuando con el ejemplo anterior, será común tener más de un modelo relacionado.
@@ -16,27 +16,19 @@ Si no lo sabes, aprenderás qué es un "hash de contraseña" en los [capítulos
///
-## Múltiples modelos
+## Múltiples modelos { #multiple-models }
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
+### Acerca de `**user_in.model_dump()` { #about-user-in-model-dump }
-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
+#### `.model_dump()` de Pydantic { #pydantics-model-dump }
`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.
+Los modelos Pydantic tienen un método `.model_dump()` que devuelve un `dict` con los datos del modelo.
Así que, si creamos un objeto Pydantic `user_in` como:
@@ -47,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com
y luego llamamos a:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
```
ahora tenemos un `dict` con los datos en la variable `user_dict` (es un `dict` en lugar de un objeto modelo Pydantic).
@@ -58,7 +50,7 @@ Y si llamamos a:
print(user_dict)
```
-obtendremos un `dict` de Python con:
+obtendríamos un `dict` de Python con:
```Python
{
@@ -69,7 +61,7 @@ obtendremos un `dict` de Python con:
}
```
-#### Desempaquetando un `dict`
+#### Desempaquetando un `dict` { #unpacking-a-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.
@@ -101,31 +93,31 @@ UserInDB(
)
```
-#### Un modelo Pydantic a partir del contenido de otro
+#### Un modelo Pydantic a partir del contenido de otro { #a-pydantic-model-from-the-contents-of-another }
-Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.dict()`, este código:
+Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.model_dump()`, este código:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
UserInDB(**user_dict)
```
sería equivalente a:
```Python
-UserInDB(**user_in.dict())
+UserInDB(**user_in.model_dump())
```
-...porque `user_in.dict()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`.
+...porque `user_in.model_dump()` 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
+#### Desempaquetando un `dict` y palabras clave adicionales { #unpacking-a-dict-and-extra-keywords }
Y luego agregando el argumento de palabra clave adicional `hashed_password=hashed_password`, como en:
```Python
-UserInDB(**user_in.dict(), hashed_password=hashed_password)
+UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
```
...termina siendo como:
@@ -146,7 +138,7 @@ Las funciones adicionales de soporte `fake_password_hasher` y `fake_save_user` s
///
-## Reducir duplicación
+## Reducir duplicación { #reduce-duplication }
Reducir la duplicación de código es una de las ideas centrales en **FastAPI**.
@@ -156,7 +148,7 @@ Y estos modelos están compartiendo muchos de los datos y duplicando nombres y t
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).
+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 tipos, validación, etc).
Toda la conversión de datos, validación, documentación, etc. seguirá funcionando normalmente.
@@ -164,13 +156,13 @@ De esa manera, podemos declarar solo las diferencias entre los modelos (con `pas
{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
-## `Union` o `anyOf`
+## `Union` o `anyOf` { #union-or-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`:
+Para hacerlo, usa la anotación de tipos estándar de Python `typing.Union`:
/// note | Nota
@@ -180,22 +172,21 @@ Al definir una
```console
-$ fastapi dev 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 - Development mode ───────────╮
- │ │
- │ Serving at: http://127.0.0.1:8000 │
- │ │
- │ API docs: http://127.0.0.1:8000/docs │
- │ │
- │ Running in development mode, for production use: │
- │ │
- │ fastapi run │
- │ │
- ╰─────────────────────────────────────────────────────╯
-
-INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
-INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
-INFO: Started reloader process [2265862] using WatchFiles
-INFO: Started server process [2265873]
-INFO: Waiting for application startup.
-INFO: Application startup complete.
+$ fastapi dev main.py
+
+ FastAPI Starting development server 🚀
+
+ Searching for package file structure from directories
+ with __init__.py files
+ Importing from /home/user/code/awesomeapp
+
+ module 🐍 main.py
+
+ code Importing the FastAPI app object from the module with
+ the following code:
+
+ from main import app
+
+ app Using import string: main:app
+
+ server Server started at http://127.0.0.1:8000
+ server Documentation at http://127.0.0.1:8000/docs
+
+ tip Running in development mode, for production use:
+ fastapi run
+
+ Logs:
+
+ INFO Will watch for changes in these directories:
+ ['/home/user/code/awesomeapp']
+ INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C
+ to quit)
+ INFO Started reloader process [383138] using WatchFiles
+ INFO Started server process [383153]
+ INFO Waiting for application startup.
+ INFO Application startup complete.
```
-## Prohibir Headers Extra
+## Prohibir Headers Extra { #forbid-extra-headers }
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los headers que deseas recibir.
@@ -51,6 +51,22 @@ Por ejemplo, si el cliente intenta enviar un header `tool` con un valor de `plum
}
```
-## Resumen
+## Desactivar la conversión de guiones bajos { #disable-convert-underscores }
+
+De la misma forma que con los parámetros de header normales, cuando tienes caracteres de guion bajo en los nombres de los parámetros, se **convierten automáticamente en guiones**.
+
+Por ejemplo, si tienes un parámetro de header `save_data` en el código, el header HTTP esperado será `save-data`, y aparecerá así en la documentación.
+
+Si por alguna razón necesitas desactivar esta conversión automática, también puedes hacerlo para los modelos Pydantic de parámetros de header.
+
+{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *}
+
+/// warning | Advertencia
+
+Antes de establecer `convert_underscores` a `False`, ten en cuenta que algunos proxies y servidores HTTP no permiten el uso de headers con guiones bajos.
+
+///
+
+## Resumen { #summary }
Puedes usar **modelos Pydantic** para declarar **headers** en **FastAPI**. 😎
diff --git a/docs/es/docs/tutorial/header-params.md b/docs/es/docs/tutorial/header-params.md
index 9c0112bb2..12b4d1002 100644
--- a/docs/es/docs/tutorial/header-params.md
+++ b/docs/es/docs/tutorial/header-params.md
@@ -1,14 +1,14 @@
-# Parámetros de Header
+# Parámetros de Header { #header-parameters }
Puedes definir los parámetros de Header de la misma manera que defines los parámetros de `Query`, `Path` y `Cookie`.
-## Importar `Header`
+## Importar `Header` { #import-header }
Primero importa `Header`:
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *}
-## Declarar parámetros de `Header`
+## Declarar parámetros de `Header` { #declare-header-parameters }
Luego declara los parámetros de header usando la misma estructura que con `Path`, `Query` y `Cookie`.
@@ -30,7 +30,7 @@ Para declarar headers, necesitas usar `Header`, porque de otra forma los paráme
///
-## Conversión automática
+## Conversión automática { #automatic-conversion }
`Header` tiene un poquito de funcionalidad extra además de lo que proporcionan `Path`, `Query` y `Cookie`.
@@ -54,7 +54,7 @@ Antes de establecer `convert_underscores` a `False`, ten en cuenta que algunos p
///
-## Headers duplicados
+## Headers duplicados { #duplicate-headers }
Es posible recibir headers duplicados. Eso significa, el mismo header con múltiples valores.
@@ -84,7 +84,7 @@ El response sería como:
}
```
-## Recapitulación
+## Recapitulación { #recap }
Declara headers con `Header`, usando el mismo patrón común que `Query`, `Path` y `Cookie`.
diff --git a/docs/es/docs/tutorial/index.md b/docs/es/docs/tutorial/index.md
index dcfc6cdfb..7804b6854 100644
--- a/docs/es/docs/tutorial/index.md
+++ b/docs/es/docs/tutorial/index.md
@@ -1,4 +1,4 @@
-# Tutorial - Guía del Usuario
+# Tutorial - Guía del Usuario { #tutorial-user-guide }
Este tutorial te muestra cómo usar **FastAPI** con la mayoría de sus funcionalidades, paso a paso.
@@ -6,7 +6,7 @@ Cada sección se basa gradualmente en las anteriores, pero está estructurada pa
También está diseñado para funcionar como una referencia futura para que puedas volver y ver exactamente lo que necesitas.
-## Ejecuta el código
+## Ejecuta el código { #run-the-code }
Todos los bloques de código pueden ser copiados y usados directamente (de hecho, son archivos Python probados).
@@ -15,48 +15,39 @@ Para ejecutar cualquiera de los ejemplos, copia el código a un archivo `main.py
-## Identificador de licencia
+## Identificador de licencia { #license-identifier }
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] *}
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
-## Metadata para etiquetas
+## Metadata para etiquetas { #metadata-for-tags }
También puedes agregar metadata adicional para las diferentes etiquetas usadas para agrupar tus path operations con el parámetro `openapi_tags`.
@@ -52,13 +52,13 @@ Cada diccionario puede contener:
* `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
+### Crear metadata para etiquetas { #create-metadata-for-tags }
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] *}
+{* ../../docs_src/metadata/tutorial004_py39.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_).
@@ -68,11 +68,11 @@ No tienes que agregar metadata para todas las etiquetas que uses.
///
-### Usar tus etiquetas
+### Usar tus etiquetas { #use-your-tags }
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] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
/// info | Información
@@ -80,19 +80,19 @@ Lee más sobre etiquetas en [Configuración de Path Operation](path-operation-co
///
-### Revisa la documentación
+### Revisa la documentación { #check-the-docs }
Ahora, si revisas la documentación, mostrará toda la metadata adicional:
-### Orden de las etiquetas
+### Orden de las etiquetas { #order-of-tags }
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
+## URL de OpenAPI { #openapi-url }
Por defecto, el esquema OpenAPI se sirve en `/openapi.json`.
@@ -100,11 +100,11 @@ 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] *}
+{* ../../docs_src/metadata/tutorial002_py39.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
+## URLs de Docs { #docs-urls }
Puedes configurar las dos interfaces de usuario de documentación incluidas:
@@ -117,4 +117,4 @@ Puedes configurar las dos interfaces de usuario de documentación incluidas:
Por ejemplo, para configurar Swagger UI para que se sirva en `/documentation` y deshabilitar ReDoc:
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/es/docs/tutorial/middleware.md b/docs/es/docs/tutorial/middleware.md
index 296374525..de636a485 100644
--- a/docs/es/docs/tutorial/middleware.md
+++ b/docs/es/docs/tutorial/middleware.md
@@ -1,4 +1,4 @@
-# Middleware
+# Middleware { #middleware }
Puedes añadir middleware a las aplicaciones de **FastAPI**.
@@ -15,11 +15,11 @@ Un "middleware" es una función que trabaja con cada **request** antes de que se
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.
+Si hubiera tareas en segundo plano (cubiertas en la sección [Tareas en segundo plano](background-tasks.md){.internal-link target=_blank}, lo verás más adelante), se ejecutarán *después* de todo el middleware.
///
-## Crear un middleware
+## Crear un middleware { #create-a-middleware }
Para crear un middleware usas el decorador `@app.middleware("http")` encima de una función.
@@ -31,13 +31,13 @@ La función middleware recibe:
* 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] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip | Consejo
-Ten en cuenta que los custom proprietary headers se pueden añadir usando el prefijo 'X-'.
+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.
+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.
///
@@ -49,7 +49,7 @@ También podrías usar `from starlette.requests import Request`.
///
-### Antes y después de la `response`
+### Antes y después de la `response` { #before-and-after-the-response }
Puedes añadir código que se ejecute con la `request`, antes de que cualquier *path operation* la reciba.
@@ -57,7 +57,7 @@ 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] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *}
/// tip | Consejo
@@ -65,7 +65,30 @@ Aquí usamos
-### Tags con Enums
+### Tags con Enums { #tags-with-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.
@@ -46,15 +46,15 @@ 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] *}
+{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
-## Resumen y Descripción
+## Resumen y Descripción { #summary-and-description }
Puedes añadir un `summary` y `description`:
{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
-## Descripción desde docstring
+## Descripción desde docstring { #description-from-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í.
@@ -66,7 +66,7 @@ Será usado en la documentación interactiva:
-## Descripción del Response
+## Descripción del Response { #response-description }
Puedes especificar la descripción del response con el parámetro `response_description`:
@@ -88,11 +88,11 @@ Entonces, si no proporcionas una, **FastAPI** generará automáticamente una de
-## Deprecar una *path operation*
+## Deprecar una *path operation* { #deprecate-a-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] *}
+{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
Se marcará claramente como deprecado en la documentación interactiva:
@@ -102,6 +102,6 @@ Revisa cómo lucen las *path operations* deprecadas y no deprecadas:
-## Resumen
+## Resumen { #recap }
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
index 4ea01753b..569dd03dd 100644
--- a/docs/es/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/es/docs/tutorial/path-params-numeric-validations.md
@@ -1,8 +1,8 @@
-# Parámetros de Path y Validaciones Numéricas
+# Parámetros de Path y Validaciones Numéricas { #path-parameters-and-numeric-validations }
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
+## Importar Path { #import-path }
Primero, importa `Path` de `fastapi`, e importa `Annotated`:
@@ -18,7 +18,7 @@ Asegúrate de [Actualizar la versión de FastAPI](../deployment/versions.md#upgr
///
-## Declarar metadatos
+## Declarar metadatos { #declare-metadata }
Puedes declarar todos los mismos parámetros que para `Query`.
@@ -32,7 +32,7 @@ Un parámetro de path siempre es requerido ya que tiene que formar parte del pat
///
-## Ordena los parámetros como necesites
+## Ordena los parámetros como necesites { #order-the-parameters-as-you-need }
/// tip | Consejo
@@ -54,13 +54,13 @@ No importa para **FastAPI**. Detectará los parámetros por sus nombres, tipos y
Así que puedes declarar tu función como:
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.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
+## Ordena los parámetros como necesites, trucos { #order-the-parameters-as-you-need-tricks }
/// tip | Consejo
@@ -83,15 +83,15 @@ 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] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
-### Mejor con `Annotated`
+### Mejor con `Annotated` { #better-with-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
+## Validaciones numéricas: mayor o igual { #number-validations-greater-than-or-equal }
Con `Query` y `Path` (y otros que verás más adelante) puedes declarar restricciones numéricas.
@@ -99,7 +99,7 @@ Aquí, con `ge=1`, `item_id` necesitará ser un número entero "`g`reater than o
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
-## Validaciones numéricas: mayor que y menor o igual
+## Validaciones numéricas: mayor que y menor o igual { #number-validations-greater-than-and-less-than-or-equal }
Lo mismo aplica para:
@@ -108,19 +108,19 @@ Lo mismo aplica para:
{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
-## Validaciones numéricas: flotantes, mayor y menor
+## Validaciones numéricas: flotantes, mayor y menor { #number-validations-floats-greater-than-and-less-than }
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`.
+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.
+Y lo mismo para lt.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## Resumen
+## Resumen { #recap }
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}.
@@ -139,7 +139,7 @@ Todas ellas comparten los mismos parámetros para validación adicional y metada
///
-/// note | Nota técnica
+/// note | Detalles técnicos
Cuando importas `Query`, `Path` y otros de `fastapi`, en realidad son funciones.
diff --git a/docs/es/docs/tutorial/path-params.md b/docs/es/docs/tutorial/path-params.md
index 426280902..7ba49f3b0 100644
--- a/docs/es/docs/tutorial/path-params.md
+++ b/docs/es/docs/tutorial/path-params.md
@@ -1,8 +1,8 @@
-# Parámetros de Path
+# Parámetros de Path { #path-parameters }
Puedes declarar "parámetros" o "variables" de path con la misma sintaxis que se usa en los format strings de Python:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
El valor del parámetro de path `item_id` se pasará a tu función como el argumento `item_id`.
@@ -12,11 +12,11 @@ Así que, si ejecutas este ejemplo y vas a Conversión de datos { #data-conversion }
Si ejecutas este ejemplo y abres tu navegador en http://127.0.0.1:8000/items/3, verás un response de:
@@ -38,11 +38,11 @@ Si ejecutas este ejemplo y abres tu navegador en "parsing" automático de requests.
+Entonces, con esa declaración de tipo, **FastAPI** te ofrece "parsing" automático de request.
///
-## Validación de datos
+## Validación de datos { #data-validation }
Pero si vas al navegador en http://127.0.0.1:8000/items/foo, verás un bonito error HTTP de:
@@ -76,7 +76,7 @@ Esto es increíblemente útil mientras desarrollas y depuras código que interac
///
-## Documentación
+## Documentación { #documentation }
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:
@@ -90,7 +90,7 @@ Nota que el parámetro de path está declarado como un entero.
///
-## Beneficios basados en estándares, documentación alternativa
+## Beneficios basados en estándares, documentación alternativa { #standards-based-benefits-alternative-documentation }
Y porque el esquema generado es del estándar OpenAPI, hay muchas herramientas compatibles.
@@ -100,7 +100,7 @@ Debido a esto, el propio **FastAPI** proporciona una documentación de API alter
De la misma manera, hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.
-## Pydantic
+## Pydantic { #pydantic }
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.
@@ -108,7 +108,7 @@ Puedes usar las mismas declaraciones de tipo con `str`, `float`, `bool` y muchos
Varios de estos se exploran en los siguientes capítulos del tutorial.
-## El orden importa
+## El orden importa { #order-matters }
Al crear *path operations*, puedes encontrarte en situaciones donde tienes un path fijo.
@@ -118,21 +118,21 @@ Y luego también puedes tener un path `/users/{user_id}` para obtener datos sobr
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}`:
-{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *}
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] *}
+{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
La primera siempre será utilizada ya que el path coincide primero.
-## Valores predefinidos
+## Valores predefinidos { #predefined-values }
-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.
+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.
-### Crear una clase `Enum`
+### Crear una clase `Enum` { #create-an-enum-class }
Importa `Enum` y crea una subclase que herede de `str` y de `Enum`.
@@ -140,13 +140,7 @@ Al heredar de `str`, la documentación de la API podrá saber que los valores de
Luego crea atributos de clase con valores fijos, que serán los valores válidos disponibles:
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-
-/// info | Información
-
-Las enumeraciones (o enums) están disponibles en Python desde la versión 3.4.
-
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip | Consejo
@@ -154,33 +148,33 @@ Si te estás preguntando, "AlexNet", "ResNet" y "LeNet" son solo nombres de 
-## Prohibir Parámetros Query Extras
+## Prohibir Parámetros Query Extras { #forbid-extra-query-parameters }
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los parámetros query que deseas recibir.
@@ -57,7 +57,7 @@ Recibirán un response de **error** que les indica que el parámetro query `tool
}
```
-## Resumen
+## Resumen { #summary }
Puedes usar **modelos de Pydantic** para declarar **parámetros query** en **FastAPI**. 😎
diff --git a/docs/es/docs/tutorial/query-params-str-validations.md b/docs/es/docs/tutorial/query-params-str-validations.md
index 9cb76156f..4af4782f8 100644
--- a/docs/es/docs/tutorial/query-params-str-validations.md
+++ b/docs/es/docs/tutorial/query-params-str-validations.md
@@ -1,4 +1,4 @@
-# Parámetros de Query y Validaciones de String
+# Parámetros de Query y Validaciones de String { #query-parameters-and-string-validations }
**FastAPI** te permite declarar información adicional y validación para tus parámetros.
@@ -6,48 +6,28 @@ Tomemos esta aplicación como ejemplo:
{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
-El parámetro de query `q` es del tipo `Union[str, None]` (o `str | None` en Python 3.10), lo que significa que es de tipo `str` pero también podría ser `None`, y de hecho, el valor por defecto es `None`, así que FastAPI sabrá que no es requerido.
+El parámetro de query `q` es de tipo `str | None`, lo que significa que es de tipo `str` pero también podría ser `None`, y de hecho, el valor por defecto es `None`, así que FastAPI sabrá que no es requerido.
/// note | Nota
FastAPI sabrá que el valor de `q` no es requerido por el valor por defecto `= None`.
-El `Union` en `Union[str, None]` permitirá a tu editor darte un mejor soporte y detectar errores.
+Tener `str | None` permitirá que tu editor te dé un mejor soporte y detecte errores.
///
-## Validaciones adicionales
+## Validaciones adicionales { #additional-validation }
Vamos a hacer que, aunque `q` sea opcional, siempre que se proporcione, **su longitud no exceda los 50 caracteres**.
-### Importar `Query` y `Annotated`
+### Importar `Query` y `Annotated` { #import-query-and-annotated }
Para lograr eso, primero importa:
* `Query` desde `fastapi`
-* `Annotated` desde `typing` (o desde `typing_extensions` en Python por debajo de 3.9)
+* `Annotated` desde `typing`
-//// tab | Python 3.10+
-
-En Python 3.9 o superior, `Annotated` es parte de la biblioteca estándar, así que puedes importarlo desde `typing`.
-
-```Python hl_lines="1 3"
-{!> ../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-En versiones de Python por debajo de 3.9 importas `Annotated` desde `typing_extensions`.
-
-Ya estará instalado con FastAPI.
-
-```Python hl_lines="3-4"
-{!> ../../docs_src/query_params_str_validations/tutorial002_an.py!}
-```
-
-////
+{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
/// info | Información
@@ -59,9 +39,9 @@ Asegúrate de [Actualizar la versión de FastAPI](../deployment/versions.md#upgr
///
-## Usar `Annotated` en el tipo del parámetro `q`
+## Usar `Annotated` en el tipo del parámetro `q` { #use-annotated-in-the-type-for-the-q-parameter }
-¿Recuerdas que te dije antes que `Annotated` puede ser usado para agregar metadatos a tus parámetros en la [Introducción a Tipos de Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
+¿Recuerdas que te dije antes que `Annotated` puede usarse para agregar metadatos a tus parámetros en la [Introducción a Tipos de Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
Ahora es el momento de usarlo con FastAPI. 🚀
@@ -75,7 +55,7 @@ q: str | None = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Union[str, None] = None
@@ -93,7 +73,7 @@ q: Annotated[str | None] = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Annotated[Union[str, None]] = None
@@ -105,7 +85,7 @@ Ambas versiones significan lo mismo, `q` es un parámetro que puede ser un `str`
Ahora vamos a lo divertido. 🎉
-## Agregar `Query` a `Annotated` en el parámetro `q`
+## Agregar `Query` a `Annotated` en el parámetro `q` { #add-query-to-annotated-in-the-q-parameter }
Ahora que tenemos este `Annotated` donde podemos poner más información (en este caso algunas validaciones adicionales), agrega `Query` dentro de `Annotated`, y establece el parámetro `max_length` a `50`:
@@ -127,9 +107,9 @@ FastAPI ahora:
* Mostrará un **error claro** para el cliente cuando los datos no sean válidos
* **Documentará** el parámetro en el OpenAPI esquema *path operation* (así aparecerá en la **UI de documentación automática**)
-## Alternativa (antigua): `Query` como valor por defecto
+## Alternativa (antigua): `Query` como valor por defecto { #alternative-old-query-as-the-default-value }
-Versiones anteriores de FastAPI (antes de 0.95.0) requerían que usaras `Query` como el valor por defecto de tu parámetro, en lugar de ponerlo en `Annotated`. Hay una alta probabilidad de que veas código usándolo alrededor, así que te lo explicaré.
+Versiones anteriores de FastAPI (antes de 0.95.0) requerían que usaras `Query` como el valor por defecto de tu parámetro, en lugar de ponerlo en `Annotated`, hay una alta probabilidad de que veas código usándolo alrededor, así que te lo explicaré.
/// tip | Consejo
@@ -141,63 +121,32 @@ Así es como usarías `Query()` como el valor por defecto de tu parámetro de fu
{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
-Ya que en este caso (sin usar `Annotated`) debemos reemplazar el valor por defecto `None` en la función con `Query()`, ahora necesitamos establecer el valor por defecto con el parámetro `Query(default=None)`, esto sirve al mismo propósito de definir ese valor por defecto (al menos para FastAPI).
+Como en este caso (sin usar `Annotated`) debemos reemplazar el valor por defecto `None` en la función con `Query()`, ahora necesitamos establecer el valor por defecto con el parámetro `Query(default=None)`, esto sirve al mismo propósito de definir ese valor por defecto (al menos para FastAPI).
Entonces:
-```Python
-q: Union[str, None] = Query(default=None)
-```
-
-...hace que el parámetro sea opcional, con un valor por defecto de `None`, lo mismo que:
-
-```Python
-q: Union[str, None] = None
-```
-
-Y en Python 3.10 y superior:
-
```Python
q: str | None = Query(default=None)
```
...hace que el parámetro sea opcional, con un valor por defecto de `None`, lo mismo que:
-```Python
-q: str | None = None
-```
-
-Pero las versiones de `Query` lo declaran explícitamente como un parámetro de query.
-
-/// info | Información
-
-Ten en cuenta que la parte más importante para hacer un parámetro opcional es la parte:
-
-```Python
-= None
-```
-
-o la parte:
```Python
-= Query(default=None)
+q: str | None = None
```
-ya que usará ese `None` como el valor por defecto, y de esa manera hará el parámetro **no requerido**.
-
-La parte `Union[str, None]` permite que tu editor brinde un mejor soporte, pero no es lo que le dice a FastAPI que este parámetro no es requerido.
-
-///
+Pero la versión con `Query` lo declara explícitamente como un parámetro de query.
Luego, podemos pasar más parámetros a `Query`. En este caso, el parámetro `max_length` que se aplica a los strings:
```Python
-q: Union[str, None] = Query(default=None, max_length=50)
+q: str | None = Query(default=None, max_length=50)
```
-Esto validará los datos, mostrará un error claro cuando los datos no sean válidos, y documentará el parámetro en el esquema del *path operation* de OpenaPI.
+Esto validará los datos, mostrará un error claro cuando los datos no sean válidos, y documentará el parámetro en el esquema del *path operation* de OpenAPI.
-### `Query` como valor por defecto o en `Annotated`
+### `Query` como valor por defecto o en `Annotated` { #query-as-the-default-value-or-in-annotated }
Ten en cuenta que cuando uses `Query` dentro de `Annotated` no puedes usar el parámetro `default` para `Query`.
@@ -217,13 +166,13 @@ Así que utilizarías (preferentemente):
q: Annotated[str, Query()] = "rick"
```
-...o en code bases más antiguos encontrarás:
+...o en code bases más antiguas encontrarás:
```Python
q: str = Query(default="rick")
```
-### Ventajas de `Annotated`
+### Ventajas de `Annotated` { #advantages-of-annotated }
**Usar `Annotated` es recomendado** en lugar del valor por defecto en los parámetros de función, es **mejor** por múltiples razones. 🤓
@@ -235,13 +184,13 @@ Cuando no usas `Annotated` y en su lugar usas el estilo de valor por defecto **(
Dado que `Annotated` puede tener más de una anotación de metadato, ahora podrías incluso usar la misma función con otras herramientas, como Typer. 🚀
-## Agregar más validaciones
+## Agregar más validaciones { #add-more-validations }
También puedes agregar un parámetro `min_length`:
{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *}
-## Agregar expresiones regulares
+## Agregar expresiones regulares { #add-regular-expressions }
Puedes definir una expresión regular `pattern` que el parámetro debe coincidir:
@@ -249,29 +198,15 @@ Puedes definir una Campos requeridos.
-
-///
-
-/// tip | Consejo
-
-Recuerda que en la mayoría de los casos, cuando algo es requerido, puedes simplemente omitir el default, así que normalmente no tienes que usar `...`.
-
-///
-
-## Lista de parámetros de Query / múltiples valores
+## Lista de parámetros de Query / múltiples valores { #query-parameter-list-multiple-values }
Cuando defines un parámetro de query explícitamente con `Query` también puedes declararlo para recibir una lista de valores, o dicho de otra manera, para recibir múltiples valores.
@@ -355,7 +266,7 @@ Entonces, con una URL como:
http://localhost:8000/items/?q=foo&q=bar
```
-recibirías los múltiples valores del *query parameter* `q` (`foo` y `bar`) en una `list` de Python dentro de tu *path operation function*, en el *parámetro de función* `q`.
+recibirías los múltiples valores de los *query parameters* `q` (`foo` y `bar`) en una `list` de Python dentro de tu *path operation function*, en el *parámetro de función* `q`.
Entonces, el response a esa URL sería:
@@ -378,9 +289,9 @@ La documentación interactiva de API se actualizará en consecuencia, para permi
-### Lista de parámetros de Query / múltiples valores con valores por defecto
+### Lista de parámetros de Query / múltiples valores con valores por defecto { #query-parameter-list-multiple-values-with-defaults }
-Y también puedes definir un valor por defecto `list` de valores si no se proporcionan ninguno:
+También puedes definir un valor por defecto `list` de valores si no se proporciona ninguno:
{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
@@ -401,9 +312,9 @@ el valor por defecto de `q` será: `["foo", "bar"]` y tu response será:
}
```
-#### Usando solo `list`
+#### Usando solo `list` { #using-just-list }
-También puedes usar `list` directamente en lugar de `List[str]` (o `list[str]` en Python 3.9+):
+También puedes usar `list` directamente en lugar de `list[str]`:
{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
@@ -411,11 +322,11 @@ También puedes usar `list` directamente en lugar de `List[str]` (o `list[str]`
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.
+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
+## Declarar más metadatos { #declare-more-metadata }
Puedes agregar más información sobre el parámetro.
@@ -437,7 +348,7 @@ Y una `description`:
{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## Alias para parámetros
+## Alias para parámetros { #alias-parameters }
Imagina que quieres que el parámetro sea `item-query`.
@@ -457,11 +368,11 @@ Entonces puedes declarar un `alias`, y ese alias será usado para encontrar el v
{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## Declarar parámetros obsoletos
+## Declarar parámetros obsoletos { #deprecating-parameters }
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.
+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`:
@@ -471,13 +382,75 @@ La documentación lo mostrará así:
-## Excluir parámetros de OpenAPI
+## Excluir parámetros de OpenAPI { #exclude-parameters-from-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
+## Validación personalizada { #custom-validation }
+
+Podría haber casos donde necesites hacer alguna **validación personalizada** que no puede hacerse con los parámetros mostrados arriba.
+
+En esos casos, puedes usar una **función validadora personalizada** que se aplique después de la validación normal (por ejemplo, después de validar que el valor es un `str`).
+
+Puedes lograr eso usando `AfterValidator` de Pydantic dentro de `Annotated`.
+
+/// tip | Consejo
+
+Pydantic también tiene `BeforeValidator` y otros. 🤓
+
+///
+
+Por ejemplo, este validador personalizado comprueba que el ID del ítem empiece con `isbn-` para un número de libro ISBN o con `imdb-` para un ID de URL de película de IMDB:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
+
+/// info | Información
+
+Esto está disponible con Pydantic versión 2 o superior. 😎
+
+///
+
+/// tip | Consejo
+
+Si necesitas hacer cualquier tipo de validación que requiera comunicarte con algún **componente externo**, como una base de datos u otra API, deberías usar **Dependencias de FastAPI**, las aprenderás más adelante.
+
+Estos validadores personalizados son para cosas que pueden comprobarse **solo** con los **mismos datos** provistos en el request.
+
+///
+
+### Entiende ese código { #understand-that-code }
+
+El punto importante es solo usar **`AfterValidator` con una función dentro de `Annotated`**. Si quieres, sáltate esta parte. 🤸
+
+---
+
+Pero si te da curiosidad este ejemplo de código específico y sigues entretenido, aquí tienes algunos detalles extra.
+
+#### String con `value.startswith()` { #string-with-value-startswith }
+
+¿Lo notaste? un string usando `value.startswith()` puede recibir una tupla, y comprobará cada valor en la tupla:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### Un ítem aleatorio { #a-random-item }
+
+Con `data.items()` obtenemos un objeto iterable con tuplas que contienen la clave y el valor para cada elemento del diccionario.
+
+Convertimos este objeto iterable en una `list` propiamente dicha con `list(data.items())`.
+
+Luego con `random.choice()` podemos obtener un **valor aleatorio** de la lista, así que obtenemos una tupla con `(id, name)`. Será algo como `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+
+Luego **asignamos esos dos valores** de la tupla a las variables `id` y `name`.
+
+Así, si el usuario no proporcionó un ID de ítem, aún recibirá una sugerencia aleatoria.
+
+...hacemos todo esto en una **sola línea simple**. 🤯 ¿No te encanta Python? 🐍
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
+
+## Recapitulación { #recap }
Puedes declarar validaciones y metadatos adicionales para tus parámetros.
@@ -494,6 +467,8 @@ Validaciones específicas para strings:
* `max_length`
* `pattern`
+Validaciones personalizadas usando `AfterValidator`.
+
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 9bd47f871..2b58a2b4b 100644
--- a/docs/es/docs/tutorial/query-params.md
+++ b/docs/es/docs/tutorial/query-params.md
@@ -1,8 +1,8 @@
-# Parámetros de Query
+# Parámetros de Query { #query-parameters }
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".
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *}
La query es el conjunto de pares clave-valor que van después del `?` en una URL, separados por caracteres `&`.
@@ -24,11 +24,11 @@ Pero cuando los declaras con tipos de Python (en el ejemplo anterior, como `int`
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
-## Valores por defecto
+## Valores por defecto { #defaults }
Como los parámetros de query no son una parte fija de un path, pueden ser opcionales y pueden tener valores por defecto.
@@ -57,19 +57,21 @@ Los valores de los parámetros en tu función serán:
* `skip=20`: porque lo configuraste en la URL
* `limit=10`: porque ese era el valor por defecto
-## Parámetros opcionales
+## Parámetros opcionales { #optional-parameters }
De la misma manera, puedes declarar parámetros de query opcionales, estableciendo su valor por defecto en `None`:
{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
+En este caso, el parámetro de función `q` será opcional y será `None` por defecto.
+
/// check | Revisa
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.
///
-## Conversión de tipos en parámetros de query
+## Conversión de tipos en parámetros de query { #query-parameter-type-conversion }
También puedes declarar tipos `bool`, y serán convertidos:
@@ -107,7 +109,7 @@ 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`. De lo contrario, será `False`.
-## Múltiples parámetros de path y de query
+## Múltiples parámetros de path y de query { #multiple-path-and-query-parameters }
Puedes declarar múltiples parámetros de path y de query al mismo tiempo, **FastAPI** sabe cuál es cuál.
@@ -117,7 +119,7 @@ Serán detectados por nombre:
{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## Parámetros de query requeridos
+## Parámetros de query requeridos { #required-query-parameters }
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.
@@ -125,7 +127,7 @@ Si no quieres agregar un valor específico pero solo hacer que sea opcional, est
Pero cuando quieres hacer un parámetro de query requerido, simplemente no declares ningún valor por defecto:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
Aquí el parámetro de query `needy` es un parámetro de query requerido de tipo `str`.
diff --git a/docs/es/docs/tutorial/request-files.md b/docs/es/docs/tutorial/request-files.md
index 330523c7e..cc99deb2e 100644
--- a/docs/es/docs/tutorial/request-files.md
+++ b/docs/es/docs/tutorial/request-files.md
@@ -1,4 +1,4 @@
-# Archivos de Request
+# Archivos de Request { #request-files }
Puedes definir archivos que serán subidos por el cliente utilizando `File`.
@@ -16,13 +16,13 @@ Esto es porque los archivos subidos se envían como "form data".
///
-## Importar `File`
+## Importar `File` { #import-file }
Importa `File` y `UploadFile` desde `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## Definir Parámetros `File`
+## Definir Parámetros `File` { #define-file-parameters }
Crea parámetros de archivo de la misma manera que lo harías para `Body` o `Form`:
@@ -50,7 +50,7 @@ Ten en cuenta que esto significa que todo el contenido se almacenará en memoria
Pero hay varios casos en los que podrías beneficiarte de usar `UploadFile`.
-## Parámetros de Archivo con `UploadFile`
+## Parámetros de Archivo con `UploadFile` { #file-parameters-with-uploadfile }
Define un parámetro de archivo con un tipo de `UploadFile`:
@@ -66,7 +66,7 @@ Usar `UploadFile` tiene varias ventajas sobre `bytes`:
* 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` { #uploadfile }
`UploadFile` tiene los siguientes atributos:
@@ -109,7 +109,7 @@ El `UploadFile` de **FastAPI** hereda directamente del `UploadFile` de **Starlet
///
-## Qué es "Form Data"
+## Qué es "Form Data" { #what-is-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.
@@ -121,7 +121,7 @@ Los datos de los forms normalmente se codifican usando el "media type" `applicat
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.
+Si deseas leer más sobre estas codificaciones y campos de formularios, dirígete a la MDN web docs para POST.
///
@@ -133,19 +133,19 @@ Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
-## Subida de Archivos Opcional
+## Subida de Archivos Opcional { #optional-file-upload }
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
+## `UploadFile` con Metadatos Adicionales { #uploadfile-with-additional-metadata }
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
+## Subidas de Múltiples Archivos { #multiple-file-uploads }
Es posible subir varios archivos al mismo tiempo.
@@ -165,12 +165,12 @@ También podrías usar `from starlette.responses import HTMLResponse`.
///
-### Subidas de Múltiples Archivos con Metadatos Adicionales
+### Subidas de Múltiples Archivos con Metadatos Adicionales { #multiple-file-uploads-with-additional-metadata }
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
+## Recapitulación { #recap }
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
index 9d5d7495a..1f4668c84 100644
--- a/docs/es/docs/tutorial/request-form-models.md
+++ b/docs/es/docs/tutorial/request-form-models.md
@@ -1,4 +1,4 @@
-# Modelos de Formulario
+# Modelos de Formulario { #form-models }
Puedes usar **modelos de Pydantic** para declarar **campos de formulario** en FastAPI.
@@ -20,7 +20,7 @@ Esto es compatible desde la versión `0.113.0` de FastAPI. 🤓
///
-## Modelos de Pydantic para Formularios
+## Modelos de Pydantic para Formularios { #pydantic-models-for-forms }
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`:
@@ -28,7 +28,7 @@ Solo necesitas declarar un **modelo de Pydantic** con los campos que quieres rec
**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
+## Revisa la Documentación { #check-the-docs }
Puedes verificarlo en la interfaz de documentación en `/docs`:
@@ -36,7 +36,7 @@ Puedes verificarlo en la interfaz de documentación en `/docs`:
-## Prohibir Campos de Formulario Extra
+## Prohibir Campos de Formulario Extra { #forbid-extra-form-fields }
En algunos casos de uso especiales (probablemente no muy comunes), podrías querer **restringir** los campos de formulario a solo aquellos declarados en el modelo de Pydantic. Y **prohibir** cualquier campo **extra**.
@@ -73,6 +73,6 @@ Recibirá un response de error indicando que el campo `extra` no está permitido
}
```
-## Resumen
+## Resumen { #summary }
Puedes usar modelos de Pydantic para declarar campos de formulario en FastAPI. 😎
diff --git a/docs/es/docs/tutorial/request-forms-and-files.md b/docs/es/docs/tutorial/request-forms-and-files.md
index 51dfbb357..363553e86 100644
--- a/docs/es/docs/tutorial/request-forms-and-files.md
+++ b/docs/es/docs/tutorial/request-forms-and-files.md
@@ -1,4 +1,4 @@
-# Request Forms and Files
+# Formularios y archivos del request { #request-forms-and-files }
Puedes definir archivos y campos de formulario al mismo tiempo usando `File` y `Form`.
@@ -14,11 +14,11 @@ $ pip install python-multipart
///
-## Importar `File` y `Form`
+## Importa `File` y `Form` { #import-file-and-form }
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *}
-## Definir parámetros `File` y `Form`
+## Define parámetros `File` y `Form` { #define-file-and-form-parameters }
Crea parámetros de archivo y formulario de la misma manera que lo harías para `Body` o `Query`:
@@ -36,6 +36,6 @@ Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
-## Resumen
+## Resumen { #recap }
Usa `File` y `Form` juntos cuando necesites recibir datos y archivos en el mismo request.
diff --git a/docs/es/docs/tutorial/request-forms.md b/docs/es/docs/tutorial/request-forms.md
index a9d62e660..33061e6a1 100644
--- a/docs/es/docs/tutorial/request-forms.md
+++ b/docs/es/docs/tutorial/request-forms.md
@@ -1,10 +1,10 @@
-# Form Data
+# Datos de formulario { #form-data }
Cuando necesitas recibir campos de formulario en lugar de JSON, puedes usar `Form`.
/// info | Información
-Para usar forms, primero instala `python-multipart`.
+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:
@@ -14,13 +14,13 @@ $ pip install python-multipart
///
-## Importar `Form`
+## Importar `Form` { #import-form }
Importar `Form` desde `fastapi`:
{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *}
-## Definir parámetros de `Form`
+## Definir parámetros de `Form` { #define-form-parameters }
Crea parámetros de formulario de la misma manera que lo harías para `Body` o `Query`:
@@ -28,7 +28,7 @@ Crea parámetros de formulario de la misma manera que lo harías para `Body` o `
Por ejemplo, en una de las formas en las que se puede usar la especificación OAuth2 (llamada "password flow") se requiere enviar un `username` y `password` como campos de formulario.
-La especificación requiere que los campos se llamen exactamente `username` y `password`, y que se envíen como campos de formulario, no JSON.
+La spec requiere que los campos se llamen exactamente `username` y `password`, y que se envíen como campos de formulario, no JSON.
Con `Form` puedes declarar las mismas configuraciones que con `Body` (y `Query`, `Path`, `Cookie`), incluyendo validación, ejemplos, un alias (por ejemplo, `user-name` en lugar de `username`), etc.
@@ -40,23 +40,23 @@ Con `Form` puedes declarar las mismas configuraciones que con `Body` (y `Query`,
/// tip | Consejo
-Para declarar bodies de forms, necesitas usar `Form` explícitamente, porque sin él, los parámetros se interpretarían como parámetros de query o como parámetros de body (JSON).
+Para declarar bodies de formularios, necesitas usar `Form` explícitamente, porque sin él, los parámetros se interpretarían como parámetros de query o como parámetros de body (JSON).
///
-## Sobre "Campos de Formulario"
+## Sobre "Campos de formulario" { #about-form-fields }
-La manera en que los forms HTML (``) envían los datos al servidor normalmente usa una codificación "especial" para esos datos, es diferente de JSON.
+La manera en que los formularios HTML (``) envían los datos al servidor normalmente usa una codificación "especial" para esos datos, es diferente de JSON.
**FastAPI** se encargará de leer esos datos del lugar correcto en lugar de JSON.
/// note | Detalles técnicos
-Los datos de forms normalmente se codifican usando el "media type" `application/x-www-form-urlencoded`.
+Los datos de formularios normalmente se codifican usando el "media type" `application/x-www-form-urlencoded`.
Pero cuando el formulario incluye archivos, se codifica como `multipart/form-data`. Leerás sobre la gestión de archivos en el próximo capítulo.
-Si quieres leer más sobre estas codificaciones y campos de formulario, dirígete a la MDN web docs para POST.
+Si quieres leer más sobre estas codificaciones y campos de formulario, dirígete a la MDN web docs para POST.
///
@@ -68,6 +68,6 @@ Esto no es una limitación de **FastAPI**, es parte del protocolo HTTP.
///
-## Recapitulación
+## Recapitulación { #recap }
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
index 09682f51b..8cfe69e78 100644
--- a/docs/es/docs/tutorial/response-model.md
+++ b/docs/es/docs/tutorial/response-model.md
@@ -1,8 +1,8 @@
-# Modelo de Response - Tipo de Retorno
+# Modelo de Response - Tipo de Retorno { #response-model-return-type }
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.
+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, lists, diccionarios, valores escalares como enteros, booleanos, etc.
{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
@@ -19,7 +19,7 @@ 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`
+## Parámetro `response_model` { #response-model-parameter }
Hay algunos casos en los que necesitas o quieres devolver algunos datos que no son exactamente lo que declara el tipo.
@@ -27,7 +27,7 @@ Por ejemplo, podrías querer **devolver un diccionario** u objeto de base de dat
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.
+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*:
@@ -57,7 +57,7 @@ De esa manera le dices al editor que intencionalmente estás devolviendo cualqui
///
-### Prioridad del `response_model`
+### Prioridad del `response_model` { #response-model-priority }
Si declaras tanto un tipo de retorno como un `response_model`, el `response_model` tomará prioridad y será utilizado por FastAPI.
@@ -65,7 +65,7 @@ De esta manera puedes añadir anotaciones de tipos correctas a tus funciones inc
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
+## Devolver los mismos datos de entrada { #return-the-same-input-data }
Aquí estamos declarando un modelo `UserIn`, contendrá una contraseña en texto plano:
@@ -105,7 +105,7 @@ Nunca almacenes la contraseña en texto plano de un usuario ni la envíes en un
///
-## Añadir un modelo de salida
+## Añadir un modelo de salida { #add-an-output-model }
Podemos en cambio crear un modelo de entrada con la contraseña en texto plano y un modelo de salida sin ella:
@@ -121,7 +121,7 @@ Aquí, aunque nuestra *path operation function* está devolviendo el mismo usuar
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
+### `response_model` o Tipo de Retorno { #response-model-or-return-type }
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.
@@ -129,7 +129,7 @@ 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
+## Tipo de Retorno y Filtrado de Datos { #return-type-and-data-filtering }
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**.
@@ -147,17 +147,17 @@ Con esto, obtenemos soporte de las herramientas, de los editores y mypy ya que e
¿Cómo funciona esto? Vamos a echarle un vistazo. 🤓
-### Anotaciones de Tipos y Herramientas
+### Anotaciones de Tipos y Herramientas { #type-annotations-and-tooling }
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`.
+Anotamos el tipo de retorno de la función como `BaseUser`, pero en realidad estamos devolviendo un `UserIn` instance.
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
+### Filtrado de Datos en FastAPI { #fastapi-data-filtering }
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.
@@ -165,7 +165,7 @@ FastAPI realiza varias cosas internamente con Pydantic para asegurarse de que es
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
+## Verlo en la documentación { #see-it-in-the-docs }
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:
@@ -175,29 +175,29 @@ Y ambos modelos se utilizarán para la documentación interactiva de la API:
-## Otras Anotaciones de Tipos de Retorno
+## Otras Anotaciones de Tipos de Retorno { #other-return-type-annotations }
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
+### Devolver un Response Directamente { #return-a-response-directly }
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] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.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
+### Anotar una Subclase de Response { #annotate-a-response-subclass }
También puedes usar una subclase de `Response` en la anotación del tipo:
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.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
+### Anotaciones de Tipos de Retorno Inválidas { #invalid-return-type-annotations }
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á.
@@ -207,7 +207,7 @@ Lo mismo sucedería si tuvieras algo como un I/O اشاره داره که نسبتاً "آروم" هستن (نسبت به سرعت پردازنده و حافظه RAM)، مثل منتظر موندن برای:
-
-* دادههایی که از کلاینت از طریق شبکه فرستاده میشن
-* دادههایی که برنامهات فرستاده تا از طریق شبکه به کلاینت برسه
-* محتوای یه فایل توی دیسک که سیستم بخوندش و به برنامهات بده
-* محتوایی که برنامهات به سیستم داده تا توی دیسک بنویسه
-* یه عملیات API از راه دور
-* یه عملیات دیتابیس که تموم بشه
-* یه کوئری دیتابیس که نتایجش برگرده
-* و غیره.
-
-چون زمان اجرا بیشتر صرف انتظار برای عملیات I/O میشه، بهشون میگن عملیات "I/O bound".
-
-بهش "ناهمزمان" میگن چون کامپیوتر / برنامه لازم نیست با کار آروم "همزمان" باشه، منتظر لحظه دقیق تموم شدن کار بمونه، در حالی که هیچ کاری نمیکنه، تا نتیجه رو بگیره و کارش رو ادامه بده.
-
-به جاش، چون یه سیستم "ناهمزمان" هست، وقتی کار تموم شد، میتونه یه کم توی صف منتظر بمونه (چند میکروثانیه) تا کامپیوتر / برنامه هر کاری که رفته بکنه رو تموم کنه، و بعد برگرده نتیجه رو بگیره و باهاش کار کنه.
-
-برای "همزمان" (برخلاف "ناهمزمان") معمولاً از اصطلاح "ترتیبی" هم استفاده میکنن، چون کامپیوتر / برنامه همه مراحل رو به ترتیب دنبال میکنه قبل از اینکه بره سراغ یه کار دیگه، حتی اگه اون مراحل شامل انتظار باشن.
-
-### همزمانی و برگرها
-
-این ایده **ناهمزمان** که بالا توضیح دادم گاهی بهش **"همزمانی"** هم میگن. با **"موازیسازی"** فرق داره.
-
-**همزمانی** و **موازیسازی** هر دو به "اتفاق افتادن چیزای مختلف کموبیش همزمان" ربط دارن.
-
-ولی جزئیات بین *همزمانی* و *موازیسازی* خیلی متفاوته.
-
-برای دیدن فرقش، این داستان در مورد برگرها رو تصور کن:
-
-### برگرهای همزمان
-
-با عشقت میری فستفود بگیرین، توی صف وایمیستی در حالی که صندوقدار سفارش آدمای جلوی تو رو میگیره. 😍
-
-
-
-بعد نوبت تو میشه، سفارش دو تا برگر خیلی شیک برای خودت و عشقت میدی. 🍔🍔
-
-
-
-صندوقدار یه چیزی به آشپز توی آشپزخونه میگه تا بدونن باید برگرهای تو رو آماده کنن (گرچه الان دارن برگرهای مشتریای قبلی رو درست میکنن).
-
-
-
-پول رو میدی. 💸
-
-صندوقدار شماره نوبتت رو بهت میده.
-
-
-
-وقتی منتظری، با عشقت میری یه میز انتخاب میکنی، میشینی و کلی با عشقت حرف میزنی (چون برگرهات خیلی شیکن و آماده کردنشون یه کم طول میکشه).
-
-وقتی پشت میز با عشقت نشستی، در حالی که منتظر برگرهایی، میتونی اون زمان رو صرف تحسین این کنی که عشقت چقدر باحال، ناز و باهوشه ✨😍✨.
-
-
-
-وقتی منتظری و با عشقت حرف میزنی، هر از گاهی شمارهای که رو پیشخون نشون داده میشه رو چک میکنی که ببینی نوبتت شده یا نه.
-
-بعد یه جایی بالاخره نوبتت میشه. میری پیشخون، برگرهات رو میگیری و برمیگردی سر میز.
-
-
-
-تو و عشقت برگرها رو میخورین و یه وقت خوب باهم دارین. ✨
-
-
-
-/// info
-
-تصاویر قشنگ از کترینا تامپسون. 🎨
-
-///
-
----
-
-تصور کن تو توی این داستان کامپیوتر / برنامه 🤖 هستی.
-
-وقتی توی صف هستی، فقط بیکاری 😴، منتظر نوبتت هستی، کار خیلی "مفیدی" نمیکنی. ولی صف سریع پیش میره چون صندوقدار فقط سفارش میگیره (آمادشون نمیکنه)، پس این خوبه.
-
-بعد، وقتی نوبتت میشه، کار "مفید" واقعی میکنی، منو رو پردازش میکنی، تصمیم میگیری چی میخوای، انتخاب عشقت رو میگیری، پول میدی، چک میکنی اسکناس یا کارت درست رو دادی، چک میکنی درست حساب شده، چک میکنی سفارش آیتمای درست رو داره و غیره.
-
-ولی بعد، گرچه هنوز برگرهات رو نداری، کارت با صندوقدار "موقتاً متوقف" ⏸ میشه، چون باید منتظر بمونی 🕙 تا برگرهات آماده بشن.
-
-ولی وقتی از پیشخون دور میشی و با شماره نوبتت سر میز میشینی، میتونی توجهت رو 🔀 به عشقت بدی و "کار" ⏯ 🤓 رو اون بکنی. بعدش دوباره داری یه چیز خیلی "مفید" انجام میدی، مثل لاس زدن با عشقت 😍.
-
-بعد صندوقدار 💁 با گذاشتن شمارهات رو نمایشگر پیشخون میگه "من با درست کردن برگرها تموم کردم"، ولی تو مثل دیوونهها وقتی شمارهات رو نمایشگر میاد فوری نمیپری. میدونی کسی برگرهات رو نمیدزده چون شماره نوبتت رو داری، و اونا هم مال خودشون رو دارن.
-
-پس منتظر میمونی تا عشقت داستانش رو تموم کنه (کار فعلی ⏯ / وظیفهای که داره پردازش میشه 🤓)، آروم لبخند میزنی و میگی که میری برگرها رو بیاری ⏸.
-
-بعد میری پیشخون 🔀، به کار اولیه که حالا تموم شده ⏯، برگرها رو میگیری، تشکر میکنی و میبرشون سر میز. این مرحله / وظیفه تعامل با پیشخون رو تموم میکنه ⏹. این به نوبه خودش یه وظیفه جدید، "خوردن برگرها" 🔀 ⏯، میسازه، ولی اون قبلی که "گرفتن برگرها" بود تموم شده ⏹.
-
-### برگرهای موازی
-
-حالا فرض کن اینا "برگرهای همزمان" نیستن، بلکه "برگرهای موازی" هستن.
-
-با عشقت میری فستفود موازی بگیری.
-
-توی صف وایمیستی در حالی که چند تا (مثلاً 8 تا) صندوقدار که همزمان آشپز هم هستن سفارش آدمای جلوی تو رو میگیرن.
-
-همه قبل تو منتظرن برگرهاشون آماده بشه قبل از اینکه پیشخون رو ترک کنن، چون هر کدوم از 8 تا صندوقدار میره و برگر رو همون موقع درست میکنه قبل از اینکه سفارش بعدی رو بگیره.
-
-
-
-بالاخره نوبت تو میشه، سفارش دو تا برگر خیلی شیک برای خودت و عشقت میدی.
-
-پول رو میدی 💸.
-
-
-
-صندوقدار میره آشپزخونه.
-
-منتظر میمونی، جلوی پیشخون وایستادی 🕙، که کسی قبل از تو برگرهات رو نگیره، چون شماره نوبت نیست.
-
-
-
-چون تو و عشقت مشغول این هستین که نذارین کسی جلوتون بیاد و هر وقت برگرها رسیدن اونا رو بگیره، نمیتونی به عشقت توجه کنی. 😞
-
-این کار "همزمان" هست، تو با صندوقدار/آشپز 👨🍳 "همزمان" هستی. باید منتظر بمونی 🕙 و درست همون لحظه که صندوقدار/آشپز 👨🍳 برگرها رو تموم میکنه و بهت میده اونجا باشی، وگرنه ممکنه یکی دیگه اونا رو بگیره.
-
-
-
-بعد صندوقدار/آشپزت 👨🍳 بالاخره بعد از یه مدت طولانی انتظار 🕙 جلوی پیشخون با برگرهات برمیگرده.
-
-
-
-برگرهات رو میگیری و با عشقت میری سر میز.
-
-فقط میخورینشون، و تمومه. ⏹
-
-
-
-حرف زدن یا لاس زدن زیاد نبود چون بیشتر وقت صرف انتظار 🕙 جلوی پیشخون شد. 😞
-
-/// info
-
-تصاویر قشنگ از کترینا تامپسون. 🎨
-
-///
-
----
-
-توی این سناریوی برگرهای موازی، تو یه کامپیوتر / برنامه 🤖 با دو تا پردازنده (تو و عشقت) هستی، هر دو منتظر 🕙 و توجهشون ⏯ رو برای مدت طولانی "انتظار جلوی پیشخون" 🕙 گذاشتن.
-
-فستفود 8 تا پردازنده (صندوقدار/آشپز) داره. در حالی که فستفود برگرهای همزمان شاید فقط 2 تا داشته (یه صندوقدار و یه آشپز).
-
-ولی با این حال، تجربه نهایی بهترین نیست. 😞
-
----
-
-این معادل موازی داستان برگرها بود. 🍔
-
-برای یه مثال "واقعیتر" از زندگی، یه بانک رو تصور کن.
-
-تا همین چند وقت پیش، بیشتر بانکها چند تا صندوقدار 👨💼👨💼👨💼👨💼 داشتن و یه صف بزرگ 🕙🕙🕙🕙🕙🕙🕙🕙.
-
-همه صندوقدارها کار رو با یه مشتری بعد از اون یکی 👨💼⏯ انجام میدادن.
-
-و باید توی صف 🕙 مدت زیادی منتظر بمونی وگرنه نوبتت رو از دست میدی.
-
-احتمالاً نمیخوای عشقت 😍 رو با خودت ببری بانک 🏦 برای کارای روزمره.
-
-### نتیجهگیری برگرها
-
-توی این سناریوی "برگرهای فستفود با عشقت"، چون کلی انتظار 🕙 هست، خیلی منطقیتره که یه سیستم همزمان ⏸🔀⏯ داشته باشی.
-
-این برای بیشتر برنامههای وب هم صدق میکنه.
-
-خیلی خیلی کاربر، ولی سرورت منتظر 🕙 اتصال نهچندان خوبشون هست تا درخواستهاشون رو بفرستن.
-
-و بعد دوباره منتظر 🕙 که جوابها برگردن.
-
-این "انتظار" 🕙 توی میکروثانیهها اندازهگیری میشه، ولی با این حال، جمعش که بکنی آخرش کلی انتظار میشه.
-
-برای همین استفاده از کد ناهمزمان ⏸🔀⏯ برای APIهای وب خیلی منطقیه.
-
-این نوع ناهمزمانی چیزیه که NodeJS رو محبوب کرد (گرچه NodeJS موازی نیست) و نقطه قوت Go بهعنوان یه زبون برنامهنویسیه.
-
-و همون سطح عملکردی هست که با **FastAPI** میگیری.
-
-و چون میتونی همزمانی و موازیسازی رو همزمان داشته باشی، عملکرد بالاتری از بیشتر فریمورکهای تستشده NodeJS میگیری و همتراز با Go، که یه زبون کامپایلشده نزدیک به C هست (همه اینا به لطف Starlette).
-
-### آیا همزمانی از موازیسازی بهتره؟
-
-نه! این نتیجه داستان نیست.
-
-همزمانی با موازیسازی فرق داره. و توی **سناریوهای خاص** که کلی انتظار دارن بهتره. به همین خاطر، معمولاً برای توسعه برنامههای وب خیلی از موازیسازی بهتره. ولی نه برای همهچیز.
-
-برای اینکه یه تعادل بذاریم، این داستان کوتاه رو تصور کن:
-
-> باید یه خونه بزرگ و کثیف رو تمیز کنی.
-
-*آره، کل داستان همینه*.
-
----
-
-هیچ انتظاری 🕙 اونجا نیست، فقط کلی کار برای انجام دادن توی جاهای مختلف خونه.
-
-میتونی مثل مثال برگرها نوبت بذاری، اول پذیرایی، بعد آشپزخونه، ولی چون منتظر چیزی نیستی 🕙، فقط داری تمیز میکنی و تمیز میکنی، نوبتها هیچ تأثیری نداره.
-
-با نوبت یا بدون نوبت (همزمانی) همون قدر طول میکشه تا تمومش کنی و همون مقدار کار رو کردی.
-
-ولی توی این موقعیت، اگه بتونی اون 8 تا صندوقدار/آشپز/حالا-تمیزکار رو بیاری، و هر کدومشون (بهعلاوه خودت) یه قسمت از خونه رو تمیز کنن، میتونی همه کار رو **موازی** انجام بدی، با کمک اضافی، و خیلی زودتر تمومش کنی.
-
-توی این سناریو، هر کدوم از تمیزکارها (از جمله خودت) یه پردازندهست که کار خودش رو میکنه.
-
-و چون بیشتر زمان اجرا صرف کار واقعی میشه (به جای انتظار)، و کار توی کامپیوتر با CPU انجام میشه، به این مشکلات میگن "CPU bound".
-
----
-
-مثالهای رایج عملیات CPU bound چیزایی هستن که نیاز به پردازش ریاضی پیچیده دارن.
-
-مثلاً:
-
-* پردازش **صدا** یا **تصویر**.
-* **بینایی کامپیوتری**: یه تصویر از میلیونها پیکسل تشکیل شده، هر پیکسل 3 تا مقدار / رنگ داره، پردازشش معمولاً نیاز داره چیزی رو رو اون پیکسلها همزمان حساب کنی.
-* **یادگیری ماشین**: معمولاً کلی ضرب "ماتریس" و "بردار" لازم داره. یه جدول بزرگ پر از عدد رو تصور کن که همهشون رو همزمان ضرب میکنی.
-* **یادگیری عمیق**: این یه زیرشاخه از یادگیری ماشینه، پس همون قضیه صدق میکنه. فقط این که یه جدول عدد برای ضرب کردن نیست، بلکه یه مجموعه بزرگ از اونا هست، و توی خیلی موارد از یه پردازنده خاص برای ساخت و / یا استفاده از این مدلها استفاده میکنی.
-
-### همزمانی + موازیسازی: وب + یادگیری ماشین
-
-با **FastAPI** میتونی از همزمانی که برای توسعه وب خیلی رایجه (همون جذابیت اصلی NodeJS) استفاده کنی.
-
-ولی میتونی از فواید موازیسازی و چندپردازشی (اجرای چند پروسه بهصورت موازی) برای کارای **CPU bound** مثل سیستمهای یادگیری ماشین هم بهره ببری.
-
-این، بهعلاوه این واقعیت ساده که پایتون زبون اصلی برای **علم داده**، یادگیری ماشین و بهخصوص یادگیری عمیقه، باعث میشه FastAPI یه انتخاب خیلی خوب برای APIها و برنامههای وب علم داده / یادگیری ماشین باشه (بین خیلی چیزای دیگه).
-
-برای دیدن اینکه چطور توی محیط واقعی به این موازیسازی برسی، بخش [استقرار](deployment/index.md){.internal-link target=_blank} رو ببین.
-
-## `async` و `await`
-
-نسخههای مدرن پایتون یه راه خیلی ساده و قابلفهم برای تعریف کد ناهمزمان دارن. این باعث میشه مثل کد "ترتیبی" معمولی به نظر بیاد و توی لحظههای درست "انتظار" رو برات انجام بده.
-
-وقتی یه عملیاتی هست که قبل از دادن نتیجهها نیاز به انتظار داره و از این قابلیتهای جدید پایتون پشتیبانی میکنه، میتونی اینجوری کدنویسیش کنی:
-
-```Python
-burgers = await get_burgers(2)
-```
-
-نکته کلیدی اینجا `await` هست. به پایتون میگه که باید ⏸ منتظر بمونه تا `get_burgers(2)` کارش 🕙 تموم بشه قبل از اینکه نتیجهها رو توی `burgers` ذخیره کنه. با این، پایتون میدونه که میتونه بره یه کار دیگه 🔀 ⏯ توی این مدت بکنه (مثل گرفتن یه درخواست دیگه).
-
-برای اینکه `await` کار کنه، باید توی یه تابع باشه که از این ناهمزمانی پشتیبانی کنه. برای این کار، فقط با `async def` تعریفش میکنی:
-
-```Python hl_lines="1"
-async def get_burgers(number: int):
- # یه سری کار ناهمزمان برای ساختن برگرها انجام بده
- return burgers
-```
-
-...به جای `def`:
-
-```Python hl_lines="2"
-# این ناهمزمان نیست
-def get_sequential_burgers(number: int):
- # یه سری کار ترتیبی برای ساختن برگرها انجام بده
- return burgers
-```
-
-با `async def`، پایتون میدونه که توی اون تابع باید حواسش به عبارتهای `await` باشه، و میتونه اجرای اون تابع رو "موقتاً متوقف" ⏸ کنه و بره یه کار دیگه 🔀 قبل از برگشتن بکنه.
-
-وقتی میخوای یه تابع `async def` رو صدا کنی، باید "منتظرش" بمونی. پس این کار نمیکنه:
-
-```Python
-# این کار نمیکنه، چون get_burgers با async def تعریف شده
-burgers = get_burgers(2)
-```
-
----
-
-پس، اگه از یه کتابخونه استفاده میکنی که بهت میگه میتونی با `await` صداش کنی، باید *توابع عملیات مسیرت* که ازش استفاده میکنن رو با `async def` بسازی، مثل:
-
-```Python hl_lines="2-3"
-@app.get('/burgers')
-async def read_burgers():
- burgers = await get_burgers(2)
- return burgers
-```
-
-### جزئیات فنیتر
-
-شاید متوجه شده باشی که `await` فقط توی توابعی که با `async def` تعریف شدن میتونه استفاده بشه.
-
-ولی در عین حال، توابعی که با `async def` تعریف شدن باید "منتظر"شون بمونی. پس توابع با `async def` فقط توی توابعی که با `async def` تعریف شدن میتونن صدا زده بشن.
-
-حالا، قضیه مرغ و تخممرغ چیه، چطور اولین تابع `async` رو صدا میکنی؟
-
-اگه با **FastAPI** کار میکنی، لازم نیست نگران این باشی، چون اون "اولین" تابع، *تابع عملیات مسیرت* هست، و FastAPI میدونه چطور کار درست رو بکنه.
-
-ولی اگه بخوای بدون FastAPI از `async` / `await` استفاده کنی، اینم ممکنه.
-
-### کد ناهمزمان خودت رو بنویس
-
-Starlette (و **FastAPI**) بر پایه AnyIO هستن، که باعث میشه با کتابخونه استاندارد پایتون asyncio و Trio سازگار باشه.
-
-بهخصوص، میتونی مستقیماً از AnyIO برای موارد استفاده پیشرفته همزمانی که نیاز به الگوهای پیچیدهتر توی کد خودت دارن استفاده کنی.
-
-و حتی اگه از FastAPI استفاده نکنی، میتونی برنامههای ناهمزمان خودت رو با AnyIO بنویسی تا خیلی سازگار باشه و فوایدش رو بگیری (مثل *همزمانی ساختاریافته*).
-
-من یه کتابخونه دیگه روی AnyIO ساختم، یه لایه نازک روش، تا یه کم annotationهای نوع رو بهتر کنم و **تکمیل خودکار** بهتر، **خطاهای درونخطی** و غیره بگیرم. یه مقدمه و آموزش ساده هم داره که بهت کمک میکنه **بفهمی** و **کد ناهمزمان خودت رو بنویسی**: Asyncer. اگه بخوای **کد ناهمزمان رو با کد معمولی** (بلاککننده/همزمان) ترکیب کنی خیلی بهدردت میخوره.
-
-### شکلهای دیگه کد ناهمزمان
-
-این سبک استفاده از `async` و `await` توی زبون نسبتاً جدیده.
-
-ولی کار با کد ناهمزمان رو خیلی سادهتر میکنه.
-
-همین سینتکس (یا تقریباً یکسان) اخیراً توی نسخههای مدرن جاوااسکریپت (توی مرورگر و NodeJS) هم اضافه شده.
-
-ولی قبل از اون، مدیریت کد ناهمزمان خیلی پیچیدهتر و سختتر بود.
-
-توی نسخههای قبلی پایتون، میتونستی از نخها یا Gevent استفاده کنی. ولی کد خیلی پیچیدهتر میشه برای فهمیدن، دیباگ کردن و فکر کردن بهش.
-
-توی نسخههای قبلی NodeJS / جاوااسکریپت مرورگر، از "کالبکها" استفاده میکردی. که میرسید به "جهان کالبکها".
-
-## کروتینها
-
-**کروتین** فقط یه اصطلاح خیلی شیک برای چیزیه که یه تابع `async def` برمیگردونه. پایتون میدونه که این یه چیزی مثل تابع هست، میتونه شروع بشه و یه جایی تموم بشه، ولی ممکنه داخلش هم موقف ⏸ بشه، هر وقت یه `await` توش باشه.
-
-ولی همه این قابلیت استفاده از کد ناهمزمان با `async` و `await` خیلی وقتا خلاصه میشه به استفاده از "کروتینها". این قابل مقایسه با ویژگی اصلی Go، یعنی "Goroutineها" هست.
-
-## نتیجهگیری
-
-بیاید همون جمله از بالا رو ببینیم:
-
-> نسخههای مدرن پایتون از **"کد ناهمزمان"** با چیزی که بهش **"کروتین"** میگن پشتیبانی میکنن، با سینتکس **`async` و `await`**.
-
-حالا باید بیشتر برات معنی بده. ✨
-
-همه اینا چیزیه که به FastAPI (از طریق Starlette) قدرت میده و باعث میشه عملکرد چشمگیری داشته باشه.
-
-## جزئیات خیلی فنی
-
-/// warning
-
-احتمالاً میتونی اینو رد کنی.
-
-اینا جزئیات خیلی فنی از نحوه کار **FastAPI** زیر پوستهست.
-
-اگه یه کم دانش فنی (کروتینها، نخها، بلاک کردن و غیره) داری و کنجکاوی که FastAPI چطور `async def` رو در مقابل `def` معمولی مدیریت میکنه، ادامه بده.
-
-///
-
-### توابع عملیات مسیر
-
-وقتی یه *تابع عملیات مسیر* رو با `def` معمولی به جای `async def` تعریف میکنی، توی یه استخر نخ خارجی اجرا میشه که بعدش منتظرش میمونن، به جای اینکه مستقیم صداش کنن (چون سرور رو بلاک میکنه).
-
-اگه از یه فریمورک ناهمزمان دیگه میای که به روش بالا کار نمیکنه و عادت داری *توابع عملیات مسیر* ساده فقط محاسباتی رو با `def` معمولی برای یه سود کوچیک عملکرد (حدود 100 نانوثانیه) تعریف کنی، توجه کن که توی **FastAPI** اثرش کاملاً برعکسه. توی این موارد، بهتره از `async def` استفاده کنی مگه اینکه *توابع عملیات مسیرت* کدی داشته باشن که عملیات I/O بلاککننده انجام بده.
-
-با این حال، توی هر دو موقعیت، احتمالش زیاده که **FastAPI** هنوز [سریعتر](index.md#performance){.internal-link target=_blank} از فریمورک قبلیات باشه (یا حداقل قابل مقایسه باهاش).
-
-### وابستگیها
-
-همین برای [وابستگیها](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/fa/docs/environment-variables.md b/docs/fa/docs/environment-variables.md
deleted file mode 100644
index 75309ce1f..000000000
--- a/docs/fa/docs/environment-variables.md
+++ /dev/null
@@ -1,298 +0,0 @@
-# متغیرهای محیطی
-
-/// tip
-
-اگه از قبل میدونی متغیرهای محیطی چی هستن و چطور ازشون استفاده میشه، میتونی این بخش رو رد کنی.
-
-///
-
-یه متغیر محیطی (که بهش "**env var**" هم میگن) یه متغیریه که **خارج** از کد پایتون، توی **سیستمعامل** زندگی میکنه و میتونه توسط کد پایتونت (یا برنامههای دیگه) خونده بشه.
-
-متغیرهای محیطی میتونن برای مدیریت **تنظیمات** برنامه، بهعنوان بخشی از **نصب** پایتون و غیره مفید باشن.
-
-## ساخت و استفاده از متغیرهای محیطی
-
-میتونی متغیرهای محیطی رو توی **شل (ترمینال)** **بسازی** و ازشون استفاده کنی، بدون اینکه به پایتون نیاز داشته باشی:
-
-//// tab | لینوکس، مکاواس، ویندوز بش
-
-
-
-
- فریمورک FastAPI، کارایی بالا، یادگیری آسان، کدنویسی سریع، آماده برای استفاده در محیط پروداکشن -
- - ---- - -**مستندات**: https://fastapi.tiangolo.com - -**کد منبع**: https://github.com/fastapi/fastapi - ---- -FastAPI یک وب فریمورک مدرن و سریع (با کارایی بالا) برای ایجاد APIهای متنوع (وب، وبسوکت و غبره) با زبان پایتون نسخه +۳.۶ است. این فریمورک با رعایت کامل راهنمای نوع داده (Type Hint) ایجاد شده است. - -ویژگیهای کلیدی این فریمورک عبارتند از: - -* **سرعت**: کارایی بسیار بالا و قابل مقایسه با **NodeJS** و **Go** (با تشکر از Starlette و Pydantic). [یکی از سریعترین فریمورکهای پایتونی موجود](#_10). - -* **کدنویسی سریع**: افزایش ۲۰۰ تا ۳۰۰ درصدی سرعت توسعه قابلیتهای جدید. * -* **باگ کمتر**: کاهش ۴۰ درصدی خطاهای انسانی (برنامهنویسی). * -* **هوشمندانه**: پشتیبانی فوقالعاده در محیطهای توسعه یکپارچه (IDE). تکمیل در همه بخشهای کد. کاهش زمان رفع باگ. -* **آسان**: طراحی شده برای یادگیری و استفاده آسان. کاهش زمان مورد نیاز برای مراجعه به مستندات. -* **کوچک**: کاهش تکرار در کد. چندین قابلیت برای هر پارامتر (منظور پارامترهای ورودی تابع هندلر میباشد، به بخش خلاصه در همین صفحه مراجعه شود). باگ کمتر. -* **استوار**: ایجاد کدی آماده برای استفاده در محیط پروداکشن و تولید خودکار مستندات تعاملی -* **مبتنی بر استانداردها**: مبتنی بر (و منطبق با) استانداردهای متن باز مربوط به API: OpenAPI (سوگر سابق) و JSON Schema. - -* تخمینها بر اساس تستهای انجام شده در یک تیم توسعه داخلی که مشغول ایجاد برنامههای کاربردی واقعی بودند صورت گرفته است. - -## اسپانسرهای طلایی - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-اگر در حال ساختن برنامهای برای استفاده در CLI (به جای استفاده در وب) هستید، میتوانید از **Typer**. استفاده کنید.
-
-**Typer** دوقلوی کوچکتر FastAPI است و قرار است معادلی برای FastAPI در برنامههای CLI باشد.️ 🚀
-
-## نیازمندیها
-
-پایتون +۳.۶
-
-FastAPI مبتنی بر ابزارهای قدرتمند زیر است:
-
-* فریمورک Starlette برای بخش وب.
-* کتابخانه Pydantic برای بخش داده.
-
-## نصب
-
-async def... نیز استفاده کنیدuvicorn main:app --reload...email-validator - برای اعتبارسنجی آدرسهای ایمیل.
-
-استفاده شده توسط Starlette:
-
-* HTTPX - در صورتی که میخواهید از `TestClient` استفاده کنید.
-* aiofiles - در صورتی که میخواهید از `FileResponse` و `StaticFiles` استفاده کنید.
-* jinja2 - در صورتی که بخواهید از پیکربندی پیشفرض برای قالبها استفاده کنید.
-* python-multipart - در صورتی که بخواهید با استفاده از `request.form()` از قابلیت "تجزیه (parse)" فرم استفاده کنید.
-* itsdangerous - در صورتی که بخواید از `SessionMiddleware` پشتیبانی کنید.
-* pyyaml - برای پشتیبانی `SchemaGenerator` در Starlet (به احتمال زیاد برای کار کردن با FastAPI به آن نیازی پیدا نمیکنید).
-* graphene - در صورتی که از `GraphQLApp` پشتیبانی میکنید.
-
-استفاده شده توسط FastAPI / Starlette:
-
-* uvicorn - برای سرور اجرا کننده برنامه وب.
-* orjson - در صورتی که بخواهید از `ORJSONResponse` استفاده کنید.
-* ujson - در صورتی که بخواهید از `UJSONResponse` استفاده کنید.
-
-میتوان همه این موارد را با استفاده از دستور `pip install fastapi[all]`. به صورت یکجا نصب کرد.
-
-## لایسنس
-
-این پروژه مشمول قوانین و مقررات لایسنس MIT است.
diff --git a/docs/fa/docs/learn/index.md b/docs/fa/docs/learn/index.md
deleted file mode 100644
index 06aa7f00e..000000000
--- a/docs/fa/docs/learn/index.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# یادگیری
-
-اینجا بخشهای مقدماتی و آموزشهایی هستن که برای یادگیری **FastAPI** بهت کمک میکنن.
-
-میتونی اینو یه **کتاب**، یه **دوره آموزشی**، یا راه **رسمی** و پیشنهادی برای یادگیری FastAPI در نظر بگیری. 😎
diff --git a/docs/fa/docs/python-types.md b/docs/fa/docs/python-types.md
deleted file mode 100644
index c428acbf7..000000000
--- a/docs/fa/docs/python-types.md
+++ /dev/null
@@ -1,578 +0,0 @@
-# مقدمهای بر انواع نوع در پایتون
-
-پایتون از "نوعنما"های اختیاری (که بهشون "type hints" یا "type annotations" هم میگن) پشتیبانی میکنه.
-
-این **"نوعنماها"** یا annotationها یه سینتکس خاص هستن که بهت اجازه میدن نوع یه متغیر رو مشخص کنی.
-
-با مشخص کردن نوع متغیرها، ویرایشگرها و ابزارها میتونن پشتیبانی بهتری بهت بدن.
-
-این فقط یه **آموزش سریع / یادآوری** در مورد نوعنماهای پایتونه. فقط حداقل چیزایی که برای استفاده ازشون با **FastAPI** لازمه رو پوشش میده... که در واقع خیلی کمه.
-
-**FastAPI** کاملاً بر پایه این نوعنماهاست و این بهش کلی مزیت و فایده میده.
-
-ولی حتی اگه هیچوقت از **FastAPI** استفاده نکنی، بازم یادگیری یه کم در موردشون به نفعته.
-
-/// note
-
-اگه حرفهای پایتونی و همهچیز رو در مورد نوعنماها میدونی، برو سراغ فصل بعدی.
-
-///
-
-## انگیزه
-
-بیاید با یه مثال ساده شروع کنیم:
-
-{* ../../docs_src/python_types/tutorial001.py *}
-
-وقتی این برنامه رو اجرا کنی، خروجی اینه:
-
-```
-John Doe
-```
-
-این تابع این کارا رو میکنه:
-
-* یه `first_name` و `last_name` میگیره.
-* حرف اول هر کدوم رو با `title()` بزرگ میکنه.
-* ترکیبشون میکنه با یه فاصله وسطشون.
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
-
-### ویرایشش کن
-
-این یه برنامه خیلی سادهست.
-
-ولی حالا تصور کن داری از صفر مینویسیش.
-
-یه جایی شروع کردی به تعریف تابع، پارامترهات آمادهست...
-
-ولی بعد باید "اون متدی که حرف اول رو بزرگ میکنه" رو صدا کنی.
-
-آیا اسمش `upper` بود؟ یا `uppercase`؟ شاید `first_uppercase`؟ یا `capitalize`؟
-
-بعد، با دوست قدیمی برنامهنویسا، تکمیل خودکار ویرایشگر، امتحان میکنی.
-
-پارامتر اول تابع، `first_name` رو تایپ میکنی، بعد یه نقطه (`.`) میذاری و `Ctrl+Space` رو میزنی تا تکمیل خودکار بیاد.
-
-ولی متأسفانه، چیز مفیدی نمیگیری:
-
-
-
-### نوع اضافه کن
-
-بیا فقط یه خط از نسخه قبلی رو تغییر بدیم.
-
-دقیقاً این بخش، پارامترهای تابع رو، از:
-
-```Python
- first_name, last_name
-```
-
-به:
-
-```Python
- first_name: str, last_name: str
-```
-
-عوض میکنیم.
-
-همینه.
-
-اینا همون "نوعنماها" هستن:
-
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
-
-این با تعریف مقدار پیشفرض فرق داره، مثل:
-
-```Python
- first_name="john", last_name="doe"
-```
-
-یه چیز متفاوته.
-
-ما از دونقطه (`:`) استفاده میکنیم، نه علامت مساوی (`=`).
-
-و اضافه کردن نوعنماها معمولاً چیزی که اتفاق میافته رو از چیزی که بدون اونا میافتاد تغییر نمیده.
-
-ولی حالا، دوباره تصور کن وسط ساختن اون تابع هستی، ولی این بار با نوعنماها.
-
-توی همون نقطه، سعی میکنی تکمیل خودکار رو با `Ctrl+Space` فعال کنی و اینو میبینی:
-
-
-
-با این، میتونی اسکرول کنی، گزینهها رو ببینی، تا وقتی که اون چیزی که "به نظرت آشنا میاد" رو پیدا کنی:
-
-
-
-## انگیزه بیشتر
-
-این تابع رو چک کن، الان نوعنما داره:
-
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
-
-چون ویرایشگر نوع متغیرها رو میدونه، فقط تکمیل خودکار نمیگیری، بلکه چک خطاها هم داری:
-
-
-
-حالا میدونی که باید درستش کنی، `age` رو با `str(age)` به یه رشته تبدیل کنی:
-
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-
-## تعریف نوعها
-
-تازه اصلیترین جا برای تعریف نوعنماها رو دیدی. بهعنوان پارامترهای تابع.
-
-این هم اصلیترین جاییه که با **FastAPI** ازشون استفاده میکنی.
-
-### نوعهای ساده
-
-میتونی همه نوعهای استاندارد پایتون رو تعریف کنی، نه فقط `str`.
-
-مثلاً میتونی از اینا استفاده کنی:
-
-* `int`
-* `float`
-* `bool`
-* `bytes`
-
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
-
-### نوعهای عمومی با پارامترهای نوع
-
-یه سری ساختار داده هستن که میتونن مقدارهای دیگه رو نگه دارن، مثل `dict`، `list`، `set` و `tuple`. و مقدارهای داخلیشون هم میتونن نوع خودشون رو داشته باشن.
-
-به این نوعها که نوعهای داخلی دارن میگن "**عمومی**" یا "generic". و میشه اونا رو تعریف کرد، حتی با نوعهای داخلیشون.
-
-برای تعریف این نوعها و نوعهای داخلیشون، میتونی از ماژول استاندارد پایتون `typing` استفاده کنی. این ماژول مخصوص پشتیبانی از نوعنماهاست.
-
-#### نسخههای جدیدتر پایتون
-
-سینتکس با استفاده از `typing` با همه نسخهها، از پایتون 3.6 تا جدیدترینها، از جمله پایتون 3.9، 3.10 و غیره **سازگاره**.
-
-با پیشرفت پایتون، **نسخههای جدیدتر** پشتیبانی بهتری برای این نوعنماها دارن و توی خیلی موارد حتی لازم نیست ماژول `typing` رو وارد کنی و ازش برای تعریف نوعنماها استفاده کنی.
-
-اگه بتونی برای پروژهات از یه نسخه جدیدتر پایتون استفاده کنی، میتونی از این سادگی اضافه بهره ببری.
-
-توی همه مستندات، مثالهایی هستن که با هر نسخه پایتون سازگارن (وقتی تفاوتی هست).
-
-مثلاً "**Python 3.6+**" یعنی با پایتون 3.6 یا بالاتر (مثل 3.7، 3.8، 3.9، 3.10 و غیره) سازگاره. و "**Python 3.9+**" یعنی با پایتون 3.9 یا بالاتر (مثل 3.10 و غیره) سازگاره.
-
-اگه بتونی از **جدیدترین نسخههای پایتون** استفاده کنی، از مثالهای نسخه آخر استفاده کن، چون اونا **بهترین و سادهترین سینتکس** رو دارن، مثلاً "**Python 3.10+**".
-
-#### لیست
-
-مثلاً، بیایم یه متغیر تعریف کنیم که یه `list` از `str` باشه.
-
-//// tab | Python 3.9+
-
-متغیر رو با همون سینتکس دونقطه (`:`) تعریف کن.
-
-بهعنوان نوع، `list` رو بذار.
-
-چون لیست یه نوعه که نوعهای داخلی داره، اونا رو توی کروشهها میذاری:
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-از `typing`، `List` رو (با `L` بزرگ) وارد کن:
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-متغیر رو با همون سینتکس دونقطه (`:`) تعریف کن.
-
-بهعنوان نوع، `List` رو که از `typing` وارد کردی بذار.
-
-چون لیست یه نوعه که نوعهای داخلی داره، اونا رو توی کروشهها میذاری:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
-
-/// info
-
-اون نوعهای داخلی توی کروشهها بهشون "پارامترهای نوع" میگن.
-
-توی این مورد، `str` پارامتر نوعیه که به `List` (یا `list` توی پایتون 3.9 و بالاتر) پاس داده شده.
-
-///
-
-یعنی: "متغیر `items` یه `list` هست، و هر کدوم از آیتمهای این لیست یه `str` هستن".
-
-/// tip
-
-اگه از پایتون 3.9 یا بالاتر استفاده میکنی، لازم نیست `List` رو از `typing` وارد کنی، میتونی همون نوع معمولی `list` رو به جاش استفاده کنی.
-
-///
-
-با این کار، ویرایشگرت حتی وقتی داری آیتمهای لیست رو پردازش میکنی بهت کمک میکنه:
-
-
-
-بدون نوعها، رسیدن به این تقریباً غیرممکنه.
-
-توجه کن که متغیر `item` یکی از عناصر توی لیست `items` هست.
-
-و با این حال، ویرایشگر میدونه که یه `str` هست و براش پشتیبانی میده.
-
-#### تاپل و ست
-
-برای تعریف `tuple`ها و `set`ها هم همین کار رو میکنی:
-
-//// 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!}
-```
-
-////
-
-یعنی:
-
-* متغیر `items_t` یه `tuple` با 3 تا آیتمه، یه `int`، یه `int` دیگه، و یه `str`.
-* متغیر `items_s` یه `set` هست، و هر کدوم از آیتمهاش از نوع `bytes` هستن.
-
-#### دیکشنری
-
-برای تعریف یه `dict`، 2 تا پارامتر نوع میدی، که با کاما از هم جدا شدن.
-
-پارامتر نوع اول برای کلیدهای `dict` هست.
-
-پارامتر نوع دوم برای مقدارهای `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!}
-```
-
-////
-
-یعنی:
-
-* متغیر `prices` یه `dict` هست:
- * کلیدهای این `dict` از نوع `str` هستن (مثلاً اسم هر آیتم).
- * مقدارهای این `dict` از نوع `float` هستن (مثلاً قیمت هر آیتم).
-
-#### اتحادیه
-
-میتونی تعریف کنی که یه متغیر میتونه هر کدوم از **چند تا نوع** باشه، مثلاً یه `int` یا یه `str`.
-
-توی پایتون 3.6 و بالاتر (از جمله پایتون 3.10) میتونی از نوع `Union` توی `typing` استفاده کنی و نوعهای ممکن رو توی کروشهها بذاری.
-
-توی پایتون 3.10 یه **سینتکس جدید** هم هست که میتونی نوعهای ممکن رو با یه خط عمودی (`|`) جدا کنی.
-
-//// 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!}
-```
-
-////
-
-توی هر دو حالت یعنی `item` میتونه یه `int` یا یه `str` باشه.
-
-#### شاید `None`
-
-میتونی تعریف کنی که یه مقدار میتونه یه نوع باشه، مثلاً `str`، ولی میتونه `None` هم باشه.
-
-توی پایتون 3.6 و بالاتر (از جمله پایتون 3.10) میتونی با وارد کردن و استفاده از `Optional` از ماژول `typing` اینو تعریف کنی.
-
-```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
-```
-
-استفاده از `Optional[str]` به جای فقط `str` به ویرایشگر کمک میکنه خطاهایی که ممکنه فکر کنی یه مقدار همیشه `str` هست رو پیدا کنه، در حالی که میتونه `None` هم باشه.
-
-`Optional[Something]` در واقع میانبر برای `Union[Something, None]` هست، این دو تا معادلن.
-
-یعنی توی پایتون 3.10، میتونی از `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+ جایگزین
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
-```
-
-////
-
-#### استفاده از `Union` یا `Optional`
-
-اگه از نسخه پایتون زیر 3.10 استفاده میکنی، یه نکته از دید خیلی **شخصی** خودم:
-
-* 🚨 از `Optional[SomeType]` استفاده نکن
-* به جاش ✨ **از `Union[SomeType, None]` استفاده کن** ✨.
-
-هر دو معادلن و زیر پوسته یکیان، ولی من `Union` رو به `Optional` ترجیح میدم چون کلمه "**اختیاری**" انگار暗示 میکنه که مقدار اختیاریه، در حالی که در واقع یعنی "میتونه `None` باشه"، حتی اگه اختیاری نباشه و هنوز لازم باشه.
-
-فکر میکنم `Union[SomeType, None]` واضحتر نشون میده چی معنی میده.
-
-فقط بحث کلمات و اسمهاست. ولی این کلمات میتونن رو طرز فکر تو و تیمت نسبت به کد تأثیر بذارن.
-
-بهعنوان مثال، این تابع رو ببین:
-
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
-
-پارامتر `name` بهعنوان `Optional[str]` تعریف شده، ولی **اختیاری نیست**، نمیتونی تابع رو بدون پارامتر صدا کنی:
-
-```Python
-say_hi() # اوه نه، این خطا میده! 😱
-```
-
-پارامتر `name` **هنوز لازمه** (نه *اختیاری*) چون مقدار پیشفرض نداره. با این حال، `name` مقدار `None` رو قبول میکنه:
-
-```Python
-say_hi(name=None) # این کار میکنه، None معتبره 🎉
-```
-
-خبر خوب اینه که وقتی رو پایتون 3.10 باشی، لازم نیست نگران این باشی، چون میتونی بهسادگی از `|` برای تعریف اتحادیه نوعها استفاده کنی:
-
-{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
-
-اون موقع دیگه لازم نیست نگران اسمهایی مثل `Optional` و `Union` باشی. 😎
-
-#### نوعهای عمومی
-
-این نوعهایی که پارامترهای نوع رو توی کروشهها میگیرن بهشون **نوعهای عمومی** یا **Generics** میگن، مثلاً:
-
-//// tab | Python 3.10+
-
-میتونی از همون نوعهای داخلی بهعنوان نوعهای عمومی استفاده کنی (با کروشهها و نوعها داخلشون):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-و همونطور که توی پایتون 3.8 بود، از ماژول `typing`:
-
-* `Union`
-* `Optional` (همونطور که توی پایتون 3.8 بود)
-* ...و بقیه.
-
-توی پایتون 3.10، بهعنوان جایگزین برای استفاده از نوعهای عمومی `Union` و `Optional`، میتونی از خط عمودی (`|`) برای تعریف اتحادیه نوعها استفاده کنی، که خیلی بهتر و سادهتره.
-
-////
-
-//// tab | Python 3.9+
-
-میتونی از همون نوعهای داخلی بهعنوان نوعهای عمومی استفاده کنی (با کروشهها و نوعها داخلشون):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-و همونطور که توی پایتون 3.8 بود، از ماژول `typing`:
-
-* `Union`
-* `Optional`
-* ...و بقیه.
-
-////
-
-//// tab | Python 3.8+
-
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...و بقیه.
-
-////
-
-### کلاسها بهعنوان نوع
-
-میتونی یه کلاس رو هم بهعنوان نوع یه متغیر تعریف کنی.
-
-فرض کن یه کلاس `Person` داری، با یه نام:
-
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
-
-بعد میتونی یه متغیر رو از نوع `Person` تعریف کنی:
-
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
-
-و بعد، دوباره، همه پشتیبانی ویرایشگر رو داری:
-
-
-
-توجه کن که این یعنی "`one_person` یه **نمونه** از کلاس `Person` هست".
-
-یعنی "`one_person` خود **کلاس** به اسم `Person` نیست".
-
-## مدلهای Pydantic
-
-Pydantic یه کتابخونه پایتونه برای اعتبارسنجی دادهها.
-
-"شکل" دادهها رو بهعنوان کلاسهایی با ویژگیها تعریف میکنی.
-
-و هر ویژگی یه نوع داره.
-
-بعد یه نمونه از اون کلاس رو با یه سری مقدار میسازی و اون مقدارها رو اعتبارسنجی میکنه، به نوع مناسب تبدیلشون میکنه (اگه لازم باشه) و یه شیء با همه دادهها بهت میده.
-
-و با اون شیء نهایی همه پشتیبانی ویرایشگر رو میگیری.
-
-یه مثال از مستندات رسمی Pydantic:
-
-//// 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
-
-برای اطلاعات بیشتر در مورد Pydantic، مستنداتش رو چک کن.
-
-///
-
-**FastAPI** کاملاً بر پایه Pydantic هست.
-
-توی [آموزش - راهنمای کاربر](tutorial/index.md){.internal-link target=_blank} خیلی بیشتر از اینا رو توی عمل میبینی.
-
-/// tip
-
-Pydantic یه رفتار خاص داره وقتی از `Optional` یا `Union[Something, None]` بدون مقدار پیشفرض استفاده میکنی، میتونی توی مستندات Pydantic در مورد فیلدهای اختیاری لازم بیشتر بخونی.
-
-///
-
-## نوعنماها با Annotationهای متادیتا
-
-پایتون یه قابلیت هم داره که بهت اجازه میده **متادیتا اضافی** رو توی این نوعنماها بذاری با استفاده از `Annotated`.
-
-//// tab | Python 3.9+
-
-توی پایتون 3.9، `Annotated` بخشی از کتابخونه استاندارده، پس میتونی از `typing` واردش کنی.
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-توی نسخههای زیر پایتون 3.9، `Annotated` رو از `typing_extensions` وارد میکنی.
-
-با **FastAPI** از قبل نصب شده.
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013.py!}
-```
-
-////
-
-خود پایتون با این `Annotated` کاری نمیکنه. و برای ویرایشگرها و ابزارهای دیگه، نوع هنوز `str` هست.
-
-ولی میتونی از این فضا توی `Annotated` استفاده کنی تا به **FastAPI** متادیتای اضافی در مورد اینکه چطور میخوای برنامهات رفتار کنه بدی.
-
-نکته مهم اینه که **اولین *پارامتر نوع*** که به `Annotated` میدی، **نوع واقعی** هست. بقیش فقط متادیتا برای ابزارهای دیگهست.
-
-الان فقط باید بدونی که `Annotated` وجود داره، و اینکه پایتون استاندارده. 😎
-
-بعداً میبینی که چقدر **قوی** میتونه باشه.
-
-/// tip
-
-اینکه این **پایتون استاندارده** یعنی هنوز **بهترین تجربه توسعهدهنده** رو توی ویرایشگرت، با ابزارهایی که برای تحلیل و بازسازی کدت استفاده میکنی و غیره میگیری. ✨
-
-و همینطور کدت با خیلی از ابزارها و کتابخونههای دیگه پایتون خیلی سازگار میمونه. 🚀
-
-///
-
-## نوعنماها توی **FastAPI**
-
-**FastAPI** از این نوعنماها استفاده میکنه تا چند تا کار بکنه.
-
-با **FastAPI** پارامترها رو با نوعنماها تعریف میکنی و اینا رو میگیری:
-
-* **پشتیبانی ویرایشگر**.
-* **چک نوعها**.
-
-...و **FastAPI** از همون تعریفها برای اینا استفاده میکنه:
-
-* **تعریف نیازها**: از پارامترهای مسیر درخواست، پارامترهای کوئری، هدرها، بدنهها، وابستگیها و غیره.
-* **تبدیل داده**: از درخواست به نوع مورد نیاز.
-* **اعتبارسنجی داده**: که از هر درخواست میاد:
- * تولید **خطاهای خودکار** که به کلاینت برمیگرده وقتی داده نامعتبره.
-* **مستندسازی** API با استفاده از OpenAPI:
- * که بعدش توسط رابطهای کاربری مستندات تعاملی خودکار استفاده میشه.
-
-اینا شاید همهش انتزاعی به نظر بیاد. نگران نباش. همه اینا رو توی عمل توی [آموزش - راهنمای کاربر](tutorial/index.md){.internal-link target=_blank} میبینی.
-
-نکته مهم اینه که با استفاده از نوعهای استاندارد پایتون، توی یه جا (به جای اضافه کردن کلاسهای بیشتر، دکوراتورها و غیره)، **FastAPI** کلی از کار رو برات انجام میده.
-
-/// info
-
-اگه همه آموزش رو گذروندی و برگشتی که بیشتر در مورد نوعها ببینی، یه منبع خوب "تقلبنامه" از `mypy` هست.
-
-///
diff --git a/docs/fa/docs/tutorial/middleware.md b/docs/fa/docs/tutorial/middleware.md
deleted file mode 100644
index 75b1c4c5c..000000000
--- a/docs/fa/docs/tutorial/middleware.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# میانافزار - middleware
-
-شما میتوانید میانافزارها را در **FastAPI** اضافه کنید.
-
-"میانافزار" یک تابع است که با هر درخواست(request) قبل از پردازش توسط هر path operation (عملیات مسیر) خاص کار میکند. همچنین با هر پاسخ(response) قبل از بازگشت آن نیز کار میکند.
-
-* هر **درخواستی (request)** که به برنامه شما می آید را می گیرد.
-* سپس می تواند کاری برای آن **درخواست** انجام دهید یا هر کد مورد نیازتان را اجرا کنید.
-* سپس **درخواست** را به بخش دیگری از برنامه (توسط یک path operation مشخص) برای پردازش ارسال می کند.
-* سپس **پاسخ** تولید شده توسط برنامه را (توسط یک path operation مشخص) دریافت میکند.
-* می تواند کاری با **پاسخ** انجام دهید یا هر کد مورد نیازتان را اجرا کند.
-* سپس **پاسخ** را برمی گرداند.
-
-/// توجه | جزئیات فنی
-
-در صورت وجود وابستگی هایی با `yield`، کد خروجی **پس از** اجرای میانافزار اجرا خواهد شد.
-
-در صورت وجود هر گونه وظایف پس زمینه (که در ادامه توضیح داده میشوند)، تمام میانافزارها *پس از آن* اجرا خواهند شد.
-
-///
-
-## ساخت یک میان افزار
-
-برای ایجاد یک میانافزار، از دکوریتور `@app.middleware("http")` در بالای یک تابع استفاده میشود.
-
-تابع میان افزار دریافت می کند:
-* `درخواست`
-* تابع `call_next` که `درخواست` را به عنوان پارامتر دریافت می کند
- * این تابع `درخواست` را به *path operation* مربوطه ارسال می کند.
- * سپس `پاسخ` تولید شده توسط *path operation* مربوطه را برمیگرداند.
-* شما میتوانید سپس `پاسخ` را تغییر داده و پس از آن را برگردانید.
-
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
-
-/// نکته | به خاطر داشته باشید که هدرهای اختصاصی سفارشی را می توان با استفاده از پیشوند "X-" اضافه کرد.
-
-اما اگر هدرهای سفارشی دارید که میخواهید مرورگر کاربر بتواند آنها را ببیند، باید آنها را با استفاده از پارامتر `expose_headers` که در مستندات CORS از Starlette توضیح داده شده است، به پیکربندی CORS خود اضافه کنید.
-
-///
-
-/// توجه | جزئیات فنی
-
-شما همچنین میتوانید از `from starlette.requests import Request` استفاده کنید.
-
-**FastAPI** این را به عنوان یک سهولت برای شما به عنوان برنامهنویس فراهم میکند. اما این مستقیما از Starlette به دست میآید.
-
-///
-
-### قبل و بعد از `پاسخ`
-
-شما میتوانید کدی را برای اجرا با `درخواست`، قبل از اینکه هر *path operation* آن را دریافت کند، اضافه کنید.
-
-همچنین پس از تولید `پاسخ`، قبل از بازگشت آن، میتوانید کدی را اضافه کنید.
-
-به عنوان مثال، میتوانید یک هدر سفارشی به نام `X-Process-Time` که شامل زمان پردازش درخواست و تولید پاسخ به صورت ثانیه است، اضافه کنید.
-
-{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
-
- ## سایر میان افزار
-
-شما میتوانید بعداً در مورد میانافزارهای دیگر در [راهنمای کاربر پیشرفته: میانافزار پیشرفته](../advanced/middleware.md){.internal-link target=_blank} بیشتر بخوانید.
-
-شما در بخش بعدی در مورد این که چگونه با استفاده از یک میانافزار، CORS را مدیریت کنید، خواهید خواند.
diff --git a/docs/fa/docs/tutorial/security/index.md b/docs/fa/docs/tutorial/security/index.md
deleted file mode 100644
index c0827a8b3..000000000
--- a/docs/fa/docs/tutorial/security/index.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# امنیت
-
-روشهای مختلفی برای مدیریت امنیت، تأیید هویت و اعتبارسنجی وجود دارد.
-
-عموماً این یک موضوع پیچیده و "سخت" است.
-
-در بسیاری از فریم ورک ها و سیستمها، فقط مدیریت امنیت و تأیید هویت نیاز به تلاش و کد نویسی زیادی دارد (در بسیاری از موارد میتواند 50% یا بیشتر کل کد نوشته شده باشد).
-
-
-فریم ورک **FastAPI** ابزارهای متعددی را در اختیار شما قرار می دهد تا به راحتی، با سرعت، به صورت استاندارد و بدون نیاز به مطالعه و یادگیری همه جزئیات امنیت، در مدیریت **امنیت** به شما کمک کند.
-
-اما قبل از آن، بیایید برخی از مفاهیم کوچک را بررسی کنیم.
-
-## عجله دارید؟
-
-اگر به هیچ یک از این اصطلاحات اهمیت نمی دهید و فقط نیاز به افزودن امنیت با تأیید هویت بر اساس نام کاربری و رمز عبور دارید، *همین الان* به فصل های بعدی بروید.
-
-## پروتکل استاندارد OAuth2
-
-پروتکل استاندارد OAuth2 یک مشخصه است که چندین روش برای مدیریت تأیید هویت و اعتبار سنجی تعریف می کند.
-
-این مشخصه بسیار گسترده است و چندین حالت استفاده پیچیده را پوشش می دهد.
-
-در آن روش هایی برای تأیید هویت با استفاده از "برنامه های شخص ثالث" وجود دارد.
-
-این همان چیزی است که تمامی سیستم های با "ورود با فیسبوک، گوگل، توییتر، گیت هاب" در پایین آن را استفاده می کنند.
-
-### پروتکل استاندارد OAuth 1
-
-پروتکل استاندارد OAuth1 نیز وجود داشت که با OAuth2 خیلی متفاوت است و پیچیدگی بیشتری داشت، زیرا شامل مشخصات مستقیم در مورد رمزگذاری ارتباط بود.
-
-در حال حاضر OAuth1 بسیار محبوب یا استفاده شده نیست.
-
-پروتکل استاندارد OAuth2 روش رمزگذاری ارتباط را مشخص نمی کند، بلکه انتظار دارد که برنامه شما با HTTPS سرویس دهی شود.
-
-/// نکته
-
-در بخش در مورد **استقرار** ، شما یاد خواهید گرفت که چگونه با استفاده از Traefik و Let's Encrypt رایگان HTTPS را راه اندازی کنید.
-
-///
-
-## استاندارد OpenID Connect
-
-استاندارد OpenID Connect، مشخصهای دیگر است که بر پایه **OAuth2** ساخته شده است.
-
-این مشخصه، به گسترش OAuth2 میپردازد و برخی مواردی که در OAuth2 نسبتاً تردید برانگیز هستند را مشخص میکند تا سعی شود آن را با سایر سیستمها قابل ارتباط کند.
-
-به عنوان مثال، ورود به سیستم گوگل از OpenID Connect استفاده میکند (که در زیر از OAuth2 استفاده میکند).
-
-اما ورود به سیستم فیسبوک، از OpenID Connect پشتیبانی نمیکند. به جای آن، نسخه خودش از OAuth2 را دارد.
-
-### استاندارد OpenID (نه "OpenID Connect" )
-
-همچنین مشخصه "OpenID" نیز وجود داشت که سعی در حل مسائل مشابه OpenID Connect داشت، اما بر پایه OAuth2 ساخته نشده بود.
-
-بنابراین، یک سیستم جداگانه بود.
-
-اکنون این مشخصه کمتر استفاده میشود و محبوبیت زیادی ندارد.
-
-## استاندارد OpenAPI
-
-استاندارد OpenAPI (قبلاً با نام Swagger شناخته میشد) یک open specification برای ساخت APIs (که در حال حاضر جزئی از بنیاد لینوکس میباشد) است.
-
-فریم ورک **FastAPI** بر اساس **OpenAPI** است.
-
-این خاصیت، امکان دارد تا چندین رابط مستندات تعاملی خودکار(automatic interactive documentation interfaces)، تولید کد و غیره وجود داشته باشد.
-
-مشخصه OpenAPI روشی برای تعریف چندین "schemes" دارد.
-
-با استفاده از آنها، شما میتوانید از همه این ابزارهای مبتنی بر استاندارد استفاده کنید، از جمله این سیستمهای مستندات تعاملی(interactive documentation systems).
-
-استاندارد OpenAPI شیوههای امنیتی زیر را تعریف میکند:
-
-* شیوه `apiKey`: یک کلید اختصاصی برای برنامه که میتواند از موارد زیر استفاده شود:
- * پارامتر جستجو.
- * هدر.
- * کوکی.
-* شیوه `http`: سیستمهای استاندارد احراز هویت HTTP، از جمله:
- * مقدار `bearer`: یک هدر `Authorization` با مقدار `Bearer` به همراه یک توکن. این از OAuth2 به ارث برده شده است.
- * احراز هویت پایه HTTP.
- * ویژگی HTTP Digest و غیره.
-* شیوه `oauth2`: تمام روشهای OAuth2 برای مدیریت امنیت (به نام "flows").
- * چندین از این flows برای ساخت یک ارائهدهنده احراز هویت OAuth 2.0 مناسب هستند (مانند گوگل، فیسبوک، توییتر، گیتهاب و غیره):
- * ویژگی `implicit`
- * ویژگی `clientCredentials`
- * ویژگی `authorizationCode`
- * اما یک "flow" خاص وجود دارد که میتواند به طور کامل برای مدیریت احراز هویت در همان برنامه به کار رود:
- * بررسی `password`: چند فصل بعدی به مثالهای این مورد خواهیم پرداخت.
-* شیوه `openIdConnect`: یک روش برای تعریف نحوه کشف دادههای احراز هویت OAuth2 به صورت خودکار.
- * کشف خودکار این موضوع را که در مشخصه OpenID Connect تعریف شده است، مشخص میکند.
-
-/// نکته
-
-ادغام سایر ارائهدهندگان احراز هویت/اجازهدهی مانند گوگل، فیسبوک، توییتر، گیتهاب و غیره نیز امکانپذیر و نسبتاً آسان است.
-
-مشکل پیچیدهترین مسئله، ساخت یک ارائهدهنده احراز هویت/اجازهدهی مانند آنها است، اما **FastAPI** ابزارهای لازم برای انجام این کار را با سهولت به شما میدهد و همه کارهای سنگین را برای شما انجام میدهد.
-
-///
-
-## ابزارهای **FastAPI**
-
-فریم ورک FastAPI ابزارهایی برای هر یک از این شیوههای امنیتی در ماژول`fastapi.security` فراهم میکند که استفاده از این مکانیزمهای امنیتی را سادهتر میکند.
-
-در فصلهای بعدی، شما یاد خواهید گرفت که چگونه با استفاده از این ابزارهای ارائه شده توسط **FastAPI**، امنیت را به API خود اضافه کنید.
-
-همچنین، خواهید دید که چگونه به صورت خودکار در سیستم مستندات تعاملی ادغام میشود.
diff --git a/docs/fa/mkdocs.yml b/docs/fa/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/fa/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/fr/docs/alternatives.md b/docs/fr/docs/alternatives.md
index 4d6037910..9d8d85705 100644
--- a/docs/fr/docs/alternatives.md
+++ b/docs/fr/docs/alternatives.md
@@ -452,7 +452,7 @@ Gérer toute la validation des données, leur sérialisation et la documentation
///
-### Starlette
+### Starlette
Starlette est un framework/toolkit léger ASGI, qui est idéal pour construire des services asyncio performants.
@@ -498,7 +498,7 @@ Ainsi, tout ce que vous pouvez faire avec Starlette, vous pouvez le faire direct
///
-### Uvicorn
+### Uvicorn
Uvicorn est un serveur ASGI rapide comme l'éclair, basé sur uvloop et httptools.
diff --git a/docs/fr/docs/deployment/manually.md b/docs/fr/docs/deployment/manually.md
index 7c29242a9..3f99ccd9f 100644
--- a/docs/fr/docs/deployment/manually.md
+++ b/docs/fr/docs/deployment/manually.md
@@ -4,7 +4,7 @@ La principale chose dont vous avez besoin pour exécuter une application **FastA
Il existe 3 principales alternatives :
-* Uvicorn : un serveur ASGI haute performance.
+* Uvicorn : un serveur ASGI haute performance.
* Hypercorn : un serveur
ASGI compatible avec HTTP/2 et Trio entre autres fonctionnalités.
* Daphne : le serveur ASGI
@@ -27,7 +27,7 @@ Vous pouvez installer un serveur compatible ASGI avec :
//// tab | Uvicorn
-* Uvicorn, un serveur ASGI rapide comme l'éclair, basé sur uvloop et httptools.
+* Uvicorn, un serveur ASGI rapide comme l'éclair, basé sur uvloop et httptools.
uvicorn - Pour le serveur qui charge et sert votre application.
+* uvicorn - Pour le serveur qui charge et sert votre application.
* orjson - Obligatoire si vous voulez utiliser `ORJSONResponse`.
* ujson - Obligatoire si vous souhaitez utiliser `UJSONResponse`.
diff --git a/docs/fr/docs/tutorial/background-tasks.md b/docs/fr/docs/tutorial/background-tasks.md
index 2065ca58e..6efd16e07 100644
--- a/docs/fr/docs/tutorial/background-tasks.md
+++ b/docs/fr/docs/tutorial/background-tasks.md
@@ -61,7 +61,7 @@ Et ensuite une autre tâche d'arrière-plan (générée dans les paramètres de
## Détails techniques
-La classe `BackgroundTasks` provient directement de `starlette.background`.
+La classe `BackgroundTasks` provient directement de `starlette.background`.
Elle est importée/incluse directement dans **FastAPI** pour que vous puissiez l'importer depuis `fastapi` et éviter d'importer accidentellement `BackgroundTask` (sans `s` à la fin) depuis `starlette.background`.
@@ -69,7 +69,7 @@ En utilisant seulement `BackgroundTasks` (et non `BackgroundTask`), il est possi
Il est tout de même possible d'utiliser `BackgroundTask` seul dans **FastAPI**, mais dans ce cas il faut créer l'objet dans le code et renvoyer une `Response` Starlette l'incluant.
-Plus de détails sont disponibles dans la documentation officielle de Starlette sur les tâches d'arrière-plan (via leurs classes `BackgroundTasks`et `BackgroundTask`).
+Plus de détails sont disponibles dans la documentation officielle de Starlette sur les tâches d'arrière-plan (via leurs classes `BackgroundTasks`et `BackgroundTask`).
## Avertissement
diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md
index 758145362..96ea56e62 100644
--- a/docs/fr/docs/tutorial/first-steps.md
+++ b/docs/fr/docs/tutorial/first-steps.md
@@ -140,7 +140,7 @@ Vous pourriez aussi l'utiliser pour générer du code automatiquement, pour les
`FastAPI` est une classe héritant directement de `Starlette`.
-Vous pouvez donc aussi utiliser toutes les fonctionnalités de Starlette depuis `FastAPI`.
+Vous pouvez donc aussi utiliser toutes les fonctionnalités de Starlette depuis `FastAPI`.
///
diff --git a/docs/fr/llm-prompt.md b/docs/fr/llm-prompt.md
new file mode 100644
index 000000000..228500fe2
--- /dev/null
+++ b/docs/fr/llm-prompt.md
@@ -0,0 +1,132 @@
+### Target language
+
+Translate to French (français).
+
+Language code: fr.
+
+### Grammar to use when talking to the reader
+
+Use the formal grammar (use `vous` instead of `tu`).
+
+Additionally, in instructional sentences, prefer the present tense for obligations:
+
+- Prefer `vous devez …` over `vous devrez …`, unless the English source explicitly refers to a future requirement.
+
+- When translating “make sure (that) … is …”, prefer the indicative after `vous assurer que` (e.g. `Vous devez vous assurer qu'il est …`) instead of the subjunctive (e.g. `qu'il soit …`).
+
+### Quotes
+
+- Convert neutral double quotes (`"`) to French guillemets (`«` and `»`).
+
+- Do not convert quotes inside code blocks, inline code, paths, URLs, or anything wrapped in backticks.
+
+Examples:
+
+Source (English):
+
+```
+"Hello world"
+“Hello Universe”
+"He said: 'Hello'"
+"The module is `__main__`"
+```
+
+Result (French):
+
+```
+"Hello world"
+“Hello Universe”
+"He said: 'Hello'"
+"The module is `__main__`"
+```
+
+### Ellipsis
+
+- Make sure there is a space between an ellipsis and a word following or preceding the ellipsis.
+
+Examples:
+
+Source (English):
+
+```
+...as we intended.
+...this would work:
+...etc.
+others...
+More to come...
+```
+
+Result (French):
+
+```
+... comme prévu.
+... cela fonctionnerait :
+... etc.
+D'autres ...
+La suite ...
+```
+
+- This does not apply in URLs, code blocks, and code snippets. Do not remove or add spaces there.
+
+### Headings
+
+- Prefer translating headings using the infinitive form (as is common in the existing French docs): `Créer…`, `Utiliser…`, `Ajouter…`.
+
+- For headings that are instructions written in imperative in English (e.g. `Go check …`), keep them in imperative in French, using the formal grammar (e.g. `Allez voir …`).
+
+### French instructions about technical terms
+
+Do not try to translate everything. In particular, keep common programming terms (e.g. `framework`, `endpoint`, `plug-in`, `payload`).
+
+Keep class names, function names, modules, file names, and CLI commands unchanged.
+
+### List of English terms and their preferred French translations
+
+Below is a list of English terms and their preferred French translations, separated by a colon (:). Use these translations, do not use your own. If an existing translation does not use these terms, update it to use them.
+
+- /// note | Technical Details»: /// note | Détails techniques
+- /// note: /// note | Remarque
+- /// tip: /// tip | Astuce
+- /// warning: /// warning | Alertes
+- /// check: /// check | Vérifications
+- /// info: /// info
+
+- the docs: les documents
+- the documentation: la documentation
+
+- Exclude from OpenAPI: Exclusion d'OpenAPI
+
+- framework: framework (do not translate to cadre)
+- performance: performance
+
+- type hints: annotations de type
+- type annotations: annotations de type
+
+- autocomplete: autocomplétion
+- autocompletion: autocomplétion
+
+- the request (what the client sends to the server): la requête
+- the response (what the server sends back to the client): la réponse
+
+- the request body: le corps de la requête
+- the response body: le corps de la réponse
+
+- path operation: chemin d'accès
+- path operations (plural): chemins d'accès
+- path operation function: fonction de chemin d'accès
+- path operation decorator: décorateur de chemin d'accès
+
+- path parameter: paramètre de chemin
+- query parameter: paramètre de requête
+
+- the `Request`: `Request` (keep as code identifier)
+- the `Response`: `Response` (keep as code identifier)
+
+- deployment: déploiement
+- to upgrade: mettre à niveau
+
+- deprecated: déprécié
+- to deprecate: déprécier
+
+- cheat sheet: aide-mémoire
+- plug-in: plug-in
diff --git a/docs/he/docs/index.md b/docs/he/docs/index.md
deleted file mode 100644
index 14ea82f5e..000000000
--- a/docs/he/docs/index.md
+++ /dev/null
@@ -1,469 +0,0 @@
-# FastAPI
-
-
-
-
-
-
- תשתית FastAPI, ביצועים גבוהים, קלה ללמידה, מהירה לתכנות, מוכנה לסביבת ייצור -
- - ---- - -**תיעוד**: https://fastapi.tiangolo.com - -**קוד**: https://github.com/fastapi/fastapi - ---- - -FastAPI היא תשתית רשת מודרנית ומהירה (ביצועים גבוהים) לבניית ממשקי תכנות יישומים (API) עם פייתון 3.6+ בהתבסס על רמזי טיפוסים סטנדרטיים. - -תכונות המפתח הן: - -- **מהירה**: ביצועים גבוהים מאוד, בקנה אחד עם NodeJS ו - Go (תודות ל - Starlette ו - Pydantic). [אחת מתשתיות הפייתון המהירות ביותר](#_14). - -- **מהירה לתכנות**: הגבירו את מהירות פיתוח התכונות החדשות בכ - %200 עד %300. \* -- **פחות שגיאות**: מנעו כ - %40 משגיאות אנוש (מפתחים). \* -- **אינטואיטיבית**: תמיכת עורך מעולה. השלמה בכל מקום. פחות זמן ניפוי שגיאות. -- **קלה**: מתוכננת להיות קלה לשימוש וללמידה. פחות זמן קריאת תיעוד. -- **קצרה**: מזערו שכפול קוד. מספר תכונות מכל הכרזת פרמטר. פחות שגיאות. -- **חסונה**: קבלו קוד מוכן לסביבת ייצור. עם תיעוד אינטרקטיבי אוטומטי. -- **מבוססת סטנדרטים**: מבוססת על (ותואמת לחלוטין ל -) הסטדנרטים הפתוחים לממשקי תכנות יישומים: OpenAPI (ידועים לשעבר כ - Swagger) ו - JSON Schema. - -\* הערכה מבוססת על בדיקות של צוות פיתוח פנימי שבונה אפליקציות בסביבת ייצור. - -## נותני חסות - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-אם אתם בונים אפליקציית CLI לשימוש במסוף במקום ממשק רשת, העיפו מבט על **Typer**.
-
-**Typer** היא אחותה הקטנה של FastAPI. ומטרתה היא להיות ה - **FastAPI של ממשקי שורת פקודה**. ⌨️ 🚀
-
-## תלויות
-
-פייתון 3.6+
-
-FastAPI עומדת על כתפי ענקיות:
-
-- Starlette לחלקי הרשת.
-- Pydantic לחלקי המידע.
-
-## התקנה
-
-async def...uvicorn main:app --reload...app = FastAPI().
-- --reload: גרמו לשרת להתאתחל לאחר שינויים בקוד. עשו זאת רק בסביבת פיתוח.
-
-/items/{item_id}.
-- שני ה _נתיבים_ מקבלים _בקשות_ `GET` (ידועות גם כ*מתודות* HTTP).
-- ה _נתיב_ /items/{item_id} כולל \*פרמטר נתיב\_ `item_id` שאמור להיות `int`.
-- ה _נתיב_ /items/{item_id} \*פרמטר שאילתא\_ אופציונלי `q`.
-
-### תיעוד API אינטרקטיבי
-
-כעת פנו לכתובת http://127.0.0.1:8000/docs.
-
-אתם תראו את התיעוד האוטומטי (מסופק על ידי Swagger UI):
-
-
-
-### תיעוד אלטרנטיבי
-
-כעת פנו לכתובת http://127.0.0.1:8000/redoc.
-
-אתם תראו תיעוד אלטרנטיבי (מסופק על ידי ReDoc):
-
-
-
-## שדרוג לדוגמא
-
-כעת ערכו את הקובץ `main.py` כך שיוכל לקבל גוף מבקשת `PUT`.
-
-הגדירו את הגוף בעזרת רמזי טיפוסים סטנדרטיים, הודות ל - `Pydantic`.
-
-```Python hl_lines="4 9-12 25-27"
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- price: float
- is_offer: Union[bool, None] = None
-
-
-@app.get("/")
-def read_root():
- return {"Hello": "World"}
-
-
-@app.get("/items/{item_id}")
-def read_item(item_id: int, q: Union[str, None] = None):
- return {"item_id": item_id, "q": q}
-
-
-@app.put("/items/{item_id}")
-def update_item(item_id: int, item: Item):
- return {"item_name": item.name, "item_id": item_id}
-```
-
-השרת אמול להתאתחל אוטומטית (מאחר והוספתם --reload לפקודת `uvicorn` שלמעלה).
-
-### שדרוג התיעוד האינטרקטיבי
-
-כעת פנו לכתובת http://127.0.0.1:8000/docs.
-
-- התיעוד האוטומטי יתעדכן, כולל הגוף החדש:
-
-
-
-- לחצו על הכפתור "Try it out", הוא יאפשר לכם למלא את הפרמטרים ולעבוד ישירות מול ה - API.
-
-
-
-- אחר כך לחצו על הכפתור "Execute", האתר יתקשר עם ה - API שלכם, ישלח את הפרמטרים, ישיג את התוצאות ואז יראה אותן על המסך:
-
-
-
-### שדרוג התיעוד האלטרנטיבי
-
-כעת פנו לכתובת http://127.0.0.1:8000/redoc.
-
-- התיעוד האלטרנטיבי גם יראה את פרמטר השאילתא והגוף החדשים.
-
-
-
-### סיכום
-
-לסיכום, אתם מכריזים ** פעם אחת** על טיפוסי הפרמטרים, גוף וכו' כפרמטרים לפונקציה.
-
-אתם עושים את זה עם טיפוסי פייתון מודרניים.
-
-אתם לא צריכים ללמוד תחביר חדש, מתודות או מחלקות של ספרייה ספיציפית, וכו'
-
-רק **פייתון 3.6+** סטנדרטי.
-
-לדוגמא, ל - `int`:
-
-```Python
-item_id: int
-```
-
-או למודל `Item` מורכב יותר:
-
-```Python
-item: Item
-```
-
-...ועם הכרזת הטיפוס האחת הזו אתם מקבלים:
-
-- תמיכת עורך, כולל:
- - השלמות.
- - בדיקת טיפוסים.
-- אימות מידע:
- - שגיאות ברורות ואטומטיות כאשר מוכנס מידע לא חוקי .
- - אימות אפילו לאובייקטי JSON מקוננים.
-- המרה של מידע קלט: המרה של מידע שמגיע מהרשת למידע וטיפוסים של פייתון. קורא מ:
- - JSON.
- - פרמטרי נתיב.
- - פרמטרי שאילתא.
- - עוגיות.
- - כותרות.
- - טפסים.
- - קבצים.
-- המרה של מידע פלט: המרה של מידע וטיפוסים מפייתון למידע רשת (כ - JSON):
- - המירו טיפוסי פייתון (`str`, `int`, `float`, `bool`, `list`, etc).
- - עצמי `datetime`.
- - עצמי `UUID`.
- - מודלי בסיסי נתונים.
- - ...ורבים אחרים.
-- תיעוד API אוטומטי ואינטרקטיבית כולל שתי אלטרנטיבות לממשק המשתמש:
- - Swagger UI.
- - ReDoc.
-
----
-
-בחזרה לדוגמאת הקוד הקודמת, **FastAPI** ידאג:
-
-- לאמת שיש `item_id` בנתיב בבקשות `GET` ו - `PUT`.
-- לאמת שה - `item_id` הוא מטיפוס `int` בבקשות `GET` ו - `PUT`.
- - אם הוא לא, הלקוח יראה שגיאה ברורה ושימושית.
-- לבדוק האם קיים פרמטר שאילתא בשם `q` (קרי `http://127.0.0.1:8000/items/foo?q=somequery`) לבקשות `GET`.
- - מאחר והפרמטר `q` מוגדר עם = None, הוא אופציונלי.
- - לולא ה - `None` הוא היה חובה (כמו הגוף במקרה של `PUT`).
-- לבקשות `PUT` לנתיב /items/{item_id}, לקרוא את גוף הבקשה כ - JSON:
- - לאמת שהוא כולל את מאפיין החובה `name` שאמור להיות מטיפוס `str`.
- - לאמת שהוא כולל את מאפיין החובה `price` שחייב להיות מטיפוס `float`.
- - לבדוק האם הוא כולל את מאפיין הרשות `is_offer` שאמור להיות מטיפוס `bool`, אם הוא נמצא.
- - כל זה יעבוד גם לאובייקט JSON מקונן.
-- להמיר מ - JSON ול- JSON אוטומטית.
-- לתעד הכל באמצעות OpenAPI, תיעוד שבו יוכלו להשתמש:
- - מערכות תיעוד אינטרקטיביות.
- - מערכות ייצור קוד אוטומטיות, להרבה שפות.
-- לספק ישירות שתי מערכות תיעוד רשתיות.
-
----
-
-רק גרדנו את קצה הקרחון, אבל כבר יש לכם רעיון של איך הכל עובד.
-
-נסו לשנות את השורה:
-
-```Python
- return {"item_name": item.name, "item_id": item_id}
-```
-
-...מ:
-
-```Python
- ... "item_name": item.name ...
-```
-
-...ל:
-
-```Python
- ... "item_price": item.price ...
-```
-
-...וראו איך העורך שלכם משלים את המאפיינים ויודע את הטיפוסים שלהם:
-
-
-
-לדוגמא יותר שלמה שכוללת עוד תכונות, ראו את המדריך - למשתמש.
-
-**התראת ספוילרים**: המדריך - למשתמש כולל:
-
-- הכרזה על **פרמטרים** ממקורות אחרים ושונים כגון: **כותרות**, **עוגיות**, **טפסים** ו - **קבצים**.
-- איך לקבוע **מגבלות אימות** בעזרת `maximum_length` או `regex`.
-- דרך חזקה וקלה להשתמש ב**הזרקת תלויות**.
-- אבטחה והתאמתות, כולל תמיכה ב - **OAuth2** עם **JWT** והתאמתות **HTTP Basic**.
-- טכניקות מתקדמות (אבל קלות באותה מידה) להכרזת אובייקטי JSON מקוננים (תודות ל - Pydantic).
-- אינטרקציה עם **GraphQL** דרך Strawberry וספריות אחרות.
-- תכונות נוספות רבות (תודות ל - Starlette) כגון:
- - **WebSockets**
- - בדיקות קלות במיוחד מבוססות על `requests` ו - `pytest`
- - **CORS**
- - **Cookie Sessions**
- - ...ועוד.
-
-## ביצועים
-
-בדיקות עצמאיות של TechEmpower הראו שאפליקציות **FastAPI** שרצות תחת Uvicorn הן מתשתיות הפייתון המהירות ביותר, רק מתחת ל - Starlette ו - Uvicorn עצמן (ש - FastAPI מבוססת עליהן). (\*)
-
-כדי להבין עוד על הנושא, ראו את הפרק Benchmarks.
-
-## תלויות אופציונליות
-
-בשימוש Pydantic:
-
-- email-validator - לאימות כתובות אימייל.
-
-בשימוש Starlette:
-
-- httpx - דרוש אם ברצונכם להשתמש ב - `TestClient`.
-- jinja2 - דרוש אם ברצונכם להשתמש בברירת המחדל של תצורת הטמפלייטים.
-- python-multipart - דרוש אם ברצונכם לתמוך ב "פרסור" טפסים, באצמעות request.form().
-- itsdangerous - דרוש אם ברצונכם להשתמש ב - `SessionMiddleware`.
-- pyyaml - דרוש אם ברצונכם להשתמש ב - `SchemaGenerator` של Starlette (כנראה שאתם לא צריכים את זה עם FastAPI).
-
-בשימוש FastAPI / Starlette:
-
-- uvicorn - לשרת שטוען ומגיש את האפליקציה שלכם.
-- orjson - דרוש אם ברצונכם להשתמש ב - `ORJSONResponse`.
-- ujson - דרוש אם ברצונכם להשתמש ב - `UJSONResponse`.
-
-תוכלו להתקין את כל אלו באמצעות pip install "fastapi[all]".
-
-## רשיון
-
-הפרויקט הזה הוא תחת התנאים של רשיון MIT.
diff --git a/docs/he/mkdocs.yml b/docs/he/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/he/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/hu/docs/index.md b/docs/hu/docs/index.md
deleted file mode 100644
index f60b6b349..000000000
--- a/docs/hu/docs/index.md
+++ /dev/null
@@ -1,467 +0,0 @@
-
-
-
- FastAPI keretrendszer, nagy teljesítmény, könnyen tanulható, gyorsan kódolható, productionre kész -
- - ---- - -**Dokumentáció**: https://fastapi.tiangolo.com - -**Forrás kód**: https://github.com/fastapi/fastapi - ---- -A FastAPI egy modern, gyors (nagy teljesítményű), webes keretrendszer API-ok építéséhez Python -al, a Python szabványos típusjelöléseire építve. - - -Kulcs funkciók: - -* **Gyors**: Nagyon nagy teljesítmény, a **NodeJS**-el és a **Go**-val egyenrangú (a Starlettenek és a Pydantic-nek köszönhetően). [Az egyik leggyorsabb Python keretrendszer](#performance). -* **Gyorsan kódolható**: A funkciók fejlesztési sebességét 200-300 százalékkal megnöveli. * -* **Kevesebb hiba**: Körülbelül 40%-al csökkenti az emberi (fejlesztői) hibák számát. * -* **Intuitív**: Kiváló szerkesztő támogatás. Kiegészítés mindenhol. Kevesebb hibakereséssel töltött idő. -* **Egyszerű**: Egyszerű tanulásra és használatra tervezve. Kevesebb dokumentáció olvasással töltött idő. -* **Rövid**: Kód duplikáció minimalizálása. Több funkció minden paraméter deklarálásával. Kevesebb hiba. -* **Robosztus**: Production ready kód. Automatikus interaktív dokumentáció val. -* **Szabvány alapú**: Az API-ok nyílt szabványaira alapuló (és azokkal teljesen kompatibilis): OpenAPI (korábban Swagger néven ismert) és a JSON Schema. - -* Egy production alkalmazásokat építő belső fejlesztői csapat tesztjein alapuló becslés. - -## Szponzorok - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Ha egy olyan CLI alkalmazást fejlesztesz amit a parancssorban kell használni webes API helyett, tekintsd meg: **Typer**.
-
-**Typer** a FastAPI kistestvére. A **CLI-k FastAPI-ja**. ⌨️ 🚀
-
-## Követelmények
-
-A FastAPI óriások vállán áll:
-
-* Starlette a webes részekhez.
-* Pydantic az adat részekhez.
-
-## Telepítés
-
-async def-et...uvicorn main:app --reload...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.
-
-Starlette által használt:
-
-* httpx - Követelmény ha a `TestClient`-et akarod használni.
-* jinja2 - Követelmény ha az alap template konfigurációt akarod használni.
-* python-multipart - Követelmény ha "parsing"-ot akarsz támogatni, `request.form()`-al.
-* itsdangerous - Követelmény `SessionMiddleware` támogatáshoz.
-* pyyaml - Követelmény a Starlette `SchemaGenerator`-ának támogatásához (valószínűleg erre nincs szükség FastAPI használása esetén).
-
-FastAPI / Starlette által használt
-
-* uvicorn - Szerverekhez amíg betöltik és szolgáltatják az applikációdat.
-* orjson - Követelmény ha `ORJSONResponse`-t akarsz használni.
-* ujson - Követelmény ha `UJSONResponse`-t akarsz használni.
-
-Ezeket mind telepítheted a `pip install "fastapi[all]"` paranccsal.
-
-## Licensz
-Ez a projekt az MIT license, licensz alatt fut
diff --git a/docs/hu/mkdocs.yml b/docs/hu/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/hu/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/id/docs/index.md b/docs/id/docs/index.md
deleted file mode 100644
index b29d42dfd..000000000
--- a/docs/id/docs/index.md
+++ /dev/null
@@ -1,495 +0,0 @@
-# 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 -%} -
-
-Jika anda mengembangkan app CLI yang digunakan di terminal bukan sebagai API web, kunjungi **Typer**.
-
-**Typer** adalah saudara kecil FastAPI. Dan ditujukan sebagai **CLI FastAPI**. ⌨️ 🚀
-
-## Prayarat
-
-FastAPI berdiri di pundak raksasa:
-
-* Starlette untuk bagian web.
-* Pydantic untuk bagian data.
-
-## Instalasi
-
-Buat dan aktifkan virtual environment kemudian *install* FastAPI:
-
-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
deleted file mode 100644
index 9b461507d..000000000
--- a/docs/id/docs/tutorial/first-steps.md
+++ /dev/null
@@ -1,332 +0,0 @@
-# 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
deleted file mode 100644
index c01ec9a89..000000000
--- a/docs/id/docs/tutorial/index.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Tutorial - Pedoman Pengguna - Pengenalan
-
-Tutorial ini menunjukan cara menggunakan ***FastAPI*** dengan semua fitur-fiturnya, tahap demi tahap.
-
-Setiap bagian dibangun secara bertahap dari bagian sebelumnya, tetapi terstruktur untuk memisahkan banyak topik, sehingga kamu bisa secara langsung menuju ke topik spesifik untuk menyelesaikan kebutuhan API tertentu.
-
-Ini juga dibangun untuk digunakan sebagai referensi yang akan datang.
-
-Sehingga kamu dapat kembali lagi dan mencari apa yang kamu butuhkan dengan tepat.
-
-## Jalankan kode
-
-Semua blok-blok kode dapat disalin dan digunakan langsung (Mereka semua sebenarnya adalah file python yang sudah teruji).
-
-Untuk menjalankan setiap contoh, salin kode ke file `main.py`, dan jalankan `uvicorn` dengan:
-
-
-
-/// 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
deleted file mode 100644
index b55f31394..000000000
--- a/docs/id/docs/tutorial/static-files.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# 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/id/mkdocs.yml b/docs/id/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/id/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/it/docs/index.md b/docs/it/docs/index.md
deleted file mode 100644
index 7214df8a8..000000000
--- a/docs/it/docs/index.md
+++ /dev/null
@@ -1,463 +0,0 @@
-
-
-
- FastAPI framework, alte prestazioni, facile da imparare, rapido da implementare, pronto per il rilascio in produzione -
- - - ---- - -**Documentazione**: https://fastapi.tiangolo.com - -**Codice Sorgente**: https://github.com/fastapi/fastapi - ---- - -FastAPI è un web framework moderno e veloce (a prestazioni elevate) che serve a creare API con Python 3.6+ basato sulle annotazioni di tipo di Python. - -Le sue caratteristiche principali sono: - -* **Velocità**: Prestazioni molto elevate, alla pari di **NodeJS** e **Go** (grazie a Starlette e Pydantic). [Uno dei framework Python più veloci in circolazione](#performance). -* **Veloce da programmare**: Velocizza il lavoro consentendo il rilascio di nuove funzionalità tra il 200% e il 300% più rapidamente. * -* **Meno bug**: Riduce di circa il 40% gli errori che commettono gli sviluppatori durante la scrittura del codice. * -* **Intuitivo**: Grande supporto per gli editor di testo con autocompletamento in ogni dove. In questo modo si può dedicare meno tempo al debugging. -* **Facile**: Progettato per essere facile da usare e imparare. Si riduce il tempo da dedicare alla lettura della documentazione. -* **Sintentico**: Minimizza la duplicazione di codice. Molteplici funzionalità, ognuna con la propria dichiarazione dei parametri. Meno errori. -* **Robusto**: Crea codice pronto per la produzione con documentazione automatica interattiva. -* **Basato sugli standard**: Basato su (e completamente compatibile con) gli open standard per le API: OpenAPI (precedentemente Swagger) e JSON Schema. - -* Stima basata sull'esito di test eseguiti su codice sorgente di applicazioni rilasciate in produzione da un team interno di sviluppatori. - -## Sponsor - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Se stai sviluppando un'app CLI da usare nel terminale invece che una web API, ti consigliamo **Typer**.
-
-**Typer** è il fratello minore di FastAPI. Ed è stato ideato per essere la **FastAPI delle CLI**. ⌨️ 🚀
-
-## Requisiti
-
-Python 3.6+
-
-FastAPI è basata su importanti librerie:
-
-* Starlette per le parti web.
-* Pydantic per le parti dei dati.
-
-## Installazione
-
-async def...uvicorn main:app --reload...email-validator - per la validazione di email.
-
-Usate da Starlette:
-
-* requests - Richiesto se vuoi usare il `TestClient`.
-* aiofiles - Richiesto se vuoi usare `FileResponse` o `StaticFiles`.
-* jinja2 - Richiesto se vuoi usare la configurazione template di default.
-* python-multipart - Richiesto se vuoi supportare il "parsing" con `request.form()`.
-* itsdangerous - Richiesto per usare `SessionMiddleware`.
-* pyyaml - Richiesto per il supporto dello `SchemaGenerator` di Starlette (probabilmente non ti serve con FastAPI).
-* graphene - Richiesto per il supporto di `GraphQLApp`.
-
-Usate da FastAPI / Starlette:
-
-* uvicorn - per il server che carica e serve la tua applicazione.
-* orjson - ichiesto se vuoi usare `ORJSONResponse`.
-* ujson - Richiesto se vuoi usare `UJSONResponse`.
-
-Puoi installarle tutte con `pip install fastapi[all]`.
-
-## Licenza
-
-Questo progetto è concesso in licenza in base ai termini della licenza MIT.
diff --git a/docs/it/mkdocs.yml b/docs/it/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/it/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/ja/docs/advanced/websockets.md b/docs/ja/docs/advanced/websockets.md
index 43009eba8..2517530ab 100644
--- a/docs/ja/docs/advanced/websockets.md
+++ b/docs/ja/docs/advanced/websockets.md
@@ -184,5 +184,5 @@ Client #1596980209979 left the chat
オプションの詳細については、Starletteのドキュメントを確認してください。
-* `WebSocket` クラス
-* クラスベースのWebSocket処理
+* `WebSocket` クラス
+* クラスベースのWebSocket処理
diff --git a/docs/ja/docs/alternatives.md b/docs/ja/docs/alternatives.md
index 8129a7002..9f5152c08 100644
--- a/docs/ja/docs/alternatives.md
+++ b/docs/ja/docs/alternatives.md
@@ -419,7 +419,7 @@ Marshmallowに匹敵しますが、ベンチマークではMarshmallowよりも
///
-### Starlette
+### Starlette
Starletteは、軽量なASGIフレームワーク/ツールキットで、高性能な非同期サービスの構築に最適です。
@@ -465,7 +465,7 @@ webに関するコアな部分を全て扱います。その上に機能を追
///
-### Uvicorn
+### Uvicorn
Uvicornは非常に高速なASGIサーバーで、uvloopとhttptoolsにより構成されています。
diff --git a/docs/ja/docs/deployment/manually.md b/docs/ja/docs/deployment/manually.md
index 4ea6bd8ff..da382a9c5 100644
--- a/docs/ja/docs/deployment/manually.md
+++ b/docs/ja/docs/deployment/manually.md
@@ -6,7 +6,7 @@
//// tab | Uvicorn
-* Uvicorn, uvloopとhttptoolsを基にした高速なASGIサーバ。
+* Uvicorn, uvloopとhttptoolsを基にした高速なASGIサーバ。
lt
+* XWT
+* PSGI
+
+### abbr가 설명을 제공 { #the-abbr-gives-an-explanation }
+
+* cluster
+* Deep Learning
+
+### abbr가 전체 문구와 설명을 제공 { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | 정보
+
+"abbr" 요소의 "title" 속성은 몇 가지 구체적인 지침에 따라 번역됩니다.
+
+번역에서는(영어 단어를 설명하기 위해) 자체 "abbr" 요소를 추가할 수 있으며, LLM은 이를 제거하면 안 됩니다.
+
+`scripts/translate.py`의 일반 프롬프트에서 `### HTML abbr elements` 섹션을 참고하세요.
+
+////
+
+## 제목 { #headings }
+
+//// tab | 테스트
+
+### 웹앱 개발하기 - 튜토리얼 { #develop-a-webapp-a-tutorial }
+
+안녕하세요.
+
+### 타입 힌트와 -애너테이션 { #type-hints-and-annotations }
+
+다시 안녕하세요.
+
+### super- 및 subclasses { #super-and-subclasses }
+
+다시 안녕하세요.
+
+////
+
+//// tab | 정보
+
+제목에 대한 유일한 강한 규칙은, LLM이 중괄호 안의 해시 부분을 변경하지 않아 링크가 깨지지 않게 하는 것입니다.
+
+`scripts/translate.py`의 일반 프롬프트에서 `### Headings` 섹션을 참고하세요.
+
+언어별 지침은 예를 들어 `docs/de/llm-prompt.md`의 `### Headings` 섹션을 참고하세요.
+
+////
+
+## 문서에서 사용되는 용어 { #terms-used-in-the-docs }
+
+//// tab | 테스트
+
+* 당신
+* 당신의
+
+* 예: (e.g.)
+* 등 (etc.)
+
+* `int`로서의 `foo`
+* `str`로서의 `bar`
+* `list`로서의 `baz`
+
+* 튜토리얼 - 사용자 가이드
+* 고급 사용자 가이드
+* SQLModel 문서
+* API 문서
+* 자동 문서
+
+* Data Science
+* Deep Learning
+* Machine Learning
+* Dependency Injection
+* HTTP Basic authentication
+* HTTP Digest
+* ISO format
+* JSON Schema 표준
+* JSON schema
+* schema definition
+* Password Flow
+* Mobile
+
+* deprecated
+* designed
+* invalid
+* on the fly
+* standard
+* default
+* case-sensitive
+* case-insensitive
+
+* 애플리케이션을 서빙하다
+* 페이지를 서빙하다
+
+* 앱
+* 애플리케이션
+
+* 요청
+* 응답
+* 오류 응답
+
+* 경로 처리
+* 경로 처리 데코레이터
+* 경로 처리 함수
+
+* body
+* 요청 body
+* 응답 body
+* JSON body
+* form body
+* file body
+* 함수 body
+
+* parameter
+* body parameter
+* path parameter
+* query parameter
+* cookie parameter
+* header parameter
+* form parameter
+* function parameter
+
+* event
+* startup event
+* 서버 startup
+* shutdown event
+* lifespan event
+
+* handler
+* event handler
+* exception handler
+* 처리하다
+
+* model
+* Pydantic model
+* data model
+* database model
+* form model
+* model object
+
+* class
+* base class
+* parent class
+* subclass
+* child class
+* sibling class
+* class method
+
+* header
+* headers
+* authorization header
+* `Authorization` header
+* forwarded header
+
+* dependency injection system
+* dependency
+* dependable
+* dependant
+
+* I/O bound
+* CPU bound
+* concurrency
+* parallelism
+* multiprocessing
+
+* env var
+* environment variable
+* `PATH`
+* `PATH` variable
+
+* authentication
+* authentication provider
+* authorization
+* authorization form
+* authorization provider
+* 사용자가 인증한다
+* 시스템이 사용자를 인증한다
+
+* CLI
+* command line interface
+
+* server
+* client
+
+* cloud provider
+* cloud service
+
+* development
+* development stages
+
+* dict
+* dictionary
+* enumeration
+* enum
+* enum member
+
+* encoder
+* decoder
+* encode하다
+* decode하다
+
+* exception
+* raise하다
+
+* expression
+* statement
+
+* frontend
+* backend
+
+* GitHub discussion
+* GitHub issue
+
+* performance
+* performance optimization
+
+* return type
+* return value
+
+* security
+* security scheme
+
+* task
+* background task
+* task function
+
+* template
+* template engine
+
+* type annotation
+* type hint
+
+* server worker
+* Uvicorn worker
+* Gunicorn Worker
+* worker process
+* worker class
+* workload
+
+* deployment
+* deploy하다
+
+* SDK
+* software development kit
+
+* `APIRouter`
+* `requirements.txt`
+* Bearer Token
+* breaking change
+* bug
+* button
+* callable
+* code
+* commit
+* context manager
+* coroutine
+* database session
+* disk
+* domain
+* engine
+* fake X
+* HTTP GET method
+* item
+* library
+* lifespan
+* lock
+* middleware
+* mobile application
+* module
+* mounting
+* network
+* origin
+* override
+* payload
+* processor
+* property
+* proxy
+* pull request
+* query
+* RAM
+* remote machine
+* status code
+* string
+* tag
+* web framework
+* wildcard
+* return하다
+* validate하다
+
+////
+
+//// tab | 정보
+
+이것은 문서에서 보이는 (대부분) 기술 용어의 불완전하고 비규범적인 목록입니다. 프롬프트 설계자가 어떤 용어에 대해 LLM에 추가적인 도움이 필요한지 파악하는 데 유용할 수 있습니다. 예를 들어, 좋은 번역을 계속 덜 좋은 번역으로 되돌릴 때, 또는 언어에서 용어의 활용/변화를 처리하는 데 문제가 있을 때 도움이 됩니다.
+
+예를 들어 `docs/de/llm-prompt.md`의 `### List of English terms and their preferred German translations` 섹션을 참고하세요.
+
+////
diff --git a/docs/ko/docs/about/index.md b/docs/ko/docs/about/index.md
index ee7804d32..dc2c72874 100644
--- a/docs/ko/docs/about/index.md
+++ b/docs/ko/docs/about/index.md
@@ -1,3 +1,3 @@
-# 소개
+# 소개 { #about }
-FastAPI에 대한 디자인, 영감 등에 대해 🤓
+FastAPI, 그 디자인, 영감 등에 대해 🤓
diff --git a/docs/ko/docs/advanced/additional-responses.md b/docs/ko/docs/advanced/additional-responses.md
new file mode 100644
index 000000000..a6f51f5b9
--- /dev/null
+++ b/docs/ko/docs/advanced/additional-responses.md
@@ -0,0 +1,247 @@
+# OpenAPI에서 추가 응답 { #additional-responses-in-openapi }
+
+/// warning | 경고
+
+이는 꽤 고급 주제입니다.
+
+**FastAPI**를 막 시작했다면, 이 내용이 필요 없을 수도 있습니다.
+
+///
+
+추가 상태 코드, 미디어 타입, 설명 등을 포함한 추가 응답을 선언할 수 있습니다.
+
+이러한 추가 응답은 OpenAPI 스키마에 포함되므로 API 문서에도 표시됩니다.
+
+하지만 이러한 추가 응답의 경우, 상태 코드와 콘텐츠를 포함하여 `JSONResponse` 같은 `Response`를 직접 반환하도록 반드시 처리해야 합니다.
+
+## `model`을 사용한 추가 응답 { #additional-response-with-model }
+
+*경로 처리 데코레이터*에 `responses` 파라미터를 전달할 수 있습니다.
+
+이는 `dict`를 받습니다. 키는 각 응답의 상태 코드(예: `200`)이고, 값은 각 응답에 대한 정보를 담은 다른 `dict`입니다.
+
+각 응답 `dict`에는 `response_model`처럼 Pydantic 모델을 담는 `model` 키가 있을 수 있습니다.
+
+**FastAPI**는 그 모델을 사용해 JSON Schema를 생성하고, OpenAPI의 올바른 위치에 포함합니다.
+
+예를 들어, 상태 코드 `404`와 Pydantic 모델 `Message`를 사용하는 다른 응답을 선언하려면 다음과 같이 작성할 수 있습니다:
+
+{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
+
+/// note | 참고
+
+`JSONResponse`를 직접 반환해야 한다는 점을 기억하세요.
+
+///
+
+/// info | 정보
+
+`model` 키는 OpenAPI의 일부가 아닙니다.
+
+**FastAPI**는 여기에서 Pydantic 모델을 가져와 JSON Schema를 생성하고 올바른 위치에 넣습니다.
+
+올바른 위치는 다음과 같습니다:
+
+* 값으로 또 다른 JSON 객체(`dict`)를 가지는 `content` 키 안에:
+ * 미디어 타입(예: `application/json`)을 키로 가지며, 값으로 또 다른 JSON 객체를 포함하고:
+ * `schema` 키가 있고, 그 값이 모델에서 생성된 JSON Schema입니다. 이것이 올바른 위치입니다.
+ * **FastAPI**는 이를 직접 포함하는 대신, OpenAPI의 다른 위치에 있는 전역 JSON Schemas를 참조하도록 여기에서 reference를 추가합니다. 이렇게 하면 다른 애플리케이션과 클라이언트가 그 JSON Schema를 직접 사용할 수 있고, 더 나은 코드 생성 도구 등을 제공할 수 있습니다.
+
+///
+
+이 *경로 처리*에 대해 OpenAPI에 생성되는 응답은 다음과 같습니다:
+
+```JSON hl_lines="3-12"
+{
+ "responses": {
+ "404": {
+ "description": "Additional Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Message"
+ }
+ }
+ }
+ },
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Item"
+ }
+ }
+ }
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+스키마는 OpenAPI 스키마 내부의 다른 위치를 참조합니다:
+
+```JSON hl_lines="4-16"
+{
+ "components": {
+ "schemas": {
+ "Message": {
+ "title": "Message",
+ "required": [
+ "message"
+ ],
+ "type": "object",
+ "properties": {
+ "message": {
+ "title": "Message",
+ "type": "string"
+ }
+ }
+ },
+ "Item": {
+ "title": "Item",
+ "required": [
+ "id",
+ "value"
+ ],
+ "type": "object",
+ "properties": {
+ "id": {
+ "title": "Id",
+ "type": "string"
+ },
+ "value": {
+ "title": "Value",
+ "type": "string"
+ }
+ }
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": [
+ "loc",
+ "msg",
+ "type"
+ ],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "msg": {
+ "title": "Message",
+ "type": "string"
+ },
+ "type": {
+ "title": "Error Type",
+ "type": "string"
+ }
+ }
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+## 주요 응답에 대한 추가 미디어 타입 { #additional-media-types-for-the-main-response }
+
+같은 `responses` 파라미터를 사용해 동일한 주요 응답에 대해 다른 미디어 타입을 추가할 수도 있습니다.
+
+예를 들어, *경로 처리*가 JSON 객체(미디어 타입 `application/json`) 또는 PNG 이미지(미디어 타입 `image/png`)를 반환할 수 있다고 선언하기 위해 `image/png`라는 추가 미디어 타입을 추가할 수 있습니다:
+
+{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
+
+/// note | 참고
+
+이미지는 `FileResponse`를 사용해 직접 반환해야 한다는 점에 유의하세요.
+
+///
+
+/// info | 정보
+
+`responses` 파라미터에서 다른 미디어 타입을 명시적으로 지정하지 않는 한, FastAPI는 응답이 주요 응답 클래스와 동일한 미디어 타입(기본값 `application/json`)을 가진다고 가정합니다.
+
+하지만 커스텀 응답 클래스를 지정하면서 미디어 타입을 `None`으로 설정했다면, FastAPI는 연결된 모델이 있는 모든 추가 응답에 대해 `application/json`을 사용합니다.
+
+///
+
+## 정보 결합하기 { #combining-information }
+
+`response_model`, `status_code`, `responses` 파라미터를 포함해 여러 위치의 응답 정보를 결합할 수도 있습니다.
+
+기본 상태 코드 `200`(또는 필요하다면 커스텀 코드)을 사용하여 `response_model`을 선언하고, 그와 동일한 응답에 대한 추가 정보를 `responses`에서 OpenAPI 스키마에 직접 선언할 수 있습니다.
+
+**FastAPI**는 `responses`의 추가 정보를 유지하고, 모델의 JSON Schema와 결합합니다.
+
+예를 들어, Pydantic 모델을 사용하고 커스텀 `description`을 가진 상태 코드 `404` 응답을 선언할 수 있습니다.
+
+또한 `response_model`을 사용하는 상태 코드 `200` 응답을 선언하되, 커스텀 `example`을 포함할 수도 있습니다:
+
+{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
+
+이 모든 내용은 OpenAPI에 결합되어 포함되고, API 문서에 표시됩니다:
+
+
+
+## 미리 정의된 응답과 커스텀 응답 결합하기 { #combine-predefined-responses-and-custom-ones }
+
+여러 *경로 처리*에 적용되는 미리 정의된 응답이 필요할 수도 있지만, 각 *경로 처리*마다 필요한 커스텀 응답과 결합하고 싶을 수도 있습니다.
+
+그런 경우 Python의 `dict` “unpacking” 기법인 `**dict_to_unpack`을 사용할 수 있습니다:
+
+```Python
+old_dict = {
+ "old key": "old value",
+ "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+여기서 `new_dict`는 `old_dict`의 모든 키-값 쌍에 더해 새 키-값 쌍까지 포함합니다:
+
+```Python
+{
+ "old key": "old value",
+ "second old key": "second old value",
+ "new key": "new value",
+}
+```
+
+이 기법을 사용해 *경로 처리*에서 일부 미리 정의된 응답을 재사용하고, 추가 커스텀 응답과 결합할 수 있습니다.
+
+예를 들어:
+
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
+
+## OpenAPI 응답에 대한 추가 정보 { #more-information-about-openapi-responses }
+
+응답에 정확히 무엇을 포함할 수 있는지 보려면, OpenAPI 사양의 다음 섹션을 확인하세요:
+
+* OpenAPI Responses Object: `Response Object`를 포함합니다.
+* OpenAPI Response Object: `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다.
diff --git a/docs/ko/docs/advanced/additional-status-codes.md b/docs/ko/docs/advanced/additional-status-codes.md
index da06cb778..64a7eabd5 100644
--- a/docs/ko/docs/advanced/additional-status-codes.md
+++ b/docs/ko/docs/advanced/additional-status-codes.md
@@ -1,16 +1,16 @@
-# 추가 상태 코드
+# 추가 상태 코드 { #additional-status-codes }
기본적으로 **FastAPI**는 응답을 `JSONResponse`를 사용하여 반환하며, *경로 작업(path operation)*에서 반환한 내용을 해당 `JSONResponse` 안에 넣어 반환합니다.
기본 상태 코드 또는 *경로 작업*에서 설정한 상태 코드를 사용합니다.
-## 추가 상태 코드
+## 추가 상태 코드 { #additional-status-codes_1 }
기본 상태 코드와 별도로 추가 상태 코드를 반환하려면 `JSONResponse`와 같이 `Response`를 직접 반환하고 추가 상태 코드를 직접 설정할 수 있습니다.
예를 들어 항목을 업데이트할 수 있는 *경로 작업*이 있고 성공 시 200 “OK”의 HTTP 상태 코드를 반환한다고 가정해 보겠습니다.
-하지만 새로운 항목을 허용하기를 원할 것입니다. 항목이 이전에 존재하지 않았다면 이를 생성하고 HTTP 상태 코드 201 "Created"를 반환합니다.
+하지만 새로운 항목을 허용하기를 원할 것입니다. 그리고 항목이 이전에 존재하지 않았다면 이를 생성하고 HTTP 상태 코드 201 "Created"를 반환합니다.
이를 위해서는 `JSONResponse`를 가져와서 원하는 `status_code`를 설정하여 콘텐츠를 직접 반환합니다:
@@ -26,7 +26,7 @@
///
-/// note | 기술적 세부 정보
+/// note | 기술 세부사항
`from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
@@ -34,7 +34,7 @@
///
-## OpenAPI 및 API 문서
+## OpenAPI 및 API 문서 { #openapi-and-api-docs }
추가 상태 코드와 응답을 직접 반환하는 경우, FastAPI는 반환할 내용을 미리 알 수 있는 방법이 없기 때문에 OpenAPI 스키마(API 문서)에 포함되지 않습니다.
diff --git a/docs/ko/docs/advanced/advanced-dependencies.md b/docs/ko/docs/advanced/advanced-dependencies.md
index 7fa043fa3..04e557d15 100644
--- a/docs/ko/docs/advanced/advanced-dependencies.md
+++ b/docs/ko/docs/advanced/advanced-dependencies.md
@@ -1,6 +1,6 @@
-# 고급 의존성
+# 고급 의존성 { #advanced-dependencies }
-## 매개변수화된 의존성
+## 매개변수화된 의존성 { #parameterized-dependencies }
지금까지 본 모든 의존성은 고정된 함수 또는 클래스입니다.
@@ -10,7 +10,7 @@
이때 해당 고정된 내용을 매개변수화할 수 있길 바랍니다.
-## "호출 가능한" 인스턴스
+## "호출 가능한" 인스턴스 { #a-callable-instance }
Python에는 클래스의 인스턴스를 "호출 가능"하게 만드는 방법이 있습니다.
@@ -21,9 +21,9 @@ Python에는 클래스의 인스턴스를 "호출 가능"하게 만드는 방법
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
이 경우, **FastAPI**는 추가 매개변수와 하위 의존성을 확인하기 위해 `__call__`을 사용하게 되며,
-나중에 *경로 연산 함수*에서 매개변수에 값을 전달할 때 이를 호출하게 됩니다.
+나중에 *경로 처리 함수*에서 매개변수에 값을 전달할 때 이를 호출하게 됩니다.
-## 인스턴스 매개변수화하기
+## 인스턴스 매개변수화하기 { #parameterize-the-instance }
이제 `__init__`을 사용하여 의존성을 "매개변수화"할 수 있는 인스턴스의 매개변수를 선언할 수 있습니다:
@@ -31,7 +31,7 @@ Python에는 클래스의 인스턴스를 "호출 가능"하게 만드는 방법
이 경우, **FastAPI**는 `__init__`에 전혀 관여하지 않으며, 우리는 이 메서드를 코드에서 직접 사용하게 됩니다.
-## 인스턴스 생성하기
+## 인스턴스 생성하기 { #create-an-instance }
다음과 같이 이 클래스의 인스턴스를 생성할 수 있습니다:
@@ -39,10 +39,9 @@ Python에는 클래스의 인스턴스를 "호출 가능"하게 만드는 방법
이렇게 하면 `checker.fixed_content` 속성에 `"bar"`라는 값을 담아 의존성을 "매개변수화"할 수 있습니다.
-## 인스턴스를 의존성으로 사용하기
+## 인스턴스를 의존성으로 사용하기 { #use-the-instance-as-a-dependency }
-그런 다음, `Depends(FixedContentQueryChecker)` 대신 `Depends(checker)`에서 이 `checker` 인스턴스를 사용할 수 있으며,
-클래스 자체가 아닌 인스턴스 `checker`가 의존성이 됩니다.
+그런 다음, 클래스 자체가 아닌 인스턴스 `checker`가 의존성이 되므로, `Depends(FixedContentQueryChecker)` 대신 `Depends(checker)`에서 이 `checker` 인스턴스를 사용할 수 있습니다.
의존성을 해결할 때 **FastAPI**는 이 `checker`를 다음과 같이 호출합니다:
@@ -50,18 +49,116 @@ Python에는 클래스의 인스턴스를 "호출 가능"하게 만드는 방법
checker(q="somequery")
```
-...그리고 이때 반환되는 값을 *경로 연산 함수*의 `fixed_content_included` 매개변수로 전달합니다:
+...그리고 이때 반환되는 값을 *경로 처리 함수*의 의존성 값으로, `fixed_content_included` 매개변수에 전달합니다:
{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
-/// tip | 참고
+/// tip | 팁
이 모든 과정이 복잡하게 느껴질 수 있습니다. 그리고 지금은 이 방법이 얼마나 유용한지 명확하지 않을 수도 있습니다.
이 예시는 의도적으로 간단하게 만들었지만, 전체 구조가 어떻게 작동하는지 보여줍니다.
-보안 관련 장에서는 이와 같은 방식으로 구현된 편의 함수들이 있습니다.
+보안 관련 장에서는 이와 같은 방식으로 구현된 유틸리티 함수들이 있습니다.
-이 모든 과정을 이해했다면, 이러한 보안 도구들이 내부적으로 어떻게 작동하는지 이미 파악한 것입니다.
+이 모든 과정을 이해했다면, 이러한 보안용 유틸리티 도구들이 내부적으로 어떻게 작동하는지 이미 파악한 것입니다.
///
+
+## `yield`, `HTTPException`, `except`, 백그라운드 태스크가 있는 의존성 { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | 경고
+
+대부분의 경우 이러한 기술 세부사항이 필요하지 않을 것입니다.
+
+이 세부사항은 주로 0.121.0 이전의 FastAPI 애플리케이션이 있고 `yield`가 있는 의존성에서 문제가 발생하는 경우에 유용합니다.
+
+///
+
+`yield`가 있는 의존성은 여러 사용 사례를 수용하고 일부 문제를 해결하기 위해 시간이 지나며 발전해 왔습니다. 다음은 변경된 내용의 요약입니다.
+
+### `yield`와 `scope`가 있는 의존성 { #dependencies-with-yield-and-scope }
+
+0.121.0 버전에서 FastAPI는 `yield`가 있는 의존성에 대해 `Depends(scope="function")` 지원을 추가했습니다.
+
+`Depends(scope="function")`를 사용하면, `yield` 이후의 종료 코드는 *경로 처리 함수*가 끝난 직후(클라이언트에 응답이 반환되기 전)에 실행됩니다.
+
+그리고 `Depends(scope="request")`(기본값)를 사용하면, `yield` 이후의 종료 코드는 응답이 전송된 후에 실행됩니다.
+
+자세한 내용은 [Dependencies with `yield` - Early exit and `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope) 문서를 참고하세요.
+
+### `yield`가 있는 의존성과 `StreamingResponse`, 기술 세부사항 { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+FastAPI 0.118.0 이전에는 `yield`가 있는 의존성을 사용하면, *경로 처리 함수*가 반환된 뒤 응답을 보내기 직전에 `yield` 이후의 종료 코드가 실행되었습니다.
+
+의도는 응답이 네트워크를 통해 전달되기를 기다리면서 필요한 것보다 더 오래 리소스를 점유하지 않도록 하는 것이었습니다.
+
+이 변경은 `StreamingResponse`를 반환하는 경우에도 `yield`가 있는 의존성의 종료 코드가 이미 실행된다는 의미이기도 했습니다.
+
+예를 들어, `yield`가 있는 의존성에 데이터베이스 세션이 있다면, `StreamingResponse`는 데이터를 스트리밍하는 동안 해당 세션을 사용할 수 없게 됩니다. `yield` 이후의 종료 코드에서 세션이 이미 닫혔기 때문입니다.
+
+이 동작은 0.118.0에서 되돌려져, `yield` 이후의 종료 코드가 응답이 전송된 뒤 실행되도록 변경되었습니다.
+
+/// info | 정보
+
+아래에서 보시겠지만, 이는 0.106.0 버전 이전의 동작과 매우 비슷하지만, 여러 개선 사항과 코너 케이스에 대한 버그 수정이 포함되어 있습니다.
+
+///
+
+#### 종료 코드를 조기에 실행하는 사용 사례 { #use-cases-with-early-exit-code }
+
+특정 조건의 일부 사용 사례에서는 응답을 보내기 전에 `yield`가 있는 의존성의 종료 코드를 실행하던 예전 동작이 도움이 될 수 있습니다.
+
+예를 들어, `yield`가 있는 의존성에서 데이터베이스 세션을 사용해 사용자를 검증만 하고, *경로 처리 함수*에서는 그 데이터베이스 세션을 다시는 사용하지 않으며(의존성에서만 사용), **그리고** 응답을 전송하는 데 오랜 시간이 걸리는 경우를 생각해 봅시다. 예를 들어 데이터를 천천히 보내는 `StreamingResponse`인데, 어떤 이유로든 데이터베이스를 사용하지는 않는 경우입니다.
+
+이 경우 데이터베이스 세션은 응답 전송이 끝날 때까지 유지되지만, 사용하지 않는다면 굳이 유지할 필요가 없습니다.
+
+다음과 같이 보일 수 있습니다:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+다음에서 `Session`을 자동으로 닫는 종료 코드는:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+...응답이 느린 데이터 전송을 마친 뒤에 실행됩니다:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+하지만 `generate_stream()`는 데이터베이스 세션을 사용하지 않으므로, 응답을 전송하는 동안 세션을 열린 채로 유지할 필요는 없습니다.
+
+SQLModel(또는 SQLAlchemy)을 사용하면서 이런 특정 사용 사례가 있다면, 더 이상 필요하지 않을 때 세션을 명시적으로 닫을 수 있습니다:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+그러면 세션이 데이터베이스 연결을 해제하여, 다른 요청들이 이를 사용할 수 있게 됩니다.
+
+`yield`가 있는 의존성에서 조기 종료가 필요한 다른 사용 사례가 있다면, 여러분의 구체적인 사용 사례와 `yield`가 있는 의존성에 대한 조기 종료가 어떤 점에서 이득이 되는지를 포함해 GitHub Discussion Question을 생성해 주세요.
+
+`yield`가 있는 의존성에서 조기 종료에 대한 설득력 있는 사용 사례가 있다면, 조기 종료를 선택적으로 활성화할 수 있는 새로운 방법을 추가하는 것을 고려하겠습니다.
+
+### `yield`가 있는 의존성과 `except`, 기술 세부사항 { #dependencies-with-yield-and-except-technical-details }
+
+FastAPI 0.110.0 이전에는 `yield`가 있는 의존성을 사용한 다음 그 의존성에서 `except`로 예외를 잡고, 예외를 다시 발생시키지 않으면, 예외가 자동으로 어떤 예외 핸들러 또는 내부 서버 오류 핸들러로 raise/forward 되었습니다.
+
+이는 핸들러 없이 전달된 예외(내부 서버 오류)로 인해 처리되지 않은 메모리 사용이 발생하는 문제를 수정하고, 일반적인 Python 코드의 동작과 일관되게 하기 위해 0.110.0 버전에서 변경되었습니다.
+
+### 백그라운드 태스크와 `yield`가 있는 의존성, 기술 세부사항 { #background-tasks-and-dependencies-with-yield-technical-details }
+
+FastAPI 0.106.0 이전에는 `yield` 이후에 예외를 발생시키는 것이 불가능했습니다. `yield`가 있는 의존성의 종료 코드는 응답이 전송된 *후에* 실행되었기 때문에, [Exception Handlers](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}가 이미 실행된 뒤였습니다.
+
+이는 주로 백그라운드 태스크 안에서 의존성이 "yield"한 동일한 객체들을 사용할 수 있게 하기 위한 설계였습니다. 백그라운드 태스크가 끝난 뒤에 종료 코드가 실행되었기 때문입니다.
+
+이는 응답이 네트워크를 통해 전달되기를 기다리는 동안 리소스를 점유하지 않기 위한 의도로 FastAPI 0.106.0에서 변경되었습니다.
+
+/// tip | 팁
+
+추가로, 백그라운드 태스크는 보통 별도의 리소스(예: 자체 데이터베이스 연결)를 가지고 따로 처리되어야 하는 독립적인 로직 집합입니다.
+
+따라서 이 방식이 코드를 더 깔끔하게 만들어줄 가능성이 큽니다.
+
+///
+
+이 동작에 의존하던 경우라면, 이제는 백그라운드 태스크를 위한 리소스를 백그라운드 태스크 내부에서 생성하고, 내부적으로는 `yield`가 있는 의존성의 리소스에 의존하지 않는 데이터만 사용해야 합니다.
+
+예를 들어, 동일한 데이터베이스 세션을 사용하는 대신, 백그라운드 태스크 내부에서 새 데이터베이스 세션을 생성하고, 이 새 세션을 사용해 데이터베이스에서 객체를 가져오면 됩니다. 그리고 데이터베이스에서 가져온 객체를 백그라운드 태스크 함수의 매개변수로 전달하는 대신, 해당 객체의 ID를 전달한 다음 백그라운드 태스크 함수 내부에서 객체를 다시 가져오면 됩니다.
diff --git a/docs/ko/docs/advanced/async-tests.md b/docs/ko/docs/advanced/async-tests.md
index 37dfe2979..6c8593681 100644
--- a/docs/ko/docs/advanced/async-tests.md
+++ b/docs/ko/docs/advanced/async-tests.md
@@ -1,31 +1,26 @@
-# 비동기 테스트 코드 작성
+# 비동기 테스트 { #async-tests }
-이전 장에서 `TestClient` 를 이용해 **FastAPI** 어플리케이션 테스트를 작성하는 법을 배우셨을텐데요.
-지금까지는 `async` 키워드 사용없이 동기 함수의 테스트 코드를 작성하는 법만 익혔습니다.
+제공된 `TestClient`를 사용하여 **FastAPI** 애플리케이션을 테스트하는 방법을 이미 살펴보았습니다. 지금까지는 `async` 함수를 사용하지 않고, 동기 테스트를 작성하는 방법만 보았습니다.
-하지만 비동기 함수를 사용하여 테스트 코드를 작성하는 것은 매우 유용할 수 있습니다.
-예를 들면 데이터베이스에 비동기로 쿼리하는 경우를 생각해봅시다.
-FastAPI 애플리케이션에 요청을 보내고, 비동기 데이터베이스 라이브러리를 사용하여 백엔드가 데이터베이스에 올바르게 데이터를 기록했는지 확인하고 싶을 때가 있을 겁니다.
+테스트에서 비동기 함수를 사용할 수 있으면 유용할 수 있습니다. 예를 들어 데이터베이스를 비동기로 쿼리하는 경우를 생각해 보세요. FastAPI 애플리케이션에 요청을 보낸 다음, async 데이터베이스 라이브러리를 사용하면서 백엔드가 데이터베이스에 올바른 데이터를 성공적으로 기록했는지 검증하고 싶을 수 있습니다.
-이런 경우의 테스트 코드를 어떻게 비동기로 작성하는지 알아봅시다.
+어떻게 동작하게 만들 수 있는지 살펴보겠습니다.
-## pytest.mark.anyio
+## pytest.mark.anyio { #pytest-mark-anyio }
-앞에서 작성한 테스트 함수에서 비동기 함수를 호출하고 싶다면, 테스트 코드도 비동기 함수여야합니다.
-AnyIO는 특정 테스트 함수를 비동기 함수로 호출 할 수 있는 깔끔한 플러그인을 제공합니다.
+테스트에서 비동기 함수를 호출하려면, 테스트 함수도 비동기여야 합니다. AnyIO는 이를 위한 깔끔한 플러그인을 제공하며, 일부 테스트 함수를 비동기로 호출하도록 지정할 수 있습니다.
+## HTTPX { #httpx }
-## HTTPX
+**FastAPI** 애플리케이션이 `async def` 대신 일반 `def` 함수를 사용하더라도, 내부적으로는 여전히 `async` 애플리케이션입니다.
-**FastAPI** 애플리케이션이 `async def` 대신 `def` 키워드로 선언된 함수를 사용하더라도, 내부적으로는 여전히 `비동기` 애플리케이션입니다.
+`TestClient`는 표준 pytest를 사용하여, 일반 `def` 테스트 함수 안에서 비동기 FastAPI 애플리케이션을 호출하도록 내부에서 마법 같은 처리를 합니다. 하지만 비동기 함수 안에서 이를 사용하면 그 마법은 더 이상 동작하지 않습니다. 테스트를 비동기로 실행하면, 테스트 함수 안에서 `TestClient`를 더 이상 사용할 수 없습니다.
-`TestClient`는 pytest 표준을 사용하여 비동기 FastAPI 애플리케이션을 일반적인 `def` 테스트 함수 내에서 호출할 수 있도록 내부에서 마술을 부립니다. 하지만 이 마술은 비동기 함수 내부에서 사용할 때는 더 이상 작동하지 않습니다. 테스트를 비동기로 실행하면, 더 이상 테스트 함수 내부에서 `TestClient`를 사용할 수 없습니다.
+`TestClient`는 HTTPX를 기반으로 하며, 다행히 HTTPX를 직접 사용해 API를 테스트할 수 있습니다.
-`TestClient`는 HTTPX를 기반으로 하고 있으며, 다행히 이를 직접 사용하여 API를 테스트할 수 있습니다.
+## 예시 { #example }
-## 예시
-
-간단한 예시를 위해 [더 큰 어플리케이션 만들기](../ko/tutorial/bigger-applications.md){.internal-link target=_blank} 와 [테스트](../ko/tutorial/testing.md){.internal-link target=_blank}:에서 다룬 파일 구조와 비슷한 형태를 확인해봅시다:
+간단한 예시로, [더 큰 애플리케이션](../tutorial/bigger-applications.md){.internal-link target=_blank}과 [테스트](../tutorial/testing.md){.internal-link target=_blank}에서 설명한 것과 비슷한 파일 구조를 살펴보겠습니다:
```
.
@@ -35,17 +30,17 @@ AnyIO는 특정 테스트 함수를 비동기 함수로 호출 할 수 있는
│ └── test_main.py
```
- `main.py`는 아래와 같아야 합니다:
+`main.py` 파일은 다음과 같습니다:
-{* ../../docs_src/async_tests/main.py *}
+{* ../../docs_src/async_tests/app_a_py39/main.py *}
-`test_main.py` 파일은 `main.py`에 대한 테스트가 있을 텐데, 다음과 같을 수 있습니다:
+`test_main.py` 파일에는 `main.py`에 대한 테스트가 있으며, 이제 다음과 같이 보일 수 있습니다:
-{* ../../docs_src/async_tests/test_main.py *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py *}
-## 실행하기
+## 실행하기 { #run-it }
-아래의 명령어로 테스트 코드를 실행합니다:
+다음과 같이 평소처럼 테스트를 실행할 수 있습니다:
+
+하지만 프록시(포트 `9999`)를 사용해 "공식" URL인 `/api/v1/docs`에서 docs UI에 접근하면, 올바르게 동작합니다! 🎉
+
+http://127.0.0.1:9999/api/v1/docs에서 확인할 수 있습니다:
+
+
+
+원하던 그대로입니다. ✔️
+
+이는 FastAPI가 이 `root_path`를 사용해, OpenAPI에서 기본 `server`를 `root_path`가 제공한 URL로 생성하기 때문입니다.
+
+## 추가 서버 { #additional-servers }
+
+/// warning | 경고
+
+이는 더 고급 사용 사례입니다. 건너뛰어도 괜찮습니다.
+
+///
+
+기본적으로 **FastAPI**는 OpenAPI 스키마에서 `root_path`의 URL로 `server`를 생성합니다.
+
+하지만 예를 들어 동일한 docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다.
+
+사용자 정의 `servers` 리스트를 전달했고 `root_path`(API가 프록시 뒤에 있기 때문)가 있다면, **FastAPI**는 리스트의 맨 앞에 이 `root_path`를 가진 "server"를 삽입합니다.
+
+예:
+
+{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *}
+
+다음과 같은 OpenAPI 스키마를 생성합니다:
+
+```JSON hl_lines="5-7"
+{
+ "openapi": "3.1.0",
+ // More stuff here
+ "servers": [
+ {
+ "url": "/api/v1"
+ },
+ {
+ "url": "https://stag.example.com",
+ "description": "Staging environment"
+ },
+ {
+ "url": "https://prod.example.com",
+ "description": "Production environment"
+ }
+ ],
+ "paths": {
+ // More stuff here
+ }
+}
+```
+
+/// tip | 팁
+
+`root_path`에서 가져온 값인 `/api/v1`의 `url` 값을 가진, 자동 생성된 server에 주목하세요.
+
+///
+
+http://127.0.0.1:9999/api/v1/docs의 docs UI에서는 다음처럼 보입니다:
+
+
+
+/// tip | 팁
+
+docs UI는 선택한 server와 상호작용합니다.
+
+///
+
+/// note | 기술 세부사항
+
+OpenAPI 사양에서 `servers` 속성은 선택 사항입니다.
+
+`servers` 파라미터를 지정하지 않고 `root_path`가 `/`와 같다면, 생성된 OpenAPI 스키마의 `servers` 속성은 기본적으로 완전히 생략되며, 이는 `url` 값이 `/`인 단일 server와 동등합니다.
+
+///
+
+### `root_path`에서 자동 server 비활성화하기 { #disable-automatic-server-from-root-path }
+
+**FastAPI**가 `root_path`를 사용한 자동 server를 포함하지 않게 하려면, `root_path_in_servers=False` 파라미터를 사용할 수 있습니다:
+
+{* ../../docs_src/behind_a_proxy/tutorial004_py39.py hl[9] *}
+
+그러면 OpenAPI 스키마에 포함되지 않습니다.
+
+## 서브 애플리케이션 마운트하기 { #mounting-a-sub-application }
+
+프록시에서 `root_path`를 사용하면서도, [서브 애플리케이션 - 마운트](sub-applications.md){.internal-link target=_blank}에 설명된 것처럼 서브 애플리케이션을 마운트해야 한다면, 기대하는 대로 일반적으로 수행할 수 있습니다.
+
+FastAPI가 내부적으로 `root_path`를 똑똑하게 사용하므로, 그냥 동작합니다. ✨
diff --git a/docs/ko/docs/advanced/custom-response.md b/docs/ko/docs/advanced/custom-response.md
index 2001956fa..55dc2a4be 100644
--- a/docs/ko/docs/advanced/custom-response.md
+++ b/docs/ko/docs/advanced/custom-response.md
@@ -1,4 +1,4 @@
-# 사용자 정의 응답 - HTML, Stream, 파일, 기타
+# 사용자 정의 응답 - HTML, Stream, 파일, 기타 { #custom-response-html-stream-file-others }
기본적으로, **FastAPI** 응답을 `JSONResponse`를 사용하여 반환합니다.
@@ -6,11 +6,11 @@
그러나 `Response` (또는 `JSONResponse`와 같은 하위 클래스)를 직접 반환하면, 데이터가 자동으로 변환되지 않으며 (심지어 `response_model`을 선언했더라도), 문서화가 자동으로 생성되지 않습니다(예를 들어, 생성된 OpenAPI의 일부로 HTTP 헤더 `Content-Type`에 특정 "미디어 타입"을 포함하는 경우).
-하지만 *경로 작업 데코레이터*에서 `response_class` 매개변수를 사용하여 원하는 `Response`(예: 모든 `Response` 하위 클래스)를 선언할 수도 있습니다.
+하지만 *경로 처리 데코레이터*에서 `response_class` 매개변수를 사용하여 원하는 `Response`(예: 모든 `Response` 하위 클래스)를 선언할 수도 있습니다.
-*경로 작업 함수*에서 반환하는 내용은 해당 `Response`안에 포함됩니다.
+*경로 처리 함수*에서 반환하는 내용은 해당 `Response`안에 포함됩니다.
-그리고 만약 그 `Response`가 `JSONResponse`와 `UJSONResponse`의 경우 처럼 JSON 미디어 타입(`application/json`)을 가지고 있다면, *경로 작업 데코레이터*에서 선언한 Pydantic의 `response_model`을 사용해 자동으로 변환(및 필터링) 됩니다.
+그리고 만약 그 `Response`가 `JSONResponse`와 `UJSONResponse`의 경우 처럼 JSON 미디어 타입(`application/json`)을 가지고 있다면, *경로 처리 데코레이터*에서 선언한 Pydantic의 `response_model`을 사용해 자동으로 변환(및 필터링) 됩니다.
/// note | 참고
@@ -18,11 +18,11 @@
///
-## `ORJSONResponse` 사용하기
+## `ORJSONResponse` 사용하기 { #use-orjsonresponse }
-예를 들어, 성능을 극대화하려는 경우, orjson을 설치하여 사용하고 응답을 `ORJSONResponse`로 설정할 수 있습니다.
+예를 들어, 성능을 극대화하려는 경우, `orjson`을 설치하여 사용하고 응답을 `ORJSONResponse`로 설정할 수 있습니다.
-사용하고자 하는 `Response` 클래스(하위 클래스)를 임포트한 후, **경로 작업 데코레이터*에서 선언하세요.
+사용하고자 하는 `Response` 클래스(하위 클래스)를 임포트한 후, *경로 처리 데코레이터*에서 선언하세요.
대규모 응답의 경우, 딕셔너리를 반환하는 것보다 `Response`를 반환하는 것이 훨씬 빠릅니다.
@@ -30,7 +30,7 @@
하지만 반환하는 내용이 **JSON으로 직렬화 가능**하다고 확신하는 경우, 해당 내용을 응답 클래스에 직접 전달할 수 있으며, FastAPI가 반환 내용을 `jsonable_encoder`를 통해 처리한 뒤 응답 클래스에 전달하는 오버헤드를 피할 수 있습니다.
-{* ../../docs_src/custom_response/tutorial001b.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial001b_py39.py hl[2,7] *}
/// info | 정보
@@ -48,14 +48,14 @@
///
-## HTML 응답
+## HTML 응답 { #html-response }
**FastAPI**에서 HTML 응답을 직접 반환하려면 `HTMLResponse`를 사용하세요.
* `HTMLResponse`를 임포트 합니다.
-* *경로 작업 데코레이터*의 `response_class` 매개변수로 `HTMLResponse`를 전달합니다.
+* *경로 처리 데코레이터*의 `response_class` 매개변수로 `HTMLResponse`를 전달합니다.
-{* ../../docs_src/custom_response/tutorial002.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *}
/// info | 정보
@@ -67,17 +67,17 @@
///
-### `Response` 반환하기
+### `Response` 반환하기 { #return-a-response }
-[응답을 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 본 것 처럼, *경로 작업*에서 응답을 직접 반환하여 재정의할 수도 있습니다.
+[응답을 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 본 것 처럼, *경로 처리*에서 응답을 직접 반환하여 재정의할 수도 있습니다.
위의 예제와 동일하게 `HTMLResponse`를 반환하는 코드는 다음과 같을 수 있습니다:
-{* ../../docs_src/custom_response/tutorial003.py hl[2,7,19] *}
+{* ../../docs_src/custom_response/tutorial003_py39.py hl[2,7,19] *}
/// warning | 경고
-*경로 작업 함수*에서 직접 반환된 `Response`는 OpenAPI에 문서화되지 않습니다(예를들어, `Content-Type`이 문서화되지 않음) 자동 대화형 문서에서도 표시되지 않습니다.
+*경로 처리 함수*에서 직접 반환된 `Response`는 OpenAPI에 문서화되지 않습니다(예를들어, `Content-Type`이 문서화되지 않음) 자동 대화형 문서에서도 표시되지 않습니다.
///
@@ -87,27 +87,27 @@
///
-### OpenAPI에 문서화하고 `Response` 재정의 하기
+### OpenAPI에 문서화하고 `Response` 재정의 하기 { #document-in-openapi-and-override-response }
함수 내부에서 응답을 재정의하면서 동시에 OpenAPI에서 "미디어 타입"을 문서화하고 싶다면, `response_class` 매게변수를 사용하면서 `Response` 객체를 반환할 수 있습니다.
-이 경우 `response_class`는 OpenAPI *경로 작업*을 문서화하는 데만 사용되고, 실제로는 여러분이 반환한 `Response`가 그대로 사용됩니다.
+이 경우 `response_class`는 OpenAPI *경로 처리*를 문서화하는 데만 사용되고, 실제로는 여러분이 반환한 `Response`가 그대로 사용됩니다.
-### `HTMLResponse`직접 반환하기
+#### `HTMLResponse`직접 반환하기 { #return-an-htmlresponse-directly }
예를 들어, 다음과 같이 작성할 수 있습니다:
-{* ../../docs_src/custom_response/tutorial004.py hl[7,21,23] *}
+{* ../../docs_src/custom_response/tutorial004_py39.py hl[7,21,23] *}
이 예제에서, `generate_html_response()` 함수는 HTML을 `str`로 반환하는 대신 이미 `Response`를 생성하고 반환합니다.
`generate_html_response()`를 호출한 결과를 반환함으로써, 기본적인 **FastAPI** 기본 동작을 재정의 하는 `Response`를 이미 반환하고 있습니다.
-하지만 `response_class`에 `HTMLResponse`를 함께 전달했기 때문에, FastAPI는 이를 OpenAPI 및 대화형 문서에서 `text/html`로 HTML을 문서화 하는 방법을 알 수 있습니다.
+하지만 `response_class`에 `HTMLResponse`를 함께 전달했기 때문에, **FastAPI**는 이를 OpenAPI 및 대화형 문서에서 `text/html`로 HTML을 문서화 하는 방법을 알 수 있습니다.
-## 사용 가능한 응답들
+## 사용 가능한 응답들 { #available-responses }
다음은 사용할 수 있는 몇가지 응답들 입니다.
@@ -121,7 +121,7 @@
///
-### `Response`
+### `Response` { #response }
기본 `Response` 클래스는 다른 모든 응답 클래스의 부모 클래스 입니다.
@@ -134,27 +134,27 @@
* `headers` - 문자열로 이루어진 `dict`.
* `media_type` - 미디어 타입을 나타내는 `str` 예: `"text/html"`.
-FastAPI (실제로는 Starlette)가 자동으로 `Content-Length` 헤더를 포함시킵니다. 또한 `media_type`에 기반하여 `Content-Type` 헤더를 포함하며, 텍스트 타입의 경우 문자 집합을 추가 합니다.
+FastAPI (실제로는 Starlette)가 자동으로 Content-Length 헤더를 포함시킵니다. 또한 `media_type`에 기반하여 Content-Type 헤더를 포함하며, 텍스트 타입의 경우 문자 집합을 추가 합니다.
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-### `HTMLResponse`
+### `HTMLResponse` { #htmlresponse }
텍스트 또는 바이트를 받아 HTML 응답을 반환합니다. 위에서 설명한 내용과 같습니다.
-### `PlainTextResponse`
+### `PlainTextResponse` { #plaintextresponse }
텍스트 또는 바이트를 받아 일반 텍스트 응답을 반환합니다.
-{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
-### `JSONResponse`
+### `JSONResponse` { #jsonresponse }
데이터를 받아 `application/json`으로 인코딩된 응답을 반환합니다.
이는 위에서 설명했듯이 **FastAPI**에서 기본적으로 사용되는 응답 형식입니다.
-### `ORJSONResponse`
+### `ORJSONResponse` { #orjsonresponse }
`orjson`을 사용하여 빠른 JSON 응답을 제공하는 대안입니다. 위에서 설명한 내용과 같습니다.
@@ -164,13 +164,13 @@ FastAPI (실제로는 Starlette)가 자동으로 `Content-Length` 헤더를 포
///
-### `UJSONResponse`
+### `UJSONResponse` { #ujsonresponse }
`ujson`을 사용한 또 다른 JSON 응답 형식입니다.
/// info | 정보
-이 응답을 사용하려면 `ujson`을 설치해야합니다. 예: 'pip install ujson`.
+이 응답을 사용하려면 `ujson`을 설치해야합니다. 예: `pip install ujson`.
///
@@ -180,7 +180,7 @@ FastAPI (실제로는 Starlette)가 자동으로 `Content-Length` 헤더를 포
///
-{* ../../docs_src/custom_response/tutorial001.py hl[2,7] *}
+{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *}
/// tip | 팁
@@ -188,22 +188,22 @@ FastAPI (실제로는 Starlette)가 자동으로 `Content-Length` 헤더를 포
///
-### `RedirectResponse`
+### `RedirectResponse` { #redirectresponse }
HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 307(임시 리디렉션)으로 설정됩니다.
`RedirectResponse`를 직접 반환할 수 있습니다.
-{* ../../docs_src/custom_response/tutorial006.py hl[2,9] *}
+{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *}
---
또는 `response_class` 매개변수에서 사용할 수도 있습니다:
-{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006b_py39.py hl[2,7,9] *}
-이 경우, *경로 작업* 함수에서 URL을 직접 반환할 수 있습니다.
+이 경우, *경로 처리* 함수에서 URL을 직접 반환할 수 있습니다.
이 경우, 사용되는 `status_code`는 `RedirectResponse`의 기본값인 `307` 입니다.
@@ -211,23 +211,23 @@ HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 30
`status_code` 매개변수를 `response_class` 매개변수와 함께 사용할 수도 있습니다:
-{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *}
-### `StreamingResponse`
+### `StreamingResponse` { #streamingresponse }
비동기 제너레이터 또는 일반 제너레이터/이터레이터를 받아 응답 본문을 스트리밍 합니다.
-{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *}
-#### 파일과 같은 객체를 사용한 `StreamingResponse`
+#### 파일과 같은 객체를 사용한 `StreamingResponse` { #using-streamingresponse-with-file-like-objects }
-파일과 같은 객체(예: `open()`으로 반환된 객체)가 있는 경우, 해당 파일과 같은 객체를 반복(iterate)하는 제너레이터 함수를 만들 수 있습니다.
+file-like 객체(예: `open()`으로 반환된 객체)가 있는 경우, 해당 file-like 객체를 반복(iterate)하는 제너레이터 함수를 만들 수 있습니다.
이 방식으로, 파일 전체를 메모리에 먼저 읽어들일 필요 없이, 제너레이터 함수를 `StreamingResponse`에 전달하여 반환할 수 있습니다.
이 방식은 클라우드 스토리지, 비디오 처리 등의 다양한 라이브러리와 함께 사용할 수 있습니다.
-{* ../../docs_src/custom_response/tutorial008.py hl[2,10:12,14] *}
+{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *}
1. 이것이 제너레이터 함수입니다. `yield` 문을 포함하고 있으므로 "제너레이터 함수"입니다.
2. `with` 블록을 사용함으로써, 제너레이터 함수가 완료된 후 파일과 같은 객체가 닫히도록 합니다. 즉, 응답 전송이 끝난 후 닫힙니다.
@@ -235,15 +235,15 @@ HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 30
이렇게 하면 "생성(generating)" 작업을 내부적으로 다른 무언가에 위임하는 제너레이터 함수가 됩니다.
- 이 방식을 사용하면 `with` 블록 안에서 파일을 열 수 있어, 작업이 완료된 후 파일과 같은 객체가 닫히는 것을 보장할 수 있습니다.
+ 이 방식을 사용하면 `with` 블록 안에서 파일을 열 수 있어, 작업이 완료된 후 파일과 같은 객체가 닫히는 것을 보장할 수 있습니다.
/// tip | 팁
-여기서 표준 `open()`을 사용하고 있기 때문에 `async`와 `await`를 지원하지 않습니다. 따라서 경로 작업은 일반 `def`로 선언합니다.
+여기서 표준 `open()`을 사용하고 있기 때문에 `async`와 `await`를 지원하지 않습니다. 따라서 경로 처리는 일반 `def`로 선언합니다.
///
-### `FileResponse`
+### `FileResponse` { #fileresponse }
파일을 비동기로 스트리밍하여 응답합니다.
@@ -256,25 +256,25 @@ HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 30
파일 응답에는 적절한 `Content-Length`, `Last-Modified`, 및 `ETag` 헤더가 포함됩니다.
-{* ../../docs_src/custom_response/tutorial009.py hl[2,10] *}
+{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *}
또한 `response_class` 매개변수를 사용할 수도 있습니다:
-{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *}
-이 경우, 경로 작업 함수에서 파일 경로를 직접 반환할 수 있습니다.
+이 경우, 경로 처리 함수에서 파일 경로를 직접 반환할 수 있습니다.
-## 사용자 정의 응답 클래스
+## 사용자 정의 응답 클래스 { #custom-response-class }
`Response`를 상속받아 사용자 정의 응답 클래스를 생성하고 사용할 수 있습니다.
-예를 들어, 포함된 `ORJSONResponse` 클래스에서 사용되지 않는 설정으로 orjson을 사용하고 싶다고 가정해봅시다.
+예를 들어, 포함된 `ORJSONResponse` 클래스에서 사용되지 않는 설정으로 `orjson`을 사용하고 싶다고 가정해봅시다.
만약 들여쓰기 및 포맷된 JSON을 반환하고 싶다면, `orjson.OPT_INDENT_2` 옵션을 사용할 수 있습니다.
`CustomORJSONResponse`를 생성할 수 있습니다. 여기서 핵심은 `Response.render(content)` 메서드를 생성하여 내용을 `bytes`로 반환하는 것입니다:
-{* ../../docs_src/custom_response/tutorial009c.py hl[9:14,17] *}
+{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *}
이제 다음 대신:
@@ -282,7 +282,7 @@ HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 30
{"message": "Hello World"}
```
-이 응답은 이렇게 반환됩니다:
+...이 응답은 이렇게 반환됩니다:
```json
{
@@ -292,22 +292,22 @@ HTTP 리디렉션 응답을 반환합니다. 기본적으로 상태 코드는 30
물론 JSON 포맷팅보다 더 유용하게 활용할 방법을 찾을 수 있을 것입니다. 😉
-## 기본 응답 클래스
+## 기본 응답 클래스 { #default-response-class }
**FastAPI** 클래스 객체 또는 `APIRouter`를 생성할 때 기본적으로 사용할 응답 클래스를 지정할 수 있습니다.
이를 정의하는 매개변수는 `default_response_class`입니다.
-아래 예제에서 **FastAPI**는 모든 경로 작업에서 기본적으로 `JSONResponse` 대신 `ORJSONResponse`를 사용합니다.
+아래 예제에서 **FastAPI**는 모든 *경로 처리*에서 기본적으로 `JSONResponse` 대신 `ORJSONResponse`를 사용합니다.
-{* ../../docs_src/custom_response/tutorial010.py hl[2,4] *}
+{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *}
/// tip | 팁
-여전히 이전처럼 *경로 작업*에서 `response_class`를 재정의할 수 있습니다.
+여전히 이전처럼 *경로 처리*에서 `response_class`를 재정의할 수 있습니다.
///
-## 추가 문서화
+## 추가 문서화 { #additional-documentation }
OpenAPI에서 `responses`를 사용하여 미디어 타입 및 기타 세부 정보를 선언할 수도 있습니다: [OpenAPI에서 추가 응답](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/ko/docs/advanced/dataclasses.md b/docs/ko/docs/advanced/dataclasses.md
new file mode 100644
index 000000000..92ad5545b
--- /dev/null
+++ b/docs/ko/docs/advanced/dataclasses.md
@@ -0,0 +1,95 @@
+# Dataclasses 사용하기 { #using-dataclasses }
+
+FastAPI는 **Pydantic** 위에 구축되어 있으며, 지금까지는 Pydantic 모델을 사용해 요청과 응답을 선언하는 방법을 보여드렸습니다.
+
+하지만 FastAPI는 `dataclasses`도 같은 방식으로 사용하는 것을 지원합니다:
+
+{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
+
+이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 `dataclasses`에 대한 내부 지원을 제공하기 때문입니다.
+
+따라서 위 코드처럼 Pydantic을 명시적으로 사용하지 않더라도, FastAPI는 Pydantic을 사용해 표준 dataclasses를 Pydantic의 dataclasses 변형으로 변환합니다.
+
+그리고 물론 다음과 같은 기능도 동일하게 지원합니다:
+
+* 데이터 검증
+* 데이터 직렬화
+* 데이터 문서화 등
+
+이는 Pydantic 모델을 사용할 때와 같은 방식으로 동작합니다. 그리고 실제로도 내부적으로는 Pydantic을 사용해 같은 방식으로 구현됩니다.
+
+/// info | 정보
+
+dataclasses는 Pydantic 모델이 할 수 있는 모든 것을 할 수는 없다는 점을 기억하세요.
+
+그래서 여전히 Pydantic 모델을 사용해야 할 수도 있습니다.
+
+하지만 이미 여러 dataclasses를 가지고 있다면, 이것은 FastAPI로 웹 API를 구동하는 데 그것들을 활용할 수 있는 좋은 방법입니다. 🤓
+
+///
+
+## `response_model`에서 Dataclasses 사용하기 { #dataclasses-in-response-model }
+
+`response_model` 매개변수에서도 `dataclasses`를 사용할 수 있습니다:
+
+{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}
+
+dataclass는 자동으로 Pydantic dataclass로 변환됩니다.
+
+이렇게 하면 해당 스키마가 API docs 사용자 인터페이스에 표시됩니다:
+
+
+
+## 중첩 데이터 구조에서 Dataclasses 사용하기 { #dataclasses-in-nested-data-structures }
+
+`dataclasses`를 다른 타입 애너테이션과 조합해 중첩 데이터 구조를 만들 수도 있습니다.
+
+일부 경우에는 Pydantic 버전의 `dataclasses`를 사용해야 할 수도 있습니다. 예를 들어 자동 생성된 API 문서에서 오류가 발생하는 경우입니다.
+
+그런 경우 표준 `dataclasses`를 드롭인 대체재인 `pydantic.dataclasses`로 간단히 바꾸면 됩니다:
+
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
+
+1. 표준 `dataclasses`에서 `field`를 계속 임포트합니다.
+
+2. `pydantic.dataclasses`는 `dataclasses`의 드롭인 대체재입니다.
+
+3. `Author` dataclass에는 `Item` dataclasses의 리스트가 포함됩니다.
+
+4. `Author` dataclass가 `response_model` 매개변수로 사용됩니다.
+
+5. 요청 본문으로 dataclasses와 함께 다른 표준 타입 애너테이션을 사용할 수 있습니다.
+
+ 이 경우에는 `Item` dataclasses의 리스트입니다.
+
+6. 여기서는 dataclasses 리스트인 `items`를 포함하는 딕셔너리를 반환합니다.
+
+ FastAPI는 여전히 데이터를 JSON으로 serializing할 수 있습니다.
+
+7. 여기서 `response_model`은 `Author` dataclasses 리스트에 대한 타입 애너테이션을 사용합니다.
+
+ 다시 말해, `dataclasses`를 표준 타입 애너테이션과 조합할 수 있습니다.
+
+8. 이 *경로 처리 함수*는 `async def` 대신 일반 `def`를 사용하고 있다는 점에 주목하세요.
+
+ 언제나처럼 FastAPI에서는 필요에 따라 `def`와 `async def`를 조합해 사용할 수 있습니다.
+
+ 어떤 것을 언제 사용해야 하는지 다시 확인하고 싶다면, [`async`와 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 문서의 _"급하신가요?"_ 섹션을 확인하세요.
+
+9. 이 *경로 처리 함수*는 dataclasses를(물론 반환할 수도 있지만) 반환하지 않고, 내부 데이터를 담은 딕셔너리들의 리스트를 반환합니다.
+
+ FastAPI는 `response_model` 매개변수(dataclasses 포함)를 사용해 응답을 변환합니다.
+
+`dataclasses`는 다른 타입 애너테이션과 매우 다양한 조합으로 결합해 복잡한 데이터 구조를 구성할 수 있습니다.
+
+더 구체적인 내용은 위 코드 내 애너테이션 팁을 확인하세요.
+
+## 더 알아보기 { #learn-more }
+
+`dataclasses`를 다른 Pydantic 모델과 조합하거나, 이를 상속하거나, 여러분의 모델에 포함하는 등의 작업도 할 수 있습니다.
+
+자세한 내용은 dataclasses에 관한 Pydantic 문서를 참고하세요.
+
+## 버전 { #version }
+
+이 기능은 FastAPI `0.67.0` 버전부터 사용할 수 있습니다. 🔖
diff --git a/docs/ko/docs/advanced/events.md b/docs/ko/docs/advanced/events.md
index 5f8fe0f1e..35223eaf3 100644
--- a/docs/ko/docs/advanced/events.md
+++ b/docs/ko/docs/advanced/events.md
@@ -1,67 +1,66 @@
-# Lifespan 이벤트
+# Lifespan 이벤트 { #lifespan-events }
-애플리케이션 **시작 전**에 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이는 이 코드가 **한 번**만 실행되며, **애플리케이션이 요청을 받기 시작하기 전**에 실행된다는 의미입니다.
+애플리케이션이 **시작**하기 전에 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이는 이 코드가 **한 번**만 실행되며, 애플리케이션이 **요청을 받기 시작하기 전**에 실행된다는 의미입니다.
-마찬가지로, 애플리케이션이 **종료될 때** 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이 경우, 이 코드는 **한 번**만 실행되며, **여러 요청을 처리한 후**에 실행됩니다.
+마찬가지로, 애플리케이션이 **종료**될 때 실행되어야 하는 로직(코드)을 정의할 수 있습니다. 이 경우, 이 코드는 **한 번**만 실행되며, **여러 요청을 처리한 후**에 실행됩니다.
-이 코드가 애플리케이션이 **요청을 받기 시작하기 전에** 실행되고, 요청 처리가 끝난 후 **종료 직전에** 실행되기 때문에 전체 애플리케이션의 **수명(Lifespan)**을 다룹니다. (잠시 후 "수명"이라는 단어가 중요해집니다 😉)
+이 코드는 애플리케이션이 요청을 받기 **시작**하기 전에 실행되고, 요청 처리를 **끝낸 직후**에 실행되기 때문에 전체 애플리케이션의 **수명(lifespan)**을 다룹니다(잠시 후 "lifespan"이라는 단어가 중요해집니다 😉).
-이 방법은 전체 애플리케이션에서 사용해야 하는 **자원**을 설정하거나 요청 간에 **공유되는** 자원을 설정하고, 또는 그 후에 **정리**하는 데 매우 유용할 수 있습니다. 예를 들어, 데이터베이스 연결 풀 또는 공유되는 머신러닝 모델을 로드하는 경우입니다.
+이는 전체 앱에서 사용해야 하는 **자원**을 설정하고, 요청 간에 **공유되는** 자원을 설정하고, 그리고/또는 이후에 **정리**하는 데 매우 유용할 수 있습니다. 예를 들어, 데이터베이스 연결 풀 또는 공유 머신러닝 모델을 로드하는 경우입니다.
+## 사용 사례 { #use-case }
-## 사용 사례
+먼저 **사용 사례** 예시로 시작한 다음, 이를 어떻게 해결할지 살펴보겠습니다.
-먼저 **사용 사례**를 예로 들어보고, 이를 어떻게 해결할 수 있는지 살펴보겠습니다.
+요청을 처리하는 데 사용하고 싶은 **머신러닝 모델**이 있다고 상상해 봅시다. 🤖
-우리가 요청을 처리하기 위해 사용하고 싶은 **머신러닝 모델**이 있다고 상상해 봅시다. 🤖
+동일한 모델이 요청 간에 공유되므로, 요청마다 모델이 하나씩 있거나 사용자마다 하나씩 있는 등의 방식이 아닙니다.
-이 모델들은 요청 간에 공유되므로, 요청마다 모델이 하나씩 있는 것이 아니라, 여러 요청에서 동일한 모델을 사용합니다.
+모델을 로드하는 데 **상당한 시간이 걸린다고 상상해 봅시다**, 왜냐하면 모델이 **디스크에서 많은 데이터를 읽어야** 하기 때문입니다. 그래서 모든 요청마다 이를 수행하고 싶지는 않습니다.
-모델을 로드하는 데 **상당한 시간이 걸린다고 상상해 봅시다**, 왜냐하면 모델이 **디스크에서 많은 데이터를 읽어야** 하기 때문입니다. 따라서 모든 요청에 대해 모델을 매번 로드하고 싶지 않습니다.
+모듈/파일의 최상위에서 로드할 수도 있지만, 그러면 단순한 자동화된 테스트를 실행하는 경우에도 **모델을 로드**하게 되고, 테스트가 코드의 독립적인 부분을 실행하기 전에 모델이 로드될 때까지 기다려야 하므로 **느려집니다**.
-모듈/파일의 최상위에서 모델을 로드할 수도 있지만, 그러면 **모델을 로드하는데** 시간이 걸리기 때문에, 단순한 자동화된 테스트를 실행할 때도 모델이 로드될 때까지 기다려야 해서 **테스트 속도가 느려집니다**.
+이것이 우리가 해결할 문제입니다. 요청을 처리하기 전에 모델을 로드하되, 코드가 로드되는 동안이 아니라 애플리케이션이 요청을 받기 시작하기 직전에만 로드하겠습니다.
-이 문제를 해결하려고 하는 것입니다. 요청을 처리하기 전에 모델을 로드하되, 애플리케이션이 요청을 받기 시작하기 직전에만 로드하고, 코드가 로드되는 동안은 로드하지 않도록 하겠습니다.
+## Lifespan { #lifespan }
-## Lifespan
+`FastAPI` 앱의 `lifespan` 매개변수와 "컨텍스트 매니저"를 사용하여 *시작*과 *종료* 로직을 정의할 수 있습니다(컨텍스트 매니저가 무엇인지 잠시 후에 보여드리겠습니다).
-`FastAPI` 애플리케이션의 `lifespan` 매개변수와 "컨텍스트 매니저"를 사용하여 *시작*과 *종료* 로직을 정의할 수 있습니다. (컨텍스트 매니저가 무엇인지 잠시 후에 설명드리겠습니다.)
+예제로 시작한 다음 자세히 살펴보겠습니다.
-예제를 통해 시작하고, 그 후에 자세히 살펴보겠습니다.
+`yield`를 사용해 비동기 함수 `lifespan()`을 다음과 같이 생성합니다:
-우리는 `yield`를 사용하여 비동기 함수 `lifespan()`을 다음과 같이 생성합니다:
+{* ../../docs_src/events/tutorial003_py39.py hl[16,19] *}
-{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+여기서는 `yield` 이전에 (가짜) 모델 함수를 머신러닝 모델이 들어 있는 딕셔너리에 넣어 모델을 로드하는 비용이 큰 *시작* 작업을 시뮬레이션합니다. 이 코드는 애플리케이션이 **요청을 받기 시작하기 전**, *시작* 동안에 실행됩니다.
-여기서 우리는 모델을 로드하는 비싼 *시작* 작업을 시뮬레이션하고 있습니다. `yield` 앞에서 (가짜) 모델 함수를 머신러닝 모델이 담긴 딕셔너리에 넣습니다. 이 코드는 **애플리케이션이 요청을 받기 시작하기 전**, *시작* 동안에 실행됩니다.
-
-그리고 `yield` 직후에는 모델을 언로드합니다. 이 코드는 **애플리케이션이 요청 처리 완료 후**, *종료* 직전에 실행됩니다. 예를 들어, 메모리나 GPU와 같은 자원을 해제하는 작업을 할 수 있습니다.
+그리고 `yield` 직후에는 모델을 언로드합니다. 이 코드는 애플리케이션이 **요청 처리를 마친 후**, *종료* 직전에 실행됩니다. 예를 들어 메모리나 GPU 같은 자원을 해제할 수 있습니다.
/// tip | 팁
-`shutdown`은 애플리케이션을 **종료**할 때 발생합니다.
+`shutdown`은 애플리케이션을 **중지**할 때 발생합니다.
-새로운 버전을 시작해야 하거나, 그냥 실행을 멈추고 싶을 수도 있습니다. 🤷
+새 버전을 시작해야 할 수도 있고, 그냥 실행하는 게 지겨워졌을 수도 있습니다. 🤷
///
-### Lifespan 함수
+### Lifespan 함수 { #lifespan-function }
-먼저 주목할 점은, `yield`를 사용하여 비동기 함수(async function)를 정의하고 있다는 것입니다. 이는 `yield`를 사용한 의존성과 매우 유사합니다.
+먼저 주목할 점은 `yield`를 사용하여 비동기 함수를 정의하고 있다는 것입니다. 이는 `yield`를 사용하는 의존성과 매우 유사합니다.
-{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[14:19] *}
함수의 첫 번째 부분, 즉 `yield` 이전의 코드는 애플리케이션이 시작되기 **전에** 실행됩니다.
-그리고 `yield` 이후의 부분은 애플리케이션이 완료된 후 **나중에** 실행됩니다.
+그리고 `yield` 이후의 부분은 애플리케이션이 종료된 **후에** 실행됩니다.
-### 비동기 컨텍스트 매니저
+### 비동기 컨텍스트 매니저 { #async-context-manager }
-함수를 확인해보면, `@asynccontextmanager`로 장식되어 있습니다.
+확인해 보면, 함수는 `@asynccontextmanager`로 데코레이션되어 있습니다.
-이것은 함수를 "**비동기 컨텍스트 매니저**"라고 불리는 것으로 변환시킵니다.
+이는 함수를 "**비동기 컨텍스트 매니저**"라고 불리는 것으로 변환합니다.
-{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[1,13] *}
파이썬에서 **컨텍스트 매니저**는 `with` 문에서 사용할 수 있는 것입니다. 예를 들어, `open()`은 컨텍스트 매니저로 사용할 수 있습니다:
@@ -69,97 +68,98 @@
with open("file.txt") as file:
file.read()
```
-최근 버전의 파이썬에서는 **비동기 컨텍스트 매니저**도 있습니다. 이를 `async with`와 함께 사용합니다:
+
+최근 버전의 파이썬에는 **비동기 컨텍스트 매니저**도 있습니다. 이를 `async with`와 함께 사용합니다:
```Python
async with lifespan(app):
await do_stuff()
```
-컨텍스트 매니저나 위와 같은 비동기 컨텍스트 매니저를 만들면, `with` 블록에 들어가기 전에 `yield` 이전의 코드가 실행되고, `with` 블록을 벗어난 후에는 `yield` 이후의 코드가 실행됩니다.
+위와 같은 컨텍스트 매니저 또는 비동기 컨텍스트 매니저를 만들면, `with` 블록에 들어가기 전에 `yield` 이전의 코드를 실행하고, `with` 블록을 벗어난 후에는 `yield` 이후의 코드를 실행합니다.
-위의 코드 예제에서는 직접 사용하지 않고, FastAPI에 전달하여 사용하도록 합니다.
+위의 코드 예제에서는 직접 사용하지 않고, FastAPI에 전달하여 FastAPI가 이를 사용하도록 합니다.
-`FastAPI` 애플리케이션의 `lifespan` 매개변수는 **비동기 컨텍스트 매니저**를 받기 때문에, 새로운 `lifespan` 비동기 컨텍스트 매니저를 FastAPI에 전달할 수 있습니다.
+`FastAPI` 앱의 `lifespan` 매개변수는 **비동기 컨텍스트 매니저**를 받으므로, 새 `lifespan` 비동기 컨텍스트 매니저를 전달할 수 있습니다.
-{* ../../docs_src/events/tutorial003.py hl[22] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[22] *}
-## 대체 이벤트 (사용 중단)
+## 대체 이벤트(사용 중단) { #alternative-events-deprecated }
/// warning | 경고
-*시작*과 *종료*를 처리하는 권장 방법은 위에서 설명한 대로 `FastAPI` 애플리케이션의 `lifespan` 매개변수를 사용하는 것입니다. `lifespan` 매개변수를 제공하면 `startup`과 `shutdown` 이벤트 핸들러는 더 이상 호출되지 않습니다. `lifespan`을 사용할지, 모든 이벤트를 사용할지 선택해야 하며 둘 다 사용할 수는 없습니다.
+*시작*과 *종료*를 처리하는 권장 방법은 위에서 설명한 대로 `FastAPI` 앱의 `lifespan` 매개변수를 사용하는 것입니다. `lifespan` 매개변수를 제공하면 `startup`과 `shutdown` 이벤트 핸들러는 더 이상 호출되지 않습니다. `lifespan`만 쓰거나 이벤트만 쓰거나 둘 중 하나이지, 둘 다는 아닙니다.
-이 부분은 건너뛰셔도 좋습니다.
+이 부분은 아마 건너뛰셔도 됩니다.
///
*시작*과 *종료* 동안 실행될 이 로직을 정의하는 대체 방법이 있습니다.
-애플리케이션이 시작되기 전에 또는 종료될 때 실행해야 하는 이벤트 핸들러(함수)를 정의할 수 있습니다.
+애플리케이션이 시작되기 전에 또는 애플리케이션이 종료될 때 실행되어야 하는 이벤트 핸들러(함수)를 정의할 수 있습니다.
이 함수들은 `async def` 또는 일반 `def`로 선언할 수 있습니다.
-### `startup` 이벤트
+### `startup` 이벤트 { #startup-event }
애플리케이션이 시작되기 전에 실행되어야 하는 함수를 추가하려면, `"startup"` 이벤트로 선언합니다:
-{* ../../docs_src/events/tutorial001.py hl[8] *}
+{* ../../docs_src/events/tutorial001_py39.py hl[8] *}
-이 경우, `startup` 이벤트 핸들러 함수는 "database"라는 항목(단지 `dict`)을 일부 값으로 초기화합니다.
+이 경우, `startup` 이벤트 핸들러 함수는 "database"(그냥 `dict`) 항목을 일부 값으로 초기화합니다.
여러 개의 이벤트 핸들러 함수를 추가할 수 있습니다.
-애플리케이션은 모든 `startup` 이벤트 핸들러가 완료될 때까지 요청을 받기 시작하지 않습니다.
+그리고 모든 `startup` 이벤트 핸들러가 완료될 때까지 애플리케이션은 요청을 받기 시작하지 않습니다.
-### `shutdown` 이벤트
+### `shutdown` 이벤트 { #shutdown-event }
애플리케이션이 종료될 때 실행되어야 하는 함수를 추가하려면, `"shutdown"` 이벤트로 선언합니다:
-{* ../../docs_src/events/tutorial002.py hl[6] *}
+{* ../../docs_src/events/tutorial002_py39.py hl[6] *}
-여기서, `shutdown` 이벤트 핸들러 함수는 `"Application shutdown"`이라는 텍스트를 `log.txt` 파일에 기록합니다.
+여기서 `shutdown` 이벤트 핸들러 함수는 텍스트 한 줄 `"Application shutdown"`을 `log.txt` 파일에 기록합니다.
/// info | 정보
-`open()` 함수에서 `mode="a"`는 "추가"를 의미하므로, 파일에 있는 기존 내용은 덮어쓰지 않고 새로운 줄이 추가됩니다.
+`open()` 함수에서 `mode="a"`는 "append"(추가)를 의미하므로, 기존 내용을 덮어쓰지 않고 파일에 있던 내용 뒤에 줄이 추가됩니다.
///
/// tip | 팁
-이 경우, 우리는 표준 파이썬 `open()` 함수를 사용하여 파일과 상호작용하고 있습니다.
+이 경우에는 파일과 상호작용하는 표준 파이썬 `open()` 함수를 사용하고 있습니다.
-따라서 I/O(입출력) 작업이 포함되어 있어 디스크에 기록되는 것을 "기다리는" 과정이 필요합니다.
+따라서 I/O(input/output)가 포함되어 있어 디스크에 기록되는 것을 "기다리는" 과정이 필요합니다.
하지만 `open()`은 `async`와 `await`를 사용하지 않습니다.
-그래서 우리는 이벤트 핸들러 함수를 `async def` 대신 일반 `def`로 선언합니다.
+그래서 이벤트 핸들러 함수는 `async def` 대신 표준 `def`로 선언합니다.
///
-### `startup`과 `shutdown`을 함께 사용
+### `startup`과 `shutdown`을 함께 { #startup-and-shutdown-together }
-*시작*과 *종료* 로직이 연결될 가능성이 높습니다. 예를 들어, 무언가를 시작한 후 끝내거나, 자원을 획득한 후 해제하는 등의 작업을 할 수 있습니다.
+*시작*과 *종료* 로직은 연결되어 있을 가능성이 높습니다. 무언가를 시작했다가 끝내거나, 자원을 획득했다가 해제하는 등의 작업이 필요할 수 있습니다.
-이러한 작업을 별도의 함수로 처리하면 서로 로직이나 변수를 공유하지 않기 때문에 더 어려워집니다. 값들을 전역 변수에 저장하거나 비슷한 트릭을 사용해야 할 수 있습니다.
+로직이나 변수를 함께 공유하지 않는 분리된 함수에서 이를 처리하면, 전역 변수에 값을 저장하거나 비슷한 트릭이 필요해져 더 어렵습니다.
-그렇기 때문에 위에서 설명한 대로 `lifespan`을 사용하는 것이 권장됩니다.
+그 때문에, 이제는 위에서 설명한 대로 `lifespan`을 사용하는 것이 권장됩니다.
-## 기술적 세부사항
+## 기술적 세부사항 { #technical-details }
호기심 많은 분들을 위한 기술적인 세부사항입니다. 🤓
-ASGI 기술 사양에 따르면, 이는 Lifespan Protocol의 일부이며, `startup`과 `shutdown`이라는 이벤트를 정의합니다.
+내부적으로 ASGI 기술 사양에서는 이것이 Lifespan Protocol의 일부이며, `startup`과 `shutdown`이라는 이벤트를 정의합니다.
/// info | 정보
-Starlette의 `lifespan` 핸들러에 대해 더 읽고 싶다면 Starlette의 Lifespan 문서에서 확인할 수 있습니다.
+Starlette `lifespan` 핸들러에 대해서는 Starlette의 Lifespan 문서에서 더 읽어볼 수 있습니다.
-이 문서에는 코드의 다른 영역에서 사용할 수 있는 lifespan 상태를 처리하는 방법도 포함되어 있습니다.
+또한 코드의 다른 영역에서 사용할 수 있는 lifespan 상태를 처리하는 방법도 포함되어 있습니다.
///
-## 서브 애플리케이션
+## 서브 애플리케이션 { #sub-applications }
-🚨 이 lifespan 이벤트(`startup`과 `shutdown`)는 메인 애플리케이션에 대해서만 실행되며, [서브 애플리케이션 - Mounts](sub-applications.md){.internal-link target=_blank}에는 실행되지 않음을 유의하세요.
+🚨 이 lifespan 이벤트(startup 및 shutdown)는 메인 애플리케이션에 대해서만 실행되며, [서브 애플리케이션 - Mounts](sub-applications.md){.internal-link target=_blank}에는 실행되지 않음을 유의하세요.
diff --git a/docs/ko/docs/advanced/generate-clients.md b/docs/ko/docs/advanced/generate-clients.md
new file mode 100644
index 000000000..1def3efe1
--- /dev/null
+++ b/docs/ko/docs/advanced/generate-clients.md
@@ -0,0 +1,208 @@
+# SDK 생성하기 { #generating-sdks }
+
+**FastAPI**는 **OpenAPI** 사양을 기반으로 하므로, FastAPI의 API는 많은 도구가 이해할 수 있는 표준 형식으로 설명할 수 있습니다.
+
+덕분에 여러 언어용 클라이언트 라이브러리(**SDKs**), 최신 **문서**, 그리고 코드와 동기화된 **테스트** 또는 **자동화 워크플로**를 쉽게 생성할 수 있습니다.
+
+이 가이드에서는 FastAPI 백엔드용 **TypeScript SDK**를 생성하는 방법을 배웁니다.
+
+## 오픈 소스 SDK 생성기 { #open-source-sdk-generators }
+
+다양하게 활용할 수 있는 옵션으로 OpenAPI Generator가 있으며, **다양한 프로그래밍 언어**를 지원하고 OpenAPI 사양으로부터 SDK를 생성할 수 있습니다.
+
+**TypeScript 클라이언트**의 경우 Hey API는 TypeScript 생태계에 최적화된 경험을 제공하는 목적에 맞게 설계된 솔루션입니다.
+
+더 많은 SDK 생성기는 OpenAPI.Tools에서 확인할 수 있습니다.
+
+/// tip | 팁
+
+FastAPI는 **OpenAPI 3.1** 사양을 자동으로 생성하므로, 사용하는 도구는 이 버전을 지원해야 합니다.
+
+///
+
+## FastAPI 스폰서의 SDK 생성기 { #sdk-generators-from-fastapi-sponsors }
+
+이 섹션에서는 FastAPI를 후원하는 회사들이 제공하는 **벤처 투자 기반** 및 **기업 지원** 솔루션을 소개합니다. 이 제품들은 고품질로 생성된 SDK에 더해 **추가 기능**과 **통합**을 제공합니다.
+
+✨ [**FastAPI 후원하기**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨를 통해, 이 회사들은 프레임워크와 그 **생태계**가 건강하고 **지속 가능**하게 유지되도록 돕습니다.
+
+또한 이들의 후원은 FastAPI **커뮤니티**(여러분)에 대한 강한 헌신을 보여주며, **좋은 서비스**를 제공하는 것뿐 아니라, 견고하고 활발한 프레임워크인 FastAPI를 지원하는 데에도 관심이 있음을 나타냅니다. 🙇
+
+예를 들어 다음을 사용해 볼 수 있습니다:
+
+* Speakeasy
+* Stainless
+* liblab
+
+이 중 일부는 오픈 소스이거나 무료 티어를 제공하므로, 비용 부담 없이 사용해 볼 수 있습니다. 다른 상용 SDK 생성기도 있으며 온라인에서 찾을 수 있습니다. 🤓
+
+## TypeScript SDK 만들기 { #create-a-typescript-sdk }
+
+간단한 FastAPI 애플리케이션으로 시작해 보겠습니다:
+
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
+
+*path operation*에서 요청 페이로드와 응답 페이로드에 사용하는 모델을 `Item`, `ResponseMessage` 모델로 정의하고 있다는 점에 주목하세요.
+
+### API 문서 { #api-docs }
+
+`/docs`로 이동하면, 요청으로 보낼 데이터와 응답으로 받을 데이터에 대한 **스키마(schemas)**가 있는 것을 볼 수 있습니다:
+
+
+
+이 스키마는 앱에서 모델로 선언되었기 때문에 볼 수 있습니다.
+
+그 정보는 앱의 **OpenAPI 스키마**에서 사용할 수 있고, 이후 API 문서에 표시됩니다.
+
+OpenAPI에 포함된 모델의 동일한 정보가 **클라이언트 코드 생성**에 사용될 수 있습니다.
+
+### Hey API { #hey-api }
+
+모델이 포함된 FastAPI 앱이 준비되면, Hey API를 사용해 TypeScript 클라이언트를 생성할 수 있습니다. 가장 빠른 방법은 npx를 사용하는 것입니다.
+
+```sh
+npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client
+```
+
+이 명령은 `./src/client`에 TypeScript SDK를 생성합니다.
+
+`@hey-api/openapi-ts` 설치 방법과 생성된 결과물은 해당 웹사이트에서 확인할 수 있습니다.
+
+### SDK 사용하기 { #using-the-sdk }
+
+이제 클라이언트 코드를 import해서 사용할 수 있습니다. 아래처럼 사용할 수 있으며, 메서드에 대한 자동 완성이 제공되는 것을 확인할 수 있습니다:
+
+
+
+보낼 페이로드에 대해서도 자동 완성이 제공됩니다:
+
+
+
+/// tip | 팁
+
+`name`과 `price`에 대한 자동 완성은 FastAPI 애플리케이션에서 `Item` 모델에 정의된 내용입니다.
+
+///
+
+전송하는 데이터에 대해 인라인 오류도 표시됩니다:
+
+
+
+응답 객체도 자동 완성을 제공합니다:
+
+
+
+## 태그가 있는 FastAPI 앱 { #fastapi-app-with-tags }
+
+대부분의 경우 FastAPI 앱은 더 커지고, 서로 다른 *path operations* 그룹을 분리하기 위해 태그를 사용하게 될 가능성이 큽니다.
+
+예를 들어 **items** 섹션과 **users** 섹션이 있고, 이를 태그로 분리할 수 있습니다:
+
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
+
+### 태그로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-tags }
+
+태그를 사용하는 FastAPI 앱에 대해 클라이언트를 생성하면, 일반적으로 생성된 클라이언트 코드도 태그를 기준으로 분리됩니다.
+
+이렇게 하면 클라이언트 코드에서 항목들이 올바르게 정렬되고 그룹화됩니다:
+
+
+
+이 경우 다음이 있습니다:
+
+* `ItemsService`
+* `UsersService`
+
+### 클라이언트 메서드 이름 { #client-method-names }
+
+현재 `createItemItemsPost` 같은 생성된 메서드 이름은 그다지 깔끔하지 않습니다:
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...이는 클라이언트 생성기가 각 *path operation*에 대해 OpenAPI 내부의 **operation ID**를 사용하기 때문입니다.
+
+OpenAPI는 모든 *path operations* 전체에서 operation ID가 각각 유일해야 한다고 요구합니다. 그래서 FastAPI는 operation ID가 유일하도록 **함수 이름**, **경로**, **HTTP method/operation**을 조합해 operation ID를 생성합니다.
+
+하지만 다음에서 이를 개선하는 방법을 보여드리겠습니다. 🤓
+
+## 커스텀 Operation ID와 더 나은 메서드 이름 { #custom-operation-ids-and-better-method-names }
+
+클라이언트에서 **더 단순한 메서드 이름**을 갖도록, operation ID가 **생성되는 방식**을 **수정**할 수 있습니다.
+
+이 경우 operation ID가 다른 방식으로도 **유일**하도록 보장해야 합니다.
+
+예를 들어 각 *path operation*이 태그를 갖도록 한 다음, **태그**와 *path operation* **이름**(함수 이름)을 기반으로 operation ID를 생성할 수 있습니다.
+
+### 유일 ID 생성 함수 커스터마이징 { #custom-generate-unique-id-function }
+
+FastAPI는 각 *path operation*에 대해 **유일 ID**를 사용하며, 이는 **operation ID** 및 요청/응답에 필요한 커스텀 모델 이름에도 사용됩니다.
+
+이 함수를 커스터마이징할 수 있습니다. 이 함수는 `APIRoute`를 받아 문자열을 반환합니다.
+
+예를 들어 아래에서는 첫 번째 태그(대부분 태그는 하나만 있을 것입니다)와 *path operation* 이름(함수 이름)을 사용합니다.
+
+그 다음 이 커스텀 함수를 `generate_unique_id_function` 매개변수로 **FastAPI**에 전달할 수 있습니다:
+
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
+
+### 커스텀 Operation ID로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-custom-operation-ids }
+
+이제 클라이언트를 다시 생성하면, 개선된 메서드 이름을 확인할 수 있습니다:
+
+
+
+보시다시피, 이제 메서드 이름은 태그 다음에 함수 이름이 오며, URL 경로와 HTTP operation의 정보는 포함하지 않습니다.
+
+### 클라이언트 생성기를 위한 OpenAPI 사양 전처리 { #preprocess-the-openapi-specification-for-the-client-generator }
+
+생성된 코드에는 여전히 일부 **중복 정보**가 있습니다.
+
+`ItemsService`(태그에서 가져옴)에 이미 **items**가 포함되어 있어 이 메서드가 items와 관련되어 있음을 알 수 있지만, 메서드 이름에도 태그 이름이 접두사로 붙어 있습니다. 😕
+
+OpenAPI 전반에서는 operation ID가 **유일**하다는 것을 보장하기 위해 이 방식을 유지하고 싶을 수 있습니다.
+
+하지만 생성된 클라이언트에서는, 클라이언트를 생성하기 직전에 OpenAPI operation ID를 **수정**해서 메서드 이름을 더 보기 좋고 **깔끔하게** 만들 수 있습니다.
+
+OpenAPI JSON을 `openapi.json` 파일로 다운로드한 뒤, 아래와 같은 스크립트로 **접두사 태그를 제거**할 수 있습니다:
+
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
+
+////
+
+이렇게 하면 operation ID가 `items-get_items` 같은 형태에서 `get_items`로 변경되어, 클라이언트 생성기가 더 단순한 메서드 이름을 생성할 수 있습니다.
+
+### 전처리된 OpenAPI로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-the-preprocessed-openapi }
+
+이제 최종 결과가 `openapi.json` 파일에 있으므로, 입력 위치를 업데이트해야 합니다:
+
+```sh
+npx @hey-api/openapi-ts -i ./openapi.json -o src/client
+```
+
+새 클라이언트를 생성한 후에는 **깔끔한 메서드 이름**을 가지면서도, **자동 완성**, **인라인 오류** 등은 그대로 제공됩니다:
+
+
+
+## 장점 { #benefits }
+
+자동으로 생성된 클라이언트를 사용하면 다음에 대해 **자동 완성**을 받을 수 있습니다:
+
+* 메서드
+* 본문(body)의 요청 페이로드, 쿼리 파라미터 등
+* 응답 페이로드
+
+또한 모든 것에 대해 **인라인 오류**도 확인할 수 있습니다.
+
+그리고 백엔드 코드를 업데이트한 뒤 프론트엔드를 **재생성(regenerate)**하면, 새 *path operations*가 메서드로 추가되고 기존 것은 제거되며, 그 밖의 변경 사항도 생성된 코드에 반영됩니다. 🤓
+
+이는 무언가 변경되면 그 변경이 클라이언트 코드에도 자동으로 **반영**된다는 뜻입니다. 또한 클라이언트를 **빌드(build)**하면 사용된 데이터가 **불일치(mismatch)**할 경우 오류가 발생합니다.
+
+따라서 운영 환경에서 최종 사용자에게 오류가 노출된 뒤 문제를 추적하는 대신, 개발 사이클 초기에 **많은 오류를 매우 빨리 감지**할 수 있습니다. ✨
diff --git a/docs/ko/docs/advanced/index.md b/docs/ko/docs/advanced/index.md
index 31704727c..78ef5ffec 100644
--- a/docs/ko/docs/advanced/index.md
+++ b/docs/ko/docs/advanced/index.md
@@ -1,6 +1,6 @@
-# 심화 사용자 안내서 - 도입부
+# 심화 사용자 안내서 - 도입부 { #advanced-user-guide }
-## 추가 기능
+## 추가 기능 { #additional-features }
메인 [자습서 - 사용자 안내서](../tutorial/index.md){.internal-link target=_blank}는 여러분이 **FastAPI**의 모든 주요 기능을 둘러보시기에 충분할 것입니다.
@@ -14,14 +14,8 @@
///
-## 자습서를 먼저 읽으십시오
+## 자습서를 먼저 읽으십시오 { #read-the-tutorial-first }
여러분은 메인 [자습서 - 사용자 안내서](../tutorial/index.md){.internal-link target=_blank}의 지식으로 **FastAPI**의 대부분의 기능을 사용하실 수 있습니다.
이어지는 장들은 여러분이 메인 자습서 - 사용자 안내서를 이미 읽으셨으며 주요 아이디어를 알고 계신다고 가정합니다.
-
-## TestDriven.io 강좌
-
-여러분이 문서의 이 부분을 보완하시기 위해 심화-기초 강좌 수강을 희망하신다면 다음을 참고 하시기를 바랍니다: **TestDriven.io**의 FastAPI와 Docker를 사용한 테스트 주도 개발.
-
-그들은 현재 전체 수익의 10퍼센트를 **FastAPI** 개발에 기부하고 있습니다. 🎉 😄
diff --git a/docs/ko/docs/advanced/middleware.md b/docs/ko/docs/advanced/middleware.md
new file mode 100644
index 000000000..be2c972a6
--- /dev/null
+++ b/docs/ko/docs/advanced/middleware.md
@@ -0,0 +1,97 @@
+# 고급 Middleware { #advanced-middleware }
+
+메인 튜토리얼에서 애플리케이션에 [커스텀 Middleware](../tutorial/middleware.md){.internal-link target=_blank}를 추가하는 방법을 읽었습니다.
+
+그리고 [`CORSMiddleware`로 CORS 처리하기](../tutorial/cors.md){.internal-link target=_blank}도 읽었습니다.
+
+이 섹션에서는 다른 middleware들을 사용하는 방법을 살펴보겠습니다.
+
+## ASGI middleware 추가하기 { #adding-asgi-middlewares }
+
+**FastAPI**는 Starlette를 기반으로 하고 ASGI 사양을 구현하므로, 어떤 ASGI middleware든 사용할 수 있습니다.
+
+ASGI 사양을 따르기만 하면, FastAPI나 Starlette를 위해 만들어진 middleware가 아니어도 동작합니다.
+
+일반적으로 ASGI middleware는 첫 번째 인자로 ASGI 앱을 받도록 기대하는 클래스입니다.
+
+그래서 서드파티 ASGI middleware 문서에서는 아마 다음과 같이 하라고 안내할 것입니다:
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+하지만 FastAPI(정확히는 Starlette)는 더 간단한 방법을 제공하며, 이를 통해 내부 middleware가 서버 오류를 처리하고 커스텀 예외 핸들러가 올바르게 동작하도록 보장합니다.
+
+이를 위해(그리고 CORS 예제에서처럼) `app.add_middleware()`를 사용합니다.
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()`는 첫 번째 인자로 middleware 클래스를 받고, 그 뒤에는 middleware에 전달할 추가 인자들을 받습니다.
+
+## 통합 middleware { #integrated-middlewares }
+
+**FastAPI**에는 일반적인 사용 사례를 위한 여러 middleware가 포함되어 있습니다. 다음에서 이를 사용하는 방법을 살펴보겠습니다.
+
+/// note | 기술 세부사항
+
+다음 예제에서는 `from starlette.middleware.something import SomethingMiddleware`를 사용해도 됩니다.
+
+**FastAPI**는 개발자 편의를 위해 `fastapi.middleware`에 여러 middleware를 제공하지만, 사용 가능한 대부분의 middleware는 Starlette에서 직접 제공됩니다.
+
+///
+
+## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware }
+
+들어오는 모든 요청이 `https` 또는 `wss`여야 하도록 강제합니다.
+
+`http` 또는 `ws`로 들어오는 모든 요청은 대신 보안 스킴으로 리디렉션됩니다.
+
+{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *}
+
+## `TrustedHostMiddleware` { #trustedhostmiddleware }
+
+HTTP Host Header 공격을 방어하기 위해, 들어오는 모든 요청에 올바르게 설정된 `Host` 헤더가 있어야 하도록 강제합니다.
+
+{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *}
+
+다음 인자들을 지원합니다:
+
+* `allowed_hosts` - 호스트명으로 허용할 도메인 이름 목록입니다. `*.example.com` 같은 와일드카드 도메인으로 서브도메인을 매칭하는 것도 지원합니다. 어떤 호스트명이든 허용하려면 `allowed_hosts=["*"]`를 사용하거나 middleware를 생략하세요.
+* `www_redirect` - True로 설정하면, 허용된 호스트의 non-www 버전으로 들어오는 요청을 www 버전으로 리디렉션합니다. 기본값은 `True`입니다.
+
+들어오는 요청이 올바르게 검증되지 않으면 `400` 응답이 전송됩니다.
+
+## `GZipMiddleware` { #gzipmiddleware }
+
+`Accept-Encoding` 헤더에 `"gzip"`이 포함된 어떤 요청이든 GZip 응답을 처리합니다.
+
+이 middleware는 일반 응답과 스트리밍 응답을 모두 처리합니다.
+
+{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *}
+
+다음 인자들을 지원합니다:
+
+* `minimum_size` - 바이트 단위로 지정한 최소 크기보다 작은 응답은 GZip으로 압축하지 않습니다. 기본값은 `500`입니다.
+* `compresslevel` - GZip 압축 중에 사용됩니다. 1부터 9까지의 정수입니다. 기본값은 `9`입니다. 값이 낮을수록 압축은 더 빠르지만 파일 크기는 더 커지고, 값이 높을수록 압축은 더 느리지만 파일 크기는 더 작아집니다.
+
+## 다른 middleware { #other-middlewares }
+
+다른 ASGI middleware도 많이 있습니다.
+
+예를 들어:
+
+* Uvicorn의 `ProxyHeadersMiddleware`
+* MessagePack
+
+사용 가능한 다른 middleware를 보려면 Starlette의 Middleware 문서와 ASGI Awesome List를 확인하세요.
diff --git a/docs/ko/docs/advanced/middlewares.md b/docs/ko/docs/advanced/middlewares.md
deleted file mode 100644
index c00aedeaf..000000000
--- a/docs/ko/docs/advanced/middlewares.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# 고급 미들웨어
-
-메인 튜토리얼에서 [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/openapi-callbacks.md b/docs/ko/docs/advanced/openapi-callbacks.md
new file mode 100644
index 000000000..e4bdea9d6
--- /dev/null
+++ b/docs/ko/docs/advanced/openapi-callbacks.md
@@ -0,0 +1,186 @@
+# OpenAPI 콜백 { #openapi-callbacks }
+
+다른 사람이 만든 *external API*(아마도 당신의 API를 *사용*할 동일한 개발자)가 요청을 트리거하도록 만드는 *경로 처리*를 가진 API를 만들 수 있습니다.
+
+당신의 API 앱이 *external API*를 호출할 때 일어나는 과정을 "callback"이라고 합니다. 외부 개발자가 작성한 소프트웨어가 당신의 API로 요청을 보낸 다음, 당신의 API가 다시 *external API*로 요청을 보내 *되돌려 호출*하기 때문입니다(아마도 같은 개발자가 만든 API일 것입니다).
+
+이 경우, 그 *external API*가 어떤 형태여야 하는지 문서화하고 싶을 수 있습니다. 어떤 *경로 처리*를 가져야 하는지, 어떤 body를 기대하는지, 어떤 응답을 반환해야 하는지 등입니다.
+
+## 콜백이 있는 앱 { #an-app-with-callbacks }
+
+예시로 확인해 보겠습니다.
+
+청구서를 생성할 수 있는 앱을 개발한다고 가정해 보세요.
+
+이 청구서는 `id`, `title`(선택 사항), `customer`, `total`을 갖습니다.
+
+당신의 API 사용자(외부 개발자)는 POST 요청으로 당신의 API에서 청구서를 생성합니다.
+
+그 다음 당신의 API는(가정해 보면):
+
+* 청구서를 외부 개발자의 고객에게 전송합니다.
+* 돈을 수금합니다.
+* API 사용자(외부 개발자)의 API로 다시 알림을 보냅니다.
+ * 이는 (당신의 API에서) 그 외부 개발자가 제공하는 어떤 *external API*로 POST 요청을 보내는 방식으로 수행됩니다(이것이 "callback"입니다).
+
+## 일반적인 **FastAPI** 앱 { #the-normal-fastapi-app }
+
+먼저 콜백을 추가하기 전, 일반적인 API 앱이 어떻게 생겼는지 보겠습니다.
+
+`Invoice` body를 받는 *경로 처리*와, 콜백을 위한 URL을 담는 쿼리 파라미터 `callback_url`이 있을 것입니다.
+
+이 부분은 꽤 일반적이며, 대부분의 코드는 이미 익숙할 것입니다:
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *}
+
+/// tip | 팁
+
+`callback_url` 쿼리 파라미터는 Pydantic의 Url 타입을 사용합니다.
+
+///
+
+유일하게 새로운 것은 *경로 처리 데코레이터*의 인자로 `callbacks=invoices_callback_router.routes`가 들어간다는 점입니다. 이것이 무엇인지 다음에서 보겠습니다.
+
+## 콜백 문서화하기 { #documenting-the-callback }
+
+실제 콜백 코드는 당신의 API 앱에 크게 의존합니다.
+
+그리고 앱마다 많이 달라질 수 있습니다.
+
+다음처럼 한두 줄의 코드일 수도 있습니다:
+
+```Python
+callback_url = "https://example.com/api/v1/invoices/events/"
+httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
+```
+
+하지만 콜백에서 가장 중요한 부분은, 당신의 API 사용자(외부 개발자)가 콜백 요청 body로 *당신의 API*가 보낼 데이터 등에 맞춰 *external API*를 올바르게 구현하도록 보장하는 것입니다.
+
+그래서 다음으로 할 일은, *당신의 API*에서 보내는 콜백을 받기 위해 그 *external API*가 어떤 형태여야 하는지 문서화하는 코드를 추가하는 것입니다.
+
+그 문서는 당신의 API에서 `/docs`의 Swagger UI에 표시되며, 외부 개발자들이 *external API*를 어떻게 만들어야 하는지 알 수 있게 해줍니다.
+
+이 예시는 콜백 자체(한 줄 코드로도 될 수 있음)를 구현하지 않고, 문서화 부분만 구현합니다.
+
+/// tip | 팁
+
+실제 콜백은 단지 HTTP 요청입니다.
+
+콜백을 직접 구현할 때는 HTTPX나 Requests 같은 것을 사용할 수 있습니다.
+
+///
+
+## 콜백 문서화 코드 작성하기 { #write-the-callback-documentation-code }
+
+이 코드는 앱에서 실행되지 않습니다. 그 *external API*가 어떤 형태여야 하는지 *문서화*하는 데만 필요합니다.
+
+하지만 **FastAPI**로 API의 자동 문서를 쉽게 생성하는 방법은 이미 알고 있습니다.
+
+따라서 그와 같은 지식을 사용해 *external API*가 어떻게 생겨야 하는지 문서화할 것입니다... 즉 외부 API가 구현해야 하는 *경로 처리(들)*(당신의 API가 호출할 것들)을 만들어서 말입니다.
+
+/// tip | 팁
+
+콜백을 문서화하는 코드를 작성할 때는, 자신이 그 *외부 개발자*라고 상상하는 것이 유용할 수 있습니다. 그리고 지금은 *당신의 API*가 아니라 *external API*를 구현하고 있다고 생각해 보세요.
+
+이 관점(외부 개발자의 관점)을 잠시 채택하면, 그 *external API*를 위해 파라미터, body용 Pydantic 모델, 응답 등을 어디에 두어야 하는지가 더 명확하게 느껴질 수 있습니다.
+
+///
+
+### 콜백 `APIRouter` 생성하기 { #create-a-callback-apirouter }
+
+먼저 하나 이상의 콜백을 담을 새 `APIRouter`를 만듭니다.
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *}
+
+### 콜백 *경로 처리* 생성하기 { #create-the-callback-path-operation }
+
+콜백 *경로 처리*를 만들려면 위에서 만든 동일한 `APIRouter`를 사용합니다.
+
+일반적인 FastAPI *경로 처리*처럼 보일 것입니다:
+
+* 아마도 받아야 할 body 선언이 있을 것입니다(예: `body: InvoiceEvent`).
+* 그리고 반환해야 할 응답 선언도 있을 수 있습니다(예: `response_model=InvoiceEventReceived`).
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *}
+
+일반적인 *경로 처리*와의 주요 차이점은 2가지입니다:
+
+* 실제 코드를 가질 필요가 없습니다. 당신의 앱은 이 코드를 절대 호출하지 않기 때문입니다. 이는 *external API*를 문서화하는 데만 사용됩니다. 따라서 함수는 그냥 `pass`만 있어도 됩니다.
+* *path*에는 OpenAPI 3 expression(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *당신의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다.
+
+### 콜백 경로 표현식 { #the-callback-path-expression }
+
+콜백 *path*는 *당신의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 OpenAPI 3 expression을 가질 수 있습니다.
+
+이 경우, 다음 `str`입니다:
+
+```Python
+"{$callback_url}/invoices/{$request.body.id}"
+```
+
+따라서 당신의 API 사용자(외부 개발자)가 *당신의 API*로 다음 요청을 보내고:
+
+```
+https://yourapi.com/invoices/?callback_url=https://www.external.org/events
+```
+
+JSON body가 다음과 같다면:
+
+```JSON
+{
+ "id": "2expen51ve",
+ "customer": "Mr. Richie Rich",
+ "total": "9999"
+}
+```
+
+그러면 *당신의 API*는 청구서를 처리하고, 나중에 어느 시점에서 `callback_url`(즉 *external API*)로 콜백 요청을 보냅니다:
+
+```
+https://www.external.org/events/invoices/2expen51ve
+```
+
+그리고 다음과 같은 JSON body를 포함할 것입니다:
+
+```JSON
+{
+ "description": "Payment celebration",
+ "paid": true
+}
+```
+
+또한 그 *external API*로부터 다음과 같은 JSON body 응답을 기대합니다:
+
+```JSON
+{
+ "ok": true
+}
+```
+
+/// tip | 팁
+
+콜백 URL에는 `callback_url` 쿼리 파라미터로 받은 URL(`https://www.external.org/events`)뿐 아니라, JSON body 안의 청구서 `id`(`2expen51ve`)도 함께 사용된다는 점에 주목하세요.
+
+///
+
+### 콜백 라우터 추가하기 { #add-the-callback-router }
+
+이 시점에서, 위에서 만든 콜백 라우터 안에 *콜백 경로 처리(들)*(즉 *external developer*가 *external API*에 구현해야 하는 것들)을 준비했습니다.
+
+이제 *당신의 API 경로 처리 데코레이터*에서 `callbacks` 파라미터를 사용해, 그 콜백 라우터의 `.routes` 속성(실제로는 routes/*경로 처리*의 `list`)을 전달합니다:
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
+
+/// tip | 팁
+
+`callback=`에 라우터 자체(`invoices_callback_router`)를 넘기는 것이 아니라, `invoices_callback_router.routes`처럼 `.routes` 속성을 넘긴다는 점에 주목하세요.
+
+///
+
+### 문서 확인하기 { #check-the-docs }
+
+이제 앱을 실행하고 http://127.0.0.1:8000/docs로 이동하세요.
+
+*경로 처리*에 대해 "Callbacks" 섹션을 포함한 문서가 표시되며, *external API*가 어떤 형태여야 하는지 확인할 수 있습니다:
+
+
diff --git a/docs/ko/docs/advanced/openapi-webhooks.md b/docs/ko/docs/advanced/openapi-webhooks.md
new file mode 100644
index 000000000..89cacf7b7
--- /dev/null
+++ b/docs/ko/docs/advanced/openapi-webhooks.md
@@ -0,0 +1,55 @@
+# OpenAPI Webhooks { #openapi-webhooks }
+
+앱이 어떤 데이터와 함께 (요청을 보내서) *사용자의* 앱을 호출할 수 있고, 보통 어떤 **이벤트**를 **알리기** 위해 그렇게 할 수 있다는 것을 API **사용자**에게 알려야 하는 경우가 있습니다.
+
+이는 사용자가 여러분의 API로 요청을 보내는 일반적인 과정 대신, **여러분의 API**(또는 앱)가 **사용자의 시스템**(사용자의 API, 사용자의 앱)으로 **요청을 보낼 수 있다**는 의미입니다.
+
+이를 보통 **webhook**이라고 합니다.
+
+## Webhooks 단계 { #webhooks-steps }
+
+일반적인 과정은, 여러분이 코드에서 보낼 메시지, 즉 **요청 본문(body)**이 무엇인지 **정의**하는 것입니다.
+
+또한 여러분의 앱이 어떤 **시점**에 그 요청(또는 이벤트)을 보낼지도 어떤 방식으로든 정의합니다.
+
+그리고 **사용자**는 (예: 어딘가의 웹 대시보드에서) 여러분의 앱이 그 요청을 보내야 할 **URL**을 어떤 방식으로든 정의합니다.
+
+webhook의 URL을 등록하는 방법과 실제로 그 요청을 보내는 코드에 대한 모든 **로직**은 여러분에게 달려 있습니다. **여러분의 코드**에서 원하는 방식으로 작성하면 됩니다.
+
+## **FastAPI**와 OpenAPI로 webhooks 문서화하기 { #documenting-webhooks-with-fastapi-and-openapi }
+
+**FastAPI**에서는 OpenAPI를 사용해, 이러한 webhook의 이름, 여러분의 앱이 보낼 수 있는 HTTP 작업 타입(예: `POST`, `PUT` 등), 그리고 여러분의 앱이 보낼 요청 **본문(body)**을 정의할 수 있습니다.
+
+이렇게 하면 사용자가 여러분의 **webhook** 요청을 받기 위해 **자신들의 API를 구현**하기가 훨씬 쉬워지고, 경우에 따라서는 자신의 API 코드 일부를 자동 생성할 수도 있습니다.
+
+/// info | 정보
+
+Webhooks는 OpenAPI 3.1.0 이상에서 사용할 수 있으며, FastAPI `0.99.0` 이상에서 지원됩니다.
+
+///
+
+## webhooks가 있는 앱 { #an-app-with-webhooks }
+
+**FastAPI** 애플리케이션을 만들면, *경로 처리*를 정의하는 것과 같은 방식으로(예: `@app.webhooks.post()`), *webhooks*를 정의하는 데 사용할 수 있는 `webhooks` 속성이 있습니다.
+
+{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *}
+
+여러분이 정의한 webhook은 **OpenAPI** 스키마와 자동 **docs UI**에 포함됩니다.
+
+/// info | 정보
+
+`app.webhooks` 객체는 실제로 `APIRouter`일 뿐이며, 여러 파일로 앱을 구조화할 때 사용하는 것과 동일한 타입입니다.
+
+///
+
+webhook에서는 실제로(`/items/` 같은) *경로(path)*를 선언하지 않는다는 점에 유의하세요. 그곳에 전달하는 텍스트는 webhook의 **식별자**(이벤트 이름)일 뿐입니다. 예를 들어 `@app.webhooks.post("new-subscription")`에서 webhook 이름은 `new-subscription`입니다.
+
+이는 **사용자**가 webhook 요청을 받고 싶은 실제 **URL 경로**를 다른 방식(예: 웹 대시보드)으로 정의할 것이라고 기대하기 때문입니다.
+
+### 문서 확인하기 { #check-the-docs }
+
+이제 앱을 실행하고 http://127.0.0.1:8000/docs로 이동하세요.
+
+문서에 일반적인 *경로 처리*가 보이고, 이제는 일부 **webhooks**도 함께 보일 것입니다:
+
+
diff --git a/docs/ko/docs/advanced/path-operation-advanced-configuration.md b/docs/ko/docs/advanced/path-operation-advanced-configuration.md
new file mode 100644
index 000000000..f20fa6d26
--- /dev/null
+++ b/docs/ko/docs/advanced/path-operation-advanced-configuration.md
@@ -0,0 +1,172 @@
+# 경로 처리 고급 구성 { #path-operation-advanced-configuration }
+
+## OpenAPI operationId { #openapi-operationid }
+
+/// warning | 경고
+
+OpenAPI “전문가”가 아니라면, 아마 이 내용은 필요하지 않을 것입니다.
+
+///
+
+매개변수 `operation_id`를 사용해 *경로 처리*에 사용할 OpenAPI `operationId`를 설정할 수 있습니다.
+
+각 작업마다 고유하도록 보장해야 합니다.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *}
+
+### *경로 처리 함수* 이름을 operationId로 사용하기 { #using-the-path-operation-function-name-as-the-operationid }
+
+API의 함수 이름을 `operationId`로 사용하고 싶다면, 모든 API를 순회하면서 `APIRoute.name`을 사용해 각 *경로 처리*의 `operation_id`를 덮어쓸 수 있습니다.
+
+모든 *경로 처리*를 추가한 뒤에 수행해야 합니다.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *}
+
+/// tip | 팁
+
+`app.openapi()`를 수동으로 호출한다면, 그 전에 `operationId`들을 업데이트해야 합니다.
+
+///
+
+/// warning | 경고
+
+이렇게 할 경우, 각 *경로 처리 함수*의 이름이 고유하도록 보장해야 합니다.
+
+서로 다른 모듈(파이썬 파일)에 있어도 마찬가지입니다.
+
+///
+
+## OpenAPI에서 제외하기 { #exclude-from-openapi }
+
+생성된 OpenAPI 스키마(따라서 자동 문서화 시스템)에서 특정 *경로 처리*를 제외하려면, `include_in_schema` 매개변수를 `False`로 설정하세요:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *}
+
+## docstring에서 고급 설명 가져오기 { #advanced-description-from-docstring }
+
+OpenAPI에 사용할 *경로 처리 함수*의 docstring 줄 수를 제한할 수 있습니다.
+
+`\f`(이스케이프된 "form feed" 문자)를 추가하면 **FastAPI**는 이 지점에서 OpenAPI에 사용할 출력 내용을 잘라냅니다.
+
+문서에는 표시되지 않지만, Sphinx 같은 다른 도구는 나머지 부분을 사용할 수 있습니다.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
+
+## 추가 응답 { #additional-responses }
+
+*경로 처리*에 대해 `response_model`과 `status_code`를 선언하는 방법을 이미 보셨을 것입니다.
+
+이는 *경로 처리*의 기본 응답에 대한 메타데이터를 정의합니다.
+
+모델, 상태 코드 등과 함께 추가 응답도 선언할 수 있습니다.
+
+이에 대한 문서의 전체 장이 있으니, [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}에서 읽어보세요.
+
+## OpenAPI Extra { #openapi-extra }
+
+애플리케이션에서 *경로 처리*를 선언하면, **FastAPI**는 OpenAPI 스키마에 포함될 해당 *경로 처리*의 관련 메타데이터를 자동으로 생성합니다.
+
+/// note | 기술 세부사항
+
+OpenAPI 명세에서는 이를 Operation Object라고 부릅니다.
+
+///
+
+여기에는 *경로 처리*에 대한 모든 정보가 있으며, 자동 문서를 생성하는 데 사용됩니다.
+
+`tags`, `parameters`, `requestBody`, `responses` 등이 포함됩니다.
+
+이 *경로 처리* 전용 OpenAPI 스키마는 보통 **FastAPI**가 자동으로 생성하지만, 확장할 수도 있습니다.
+
+/// tip | 팁
+
+이는 저수준 확장 지점입니다.
+
+추가 응답만 선언하면 된다면, 더 편리한 방법은 [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}을 사용하는 것입니다.
+
+///
+
+`openapi_extra` 매개변수를 사용해 *경로 처리*의 OpenAPI 스키마를 확장할 수 있습니다.
+
+### OpenAPI 확장 { #openapi-extensions }
+
+예를 들어 `openapi_extra`는 [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions)를 선언하는 데 도움이 될 수 있습니다:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *}
+
+자동 API 문서를 열면, 해당 특정 *경로 처리*의 하단에 확장이 표시됩니다.
+
+
+
+또한 API의 `/openapi.json`에서 결과 OpenAPI를 보면, 특정 *경로 처리*의 일부로 확장이 포함된 것도 확인할 수 있습니다:
+
+```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"
+ }
+ }
+ }
+}
+```
+
+### 사용자 정의 OpenAPI *경로 처리* 스키마 { #custom-openapi-path-operation-schema }
+
+`openapi_extra`의 딕셔너리는 *경로 처리*에 대해 자동으로 생성된 OpenAPI 스키마와 깊게 병합됩니다.
+
+따라서 자동 생성된 스키마에 추가 데이터를 더할 수 있습니다.
+
+예를 들어 Pydantic과 함께 FastAPI의 자동 기능을 사용하지 않고, 자체 코드로 요청을 읽고 검증하기로 결정할 수도 있지만, OpenAPI 스키마에는 여전히 그 요청을 정의하고 싶을 수 있습니다.
+
+그럴 때 `openapi_extra`를 사용할 수 있습니다:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *}
+
+이 예시에서는 어떤 Pydantic 모델도 선언하지 않았습니다. 사실 요청 바디는 JSON으로 parsed되지도 않고, `bytes`로 직접 읽습니다. 그리고 함수 `magic_data_reader()`가 어떤 방식으로든 이를 파싱하는 역할을 담당합니다.
+
+그럼에도 불구하고, 요청 바디에 대해 기대하는 스키마를 선언할 수 있습니다.
+
+### 사용자 정의 OpenAPI 콘텐츠 타입 { #custom-openapi-content-type }
+
+같은 트릭을 사용하면, Pydantic 모델을 이용해 JSON Schema를 정의하고 이를 *경로 처리*의 사용자 정의 OpenAPI 스키마 섹션에 포함시킬 수 있습니다.
+
+요청의 데이터 타입이 JSON이 아니더라도 이렇게 할 수 있습니다.
+
+예를 들어 이 애플리케이션에서는 Pydantic 모델에서 JSON Schema를 추출하는 FastAPI의 통합 기능도, JSON에 대한 자동 검증도 사용하지 않습니다. 실제로 요청 콘텐츠 타입을 JSON이 아니라 YAML로 선언합니다:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *}
+
+그럼에도 기본 통합 기능을 사용하지 않더라도, YAML로 받고자 하는 데이터에 대한 JSON Schema를 수동으로 생성하기 위해 Pydantic 모델을 여전히 사용합니다.
+
+그 다음 요청을 직접 사용하고, 바디를 `bytes`로 추출합니다. 이는 FastAPI가 요청 페이로드를 JSON으로 파싱하려고 시도조차 하지 않는다는 뜻입니다.
+
+그리고 코드에서 YAML 콘텐츠를 직접 파싱한 뒤, 다시 같은 Pydantic 모델을 사용해 YAML 콘텐츠를 검증합니다:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *}
+
+/// tip | 팁
+
+여기서는 같은 Pydantic 모델을 재사용합니다.
+
+하지만 마찬가지로, 다른 방식으로 검증할 수도 있습니다.
+
+///
diff --git a/docs/ko/docs/advanced/response-change-status-code.md b/docs/ko/docs/advanced/response-change-status-code.md
index 1ba9aa3cc..4dfadde9d 100644
--- a/docs/ko/docs/advanced/response-change-status-code.md
+++ b/docs/ko/docs/advanced/response-change-status-code.md
@@ -1,31 +1,31 @@
-# 응답 - 상태 코드 변경
+# 응답 - 상태 코드 변경 { #response-change-status-code }
기본 [응답 상태 코드 설정](../tutorial/response-status-code.md){.internal-link target=_blank}이 가능하다는 걸 이미 알고 계실 겁니다.
하지만 경우에 따라 기본 설정과 다른 상태 코드를 반환해야 할 때가 있습니다.
-## 사용 예
+## 사용 예 { #use-case }
예를 들어 기본적으로 HTTP 상태 코드 "OK" `200`을 반환하고 싶다고 가정해 봅시다.
하지만 데이터가 존재하지 않으면 이를 새로 생성하고, HTTP 상태 코드 "CREATED" `201`을 반환하고자 할 때가 있을 수 있습니다.
-이때도 여전히 `response_model`을 사용하여 반환하는 데이터를 필터링하고 변환하고 싶을 수 있습니다.
+하지만 여전히 `response_model`을 사용하여 반환하는 데이터를 필터링하고 변환할 수 있기를 원합니다.
이런 경우에는 `Response` 파라미터를 사용할 수 있습니다.
-## `Response` 파라미터 사용하기
+## `Response` 파라미터 사용하기 { #use-a-response-parameter }
-*경로 작동 함수*에 `Response` 타입의 파라미터를 선언할 수 있습니다. (쿠키와 헤더에 대해 선언하는 것과 유사하게)
+*경로 처리 함수*에 `Response` 타입의 파라미터를 선언할 수 있습니다. (쿠키와 헤더에 대해 선언하는 것과 유사하게)
그리고 이 *임시* 응답 객체에서 `status_code`를 설정할 수 있습니다.
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *}
-그리고 평소처럼 원하는 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
+그리고 평소처럼 필요한 어떤 객체든 반환할 수 있습니다(`dict`, 데이터베이스 모델 등).
`response_model`을 선언했다면 반환된 객체는 여전히 필터링되고 변환됩니다.
-**FastAPI**는 이 *임시* 응답 객체에서 상태 코드(쿠키와 헤더 포함)를 추출하여, `response_model`로 필터링된 반환 값을 최종 응답에 넣습니다.
+**FastAPI**는 이 *임시* 응답 객체에서 상태 코드(쿠키와 헤더 포함)를 추출하여, `response_model`로 필터링된 반환 값을 포함하는 최종 응답에 넣습니다.
또한, 의존성에서도 `Response` 파라미터를 선언하고 그 안에서 상태 코드를 설정할 수 있습니다. 단, 마지막으로 설정된 상태 코드가 우선 적용된다는 점을 유의하세요.
diff --git a/docs/ko/docs/advanced/response-cookies.md b/docs/ko/docs/advanced/response-cookies.md
index 327f20afe..eef74276f 100644
--- a/docs/ko/docs/advanced/response-cookies.md
+++ b/docs/ko/docs/advanced/response-cookies.md
@@ -1,49 +1,51 @@
-# 응답 쿠키
+# 응답 쿠키 { #response-cookies }
-## `Response` 매개변수 사용하기
+## `Response` 매개변수 사용하기 { #use-a-response-parameter }
-*경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다.
+*경로 처리 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다.
그런 다음 해당 *임시* 응답 객체에서 쿠키를 설정할 수 있습니다.
-{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *}
-그런 다음 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
+그런 다음 일반적으로 하듯이 필요한 어떤 객체든 반환할 수 있습니다(`dict`, 데이터베이스 모델 등).
그리고 `response_model`을 선언했다면 반환한 객체를 거르고 변환하는 데 여전히 사용됩니다.
-**FastAPI**는 그 *임시* 응답에서 쿠키(또한 헤더 및 상태 코드)를 추출하고, 반환된 값이 포함된 최종 응답에 이를 넣습니다. 이 값은 `response_model`로 걸러지게 됩니다.
+**FastAPI**는 그 *임시* 응답에서 쿠키(또한 헤더 및 상태 코드)를 추출하고, `response_model`로 필터링된 반환 값이 포함된 최종 응답에 이를 넣습니다.
또한 의존관계에서 `Response` 매개변수를 선언하고, 해당 의존성에서 쿠키(및 헤더)를 설정할 수도 있습니다.
-## `Response`를 직접 반환하기
+## `Response`를 직접 반환하기 { #return-a-response-directly }
코드에서 `Response`를 직접 반환할 때도 쿠키를 생성할 수 있습니다.
이를 위해 [Response를 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성할 수 있습니다.
그런 다음 쿠키를 설정하고 반환하면 됩니다:
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-/// tip
+
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
+
+/// tip | 팁
`Response` 매개변수를 사용하지 않고 응답을 직접 반환하는 경우, FastAPI는 이를 직접 반환한다는 점에 유의하세요.
따라서 데이터가 올바른 유형인지 확인해야 합니다. 예: `JSONResponse`를 반환하는 경우, JSON과 호환되는지 확인하세요.
-또한 `response_model`로 걸러져야 할 데이터가 전달되지 않도록 확인하세요.
+또한 `response_model`로 필터링되어야 했던 데이터를 전송하지 않도록 하세요.
///
-### 추가 정보
+### 추가 정보 { #more-info }
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
`from starlette.responses import Response` 또는 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
-**FastAPI**는 개발자의 편의를 위해 `fastapi.responses`로 동일한 `starlette.responses`를 제공합니다. 그러나 대부분의 응답은 Starlette에서 직접 제공됩니다.
+**FastAPI**는 개발자의 편의를 위해 `fastapi.responses`로 동일한 `starlette.responses`를 제공합니다. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 제공됩니다.
또한 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용되므로, **FastAPI**는 이를 `fastapi.Response`로도 제공합니다.
///
-사용 가능한 모든 매개변수와 옵션은 Starlette 문서에서 확인할 수 있습니다.
+사용 가능한 모든 매개변수와 옵션은 Starlette의 문서에서 확인할 수 있습니다.
diff --git a/docs/ko/docs/advanced/response-directly.md b/docs/ko/docs/advanced/response-directly.md
index 08d63c43c..abf06bb18 100644
--- a/docs/ko/docs/advanced/response-directly.md
+++ b/docs/ko/docs/advanced/response-directly.md
@@ -1,20 +1,20 @@
-# 응답을 직접 반환하기
+# 응답을 직접 반환하기 { #return-a-response-directly }
-**FastAPI**에서 *경로 작업(path operation)*을 생성할 때, 일반적으로 `dict`, `list`, Pydantic 모델, 데이터베이스 모델 등의 데이터를 반환할 수 있습니다.
+**FastAPI**에서 *경로 처리(path operation)*를 생성할 때, 일반적으로 `dict`, `list`, Pydantic 모델, 데이터베이스 모델 등의 데이터를 반환할 수 있습니다.
-기본적으로 **FastAPI**는 [JSON 호환 가능 인코더](../tutorial/encoder.md){.internal-link target=_blank}에 설명된 `jsonable_encoder`를 사용해 해당 반환 값을 자동으로 `JSON`으로 변환합니다.
+기본적으로 **FastAPI**는 [JSON 호환 가능 인코더](../tutorial/encoder.md){.internal-link target=_blank}에 설명된 `jsonable_encoder`를 사용해 해당 반환 값을 자동으로 JSON으로 변환합니다.
-그런 다음, JSON 호환 데이터(예: `dict`)를 `JSONResponse`에 넣어 사용자의 응답을 전송하는 방식으로 처리됩니다.
+그런 다음, 내부적으로는 JSON 호환 데이터(예: `dict`)를 `JSONResponse`에 넣어 클라이언트로 응답을 전송하는 데 사용합니다.
-그러나 *경로 작업*에서 `JSONResponse`를 직접 반환할 수도 있습니다.
+하지만 *경로 처리*에서 `JSONResponse`를 직접 반환할 수도 있습니다.
예를 들어, 사용자 정의 헤더나 쿠키를 반환해야 하는 경우에 유용할 수 있습니다.
-## `Response` 반환하기
+## `Response` 반환하기 { #return-a-response }
사실, `Response` 또는 그 하위 클래스를 반환할 수 있습니다.
-/// tip
+/// tip | 팁
`JSONResponse` 자체도 `Response`의 하위 클래스입니다.
@@ -26,38 +26,40 @@ Pydantic 모델로 데이터 변환을 수행하지 않으며, 내용을 다른
이로 인해 많은 유연성을 얻을 수 있습니다. 어떤 데이터 유형이든 반환할 수 있고, 데이터 선언이나 유효성 검사를 재정의할 수 있습니다.
-## `Response`에서 `jsonable_encoder` 사용하기
+## `Response`에서 `jsonable_encoder` 사용하기 { #using-the-jsonable-encoder-in-a-response }
-**FastAPI**는 반환하는 `Response`에 아무런 변환을 하지 않으므로, 그 내용이 준비되어 있어야 합니다.
+**FastAPI**는 반환하는 `Response`에 아무런 변경도 하지 않으므로, 그 내용이 준비되어 있는지 확인해야 합니다.
-예를 들어, Pydantic 모델을 `dict`로 변환해 `JSONResponse`에 넣지 않으면 JSON 호환 유형으로 변환된 데이터 유형(예: `datetime`, `UUID` 등)이 사용되지 않습니다.
+예를 들어, Pydantic 모델을 먼저 `dict`로 변환하고 `datetime`, `UUID` 등의 모든 데이터 타입을 JSON 호환 타입으로 변환하지 않으면 Pydantic 모델을 `JSONResponse`에 넣을 수 없습니다.
이러한 경우, 데이터를 응답에 전달하기 전에 `jsonable_encoder`를 사용하여 변환할 수 있습니다:
-{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
-/// note | 기술적 세부 사항
+/// note | 기술 세부사항
`from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
-**FastAPI**는 개발자의 편의를 위해 `starlette.responses`를 `fastapi.responses`로 제공합니다. 그러나 대부분의 가능한 응답은 Starlette에서 직접 제공합니다.
+**FastAPI**는 개발자의 편의를 위해 `starlette.responses`를 `fastapi.responses`로 제공합니다. 하지만 대부분의 사용 가능한 응답은 Starlette에서 직접 제공합니다.
///
-## 사용자 정의 `Response` 반환하기
-위 예제는 필요한 모든 부분을 보여주지만, 아직 유용하지는 않습니다. 사실 데이터를 직접 반환하면 **FastAPI**가 이를 `JSONResponse`에 넣고 `dict`로 변환하는 등 모든 작업을 자동으로 처리합니다.
+## 사용자 정의 `Response` 반환하기 { #returning-a-custom-response }
-이제, 사용자 정의 응답을 반환하는 방법을 알아보겠습니다.
+위 예제는 필요한 모든 부분을 보여주지만, 아직은 그다지 유용하지 않습니다. `item`을 그냥 직접 반환했어도 **FastAPI**가 기본으로 이를 `JSONResponse`에 넣고 `dict`로 변환하는 등의 작업을 모두 수행해 주었을 것이기 때문입니다.
-예를 들어 XML 응답을 반환하고 싶다고 가정해보겠습니다.
+이제, 이를 사용해 사용자 정의 응답을 반환하는 방법을 알아보겠습니다.
+
+예를 들어 XML 응답을 반환하고 싶다고 가정해 보겠습니다.
XML 내용을 문자열에 넣고, 이를 `Response`에 넣어 반환할 수 있습니다:
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
+
+## 참고 사항 { #notes }
-## 참고 사항
`Response`를 직접 반환할 때, 그 데이터는 자동으로 유효성 검사되거나, 변환(직렬화)되거나, 문서화되지 않습니다.
그러나 [OpenAPI에서 추가 응답](additional-responses.md){.internal-link target=_blank}에서 설명된 대로 문서화할 수 있습니다.
-이후 단락에서 자동 데이터 변환, 문서화 등을 사용하면서 사용자 정의 `Response`를 선언하는 방법을 확인할 수 있습니다.
+이후 섹션에서 자동 데이터 변환, 문서화 등을 계속 사용하면서 이러한 사용자 정의 `Response`를 사용하는/선언하는 방법을 확인할 수 있습니다.
diff --git a/docs/ko/docs/advanced/response-headers.md b/docs/ko/docs/advanced/response-headers.md
index e8abe0be2..1c36db9b9 100644
--- a/docs/ko/docs/advanced/response-headers.md
+++ b/docs/ko/docs/advanced/response-headers.md
@@ -1,12 +1,12 @@
-# 응답 헤더
+# 응답 헤더 { #response-headers }
-## `Response` 매개변수 사용하기
+## `Response` 매개변수 사용하기 { #use-a-response-parameter }
-여러분은 *경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다).
+여러분은 *경로 처리 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다).
그런 다음, 여러분은 해당 *임시* 응답 객체에서 헤더를 설정할 수 있습니다.
-{* ../../docs_src/response_headers/tutorial002.py hl[1,7:8] *}
+{* ../../docs_src/response_headers/tutorial002_py39.py hl[1, 7:8] *}
그 후, 일반적으로 사용하듯이 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다.
@@ -16,26 +16,26 @@
또한, 종속성에서 `Response` 매개변수를 선언하고 그 안에서 헤더(및 쿠키)를 설정할 수 있습니다.
-## `Response` 직접 반환하기
+## `Response` 직접 반환하기 { #return-a-response-directly }
`Response`를 직접 반환할 때에도 헤더를 추가할 수 있습니다.
[응답을 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성하고, 헤더를 추가 매개변수로 전달하세요.
-{* ../../docs_src/response_headers/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_headers/tutorial001_py39.py hl[10:12] *}
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
`from starlette.responses import Response`나 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다.
-**FastAPI**는 `starlette.responses`를 `fastapi.responses`로 개발자의 편의를 위해 직접 제공하지만, 대부분의 응답은 Starlette에서 직접 제공됩니다.
+**FastAPI**는 해당 *임시* 응답에서 헤더(쿠키와 상태 코드도 포함)를 추출하여, 여러분이 반환한 값을 포함하는 최종 응답에 `response_model`로 필터링된 값을 넣습니다.
그리고 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용될 수 있으므로, **FastAPI**는 `fastapi.Response`로도 이를 제공합니다.
///
-## 커스텀 헤더
+## 커스텀 헤더 { #custom-headers }
-‘X-’ 접두어를 사용하여 커스텀 사설 헤더를 추가할 수 있습니다.
+`X-` 접두어를 사용하여 커스텀 사설 헤더를 추가할 수 있다는 점을 기억하세요.
-하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}에서 자세히 알아보세요). `expose_headers` 매개변수를 사용하여 Starlette의 CORS 설명서에 문서화된 대로 설정할 수 있습니다.
+하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}에서 자세히 알아보세요). Starlette의 CORS 문서에 문서화된 `expose_headers` 매개변수를 사용하세요.
diff --git a/docs/ko/docs/advanced/security/http-basic-auth.md b/docs/ko/docs/advanced/security/http-basic-auth.md
new file mode 100644
index 000000000..611aad795
--- /dev/null
+++ b/docs/ko/docs/advanced/security/http-basic-auth.md
@@ -0,0 +1,107 @@
+# HTTP Basic Auth { #http-basic-auth }
+
+가장 단순한 경우에는 HTTP Basic Auth를 사용할 수 있습니다.
+
+HTTP Basic Auth에서는 애플리케이션이 사용자명과 비밀번호가 들어 있는 헤더를 기대합니다.
+
+이를 받지 못하면 HTTP 401 "Unauthorized" 오류를 반환합니다.
+
+그리고 값이 `Basic`이고 선택적으로 `realm` 파라미터를 포함하는 `WWW-Authenticate` 헤더를 반환합니다.
+
+이는 브라우저가 사용자명과 비밀번호를 입력하는 통합 프롬프트를 표시하도록 알려줍니다.
+
+그다음 사용자명과 비밀번호를 입력하면, 브라우저가 자동으로 해당 값을 헤더에 담아 전송합니다.
+
+## 간단한 HTTP Basic Auth { #simple-http-basic-auth }
+
+* `HTTPBasic`과 `HTTPBasicCredentials`를 임포트합니다.
+* `HTTPBasic`을 사용해 "`security` scheme"을 생성합니다.
+* *경로 처리*에서 dependency로 해당 `security`를 사용합니다.
+* `HTTPBasicCredentials` 타입의 객체를 반환합니다:
+ * 전송된 `username`과 `password`를 포함합니다.
+
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
+
+처음으로 URL을 열어보면(또는 문서에서 "Execute" 버튼을 클릭하면) 브라우저가 사용자명과 비밀번호를 물어봅니다:
+
+
+
+## 사용자명 확인하기 { #check-the-username }
+
+더 완전한 예시입니다.
+
+dependency를 사용해 사용자명과 비밀번호가 올바른지 확인하세요.
+
+이를 위해 Python 표준 모듈 `secrets`를 사용해 사용자명과 비밀번호를 확인합니다.
+
+`secrets.compare_digest()`는 `bytes` 또는 ASCII 문자(영어에서 사용하는 문자)만 포함한 `str`을 받아야 합니다. 즉, `Sebastián`의 `á` 같은 문자가 있으면 동작하지 않습니다.
+
+이를 처리하기 위해 먼저 `username`과 `password`를 UTF-8로 인코딩해서 `bytes`로 변환합니다.
+
+그런 다음 `secrets.compare_digest()`를 사용해 `credentials.username`이 `"stanleyjobson"`이고 `credentials.password`가 `"swordfish"`인지 확실히 확인할 수 있습니다.
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
+
+이는 다음과 비슷합니다:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+ # Return some error
+ ...
+```
+
+하지만 `secrets.compare_digest()`를 사용하면 "timing attacks"라고 불리는 한 유형의 공격에 대해 안전해집니다.
+
+### Timing Attacks { #timing-attacks }
+
+그렇다면 "timing attack"이란 무엇일까요?
+
+공격자들이 사용자명과 비밀번호를 추측하려고 한다고 가정해봅시다.
+
+그리고 사용자명 `johndoe`, 비밀번호 `love123`으로 요청을 보냅니다.
+
+그러면 애플리케이션의 Python 코드는 대략 다음과 같을 것입니다:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+하지만 Python이 `johndoe`의 첫 글자 `j`를 `stanleyjobson`의 첫 글자 `s`와 비교하는 순간, 두 문자열이 같지 않다는 것을 이미 알게 되어 `False`를 반환합니다. 이는 “나머지 글자들을 비교하느라 계산을 더 낭비할 필요가 없다”고 판단하기 때문입니다. 그리고 애플리케이션은 "Incorrect username or password"라고 말합니다.
+
+그런데 공격자들이 사용자명을 `stanleyjobsox`, 비밀번호를 `love123`으로 다시 시도합니다.
+
+그러면 애플리케이션 코드는 다음과 비슷하게 동작합니다:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Python은 두 문자열이 같지 않다는 것을 알아차리기 전까지 `stanleyjobsox`와 `stanleyjobson` 양쪽의 `stanleyjobso` 전체를 비교해야 합니다. 그래서 "Incorrect username or password"라고 응답하기까지 추가로 몇 마이크로초가 더 걸릴 것입니다.
+
+#### 응답 시간은 공격자에게 도움이 됩니다 { #the-time-to-answer-helps-the-attackers }
+
+이 시점에서 서버가 "Incorrect username or password" 응답을 보내는 데 몇 마이크로초 더 걸렸다는 것을 알아채면, 공격자들은 _무언가_ 맞았다는 것(초기 몇 글자가 맞았다는 것)을 알게 됩니다.
+
+그리고 `johndoe`보다는 `stanleyjobsox`에 더 가까운 값을 시도해야 한다는 것을 알고 다시 시도할 수 있습니다.
+
+#### "전문적인" 공격 { #a-professional-attack }
+
+물론 공격자들은 이런 작업을 손으로 하지 않습니다. 보통 초당 수천~수백만 번 테스트할 수 있는 프로그램을 작성할 것이고, 한 번에 정답 글자 하나씩 추가로 얻어낼 수 있습니다.
+
+그렇게 하면 몇 분 또는 몇 시간 만에, 응답에 걸린 시간만을 이용해(우리 애플리케이션의 “도움”을 받아) 올바른 사용자명과 비밀번호를 추측할 수 있게 됩니다.
+
+#### `secrets.compare_digest()`로 해결하기 { #fix-it-with-secrets-compare-digest }
+
+하지만 우리 코드는 실제로 `secrets.compare_digest()`를 사용하고 있습니다.
+
+요약하면, `stanleyjobsox`와 `stanleyjobson`을 비교하는 데 걸리는 시간은 `johndoe`와 `stanleyjobson`을 비교하는 데 걸리는 시간과 같아집니다. 비밀번호도 마찬가지입니다.
+
+이렇게 애플리케이션 코드에서 `secrets.compare_digest()`를 사용하면, 이러한 범위의 보안 공격 전반에 대해 안전해집니다.
+
+### 오류 반환하기 { #return-the-error }
+
+자격 증명이 올바르지 않다고 판단되면, 상태 코드 401(자격 증명이 제공되지 않았을 때와 동일)을 사용하는 `HTTPException`을 반환하고 브라우저가 로그인 프롬프트를 다시 표시하도록 `WWW-Authenticate` 헤더를 추가하세요:
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/ko/docs/advanced/security/index.md b/docs/ko/docs/advanced/security/index.md
new file mode 100644
index 000000000..4c7abfacc
--- /dev/null
+++ b/docs/ko/docs/advanced/security/index.md
@@ -0,0 +1,19 @@
+# 고급 보안 { #advanced-security }
+
+## 추가 기능 { #additional-features }
+
+[튜토리얼 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank}에서 다룬 내용 외에도, 보안을 처리하기 위한 몇 가지 추가 기능이 있습니다.
+
+/// tip | 팁
+
+다음 섹션들은 **반드시 "고급"이라고 할 수는 없습니다**.
+
+그리고 사용 사례에 따라, 그중 하나에 해결책이 있을 수도 있습니다.
+
+///
+
+## 먼저 튜토리얼 읽기 { #read-the-tutorial-first }
+
+다음 섹션은 주요 [튜토리얼 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank}을 이미 읽었다고 가정합니다.
+
+모두 동일한 개념을 기반으로 하지만, 몇 가지 추가 기능을 사용할 수 있게 해줍니다.
diff --git a/docs/ko/docs/advanced/security/oauth2-scopes.md b/docs/ko/docs/advanced/security/oauth2-scopes.md
new file mode 100644
index 000000000..0f90f92ae
--- /dev/null
+++ b/docs/ko/docs/advanced/security/oauth2-scopes.md
@@ -0,0 +1,274 @@
+# OAuth2 스코프 { #oauth2-scopes }
+
+**FastAPI**에서 OAuth2 스코프를 직접 사용할 수 있으며, 자연스럽게 동작하도록 통합되어 있습니다.
+
+이를 통해 OAuth2 표준을 따르는 더 세밀한 권한 시스템을 OpenAPI 애플리케이션(및 API 문서)에 통합할 수 있습니다.
+
+스코프를 사용하는 OAuth2는 Facebook, Google, GitHub, Microsoft, X(Twitter) 등 많은 대형 인증 제공자가 사용하는 메커니즘입니다. 이들은 이를 통해 사용자와 애플리케이션에 특정 권한을 제공합니다.
+
+Facebook, Google, GitHub, Microsoft, X(Twitter)로 “로그인”할 때마다, 해당 애플리케이션은 스코프가 있는 OAuth2를 사용하고 있습니다.
+
+이 섹션에서는 **FastAPI** 애플리케이션에서 동일한 “스코프가 있는 OAuth2”로 인증(Authentication)과 인가(Authorization)를 관리하는 방법을 확인합니다.
+
+/// warning | 경고
+
+이 섹션은 다소 고급 내용입니다. 이제 막 시작했다면 건너뛰어도 됩니다.
+
+OAuth2 스코프가 반드시 필요한 것은 아니며, 인증과 인가는 원하는 방식으로 처리할 수 있습니다.
+
+하지만 스코프가 있는 OAuth2는 (OpenAPI와 함께) API 및 API 문서에 깔끔하게 통합될 수 있습니다.
+
+그럼에도 불구하고, 해당 스코프(또는 그 밖의 어떤 보안/인가 요구사항이든)는 코드에서 필요에 맞게 직접 강제해야 합니다.
+
+많은 경우 스코프가 있는 OAuth2는 과한 선택일 수 있습니다.
+
+하지만 필요하다고 알고 있거나 궁금하다면 계속 읽어보세요.
+
+///
+
+## OAuth2 스코프와 OpenAPI { #oauth2-scopes-and-openapi }
+
+OAuth2 사양은 “스코프(scopes)”를 공백으로 구분된 문자열 목록으로 정의합니다.
+
+각 문자열의 내용은 어떤 형식이든 될 수 있지만, 공백을 포함하면 안 됩니다.
+
+이 스코프들은 “권한”을 나타냅니다.
+
+OpenAPI(예: API 문서)에서는 “security schemes”를 정의할 수 있습니다.
+
+이 security scheme 중 하나가 OAuth2를 사용한다면, 스코프도 선언하고 사용할 수 있습니다.
+
+각 “스코프”는 (공백 없는) 문자열일 뿐입니다.
+
+보통 다음과 같이 특정 보안 권한을 선언하는 데 사용합니다:
+
+* `users:read` 또는 `users:write` 는 흔한 예시입니다.
+* `instagram_basic` 는 Facebook/Instagram에서 사용합니다.
+* `https://www.googleapis.com/auth/drive` 는 Google에서 사용합니다.
+
+/// info | 정보
+
+OAuth2에서 “스코프”는 필요한 특정 권한을 선언하는 문자열일 뿐입니다.
+
+`:` 같은 다른 문자가 있거나 URL이어도 상관없습니다.
+
+그런 세부사항은 구현에 따라 달라집니다.
+
+OAuth2 입장에서는 그저 문자열입니다.
+
+///
+
+## 전체 개요 { #global-view }
+
+먼저, 메인 **튜토리얼 - 사용자 가이드**의 [비밀번호(및 해싱)를 사용하는 OAuth2, JWT 토큰을 사용하는 Bearer](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 예제에서 어떤 부분이 바뀌는지 빠르게 살펴보겠습니다. 이제 OAuth2 스코프를 사용합니다:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
+
+이제 변경 사항을 단계별로 살펴보겠습니다.
+
+## OAuth2 보안 스킴 { #oauth2-security-scheme }
+
+첫 번째 변경 사항은 이제 사용 가능한 스코프 2개(`me`, `items`)로 OAuth2 보안 스킴을 선언한다는 점입니다.
+
+`scopes` 매개변수는 각 스코프를 키로 하고, 설명을 값으로 하는 `dict`를 받습니다:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+
+이제 스코프를 선언했기 때문에, 로그인/인가할 때 API 문서에 스코프가 표시됩니다.
+
+그리고 접근을 허용할 스코프를 선택할 수 있게 됩니다: `me`와 `items`.
+
+이는 Facebook, Google, GitHub 등으로 로그인하면서 권한을 부여할 때 사용되는 것과 동일한 메커니즘입니다:
+
+
+
+## 스코프를 포함한 JWT 토큰 { #jwt-token-with-scopes }
+
+이제 토큰 *경로 처리*를 수정해, 요청된 스코프를 반환하도록 합니다.
+
+여전히 동일한 `OAuth2PasswordRequestForm`을 사용합니다. 여기에는 요청에서 받은 각 스코프를 담는 `scopes` 속성이 있으며, 타입은 `str`의 `list`입니다.
+
+그리고 JWT 토큰의 일부로 스코프를 반환합니다.
+
+/// danger | 위험
+
+단순화를 위해, 여기서는 요청으로 받은 스코프를 그대로 토큰에 추가하고 있습니다.
+
+하지만 실제 애플리케이션에서는 보안을 위해, 사용자가 실제로 가질 수 있는 스코프만(또는 미리 정의한 것만) 추가하도록 반드시 확인해야 합니다.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}
+
+## *경로 처리*와 의존성에서 스코프 선언하기 { #declare-scopes-in-path-operations-and-dependencies }
+
+이제 `/users/me/items/`에 대한 *경로 처리*가 스코프 `items`를 요구한다고 선언합니다.
+
+이를 위해 `fastapi`에서 `Security`를 import하여 사용합니다.
+
+`Security`는 (`Depends`처럼) 의존성을 선언하는 데 사용할 수 있지만, `Security`는 스코프(문자열) 목록을 받는 `scopes` 매개변수도 받습니다.
+
+이 경우, 의존성 함수 `get_current_active_user`를 `Security`에 전달합니다(`Depends`로 할 때와 같은 방식).
+
+하지만 스코프 `list`도 함께 전달합니다. 여기서는 스코프 하나만: `items`(더 많을 수도 있습니다).
+
+또한 의존성 함수 `get_current_active_user`는 `Depends`뿐 아니라 `Security`로도 하위 의존성을 선언할 수 있습니다. 자체 하위 의존성 함수(`get_current_user`)와 추가 스코프 요구사항을 선언합니다.
+
+이 경우에는 스코프 `me`를 요구합니다(여러 스코프를 요구할 수도 있습니다).
+
+/// note | 참고
+
+반드시 서로 다른 곳에 서로 다른 스코프를 추가해야 하는 것은 아닙니다.
+
+여기서는 **FastAPI**가 서로 다른 레벨에서 선언된 스코프를 어떻게 처리하는지 보여주기 위해 이렇게 합니다.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
+
+/// info | 기술 세부사항
+
+`Security`는 실제로 `Depends`의 서브클래스이며, 나중에 보게 될 추가 매개변수 하나만 더 있습니다.
+
+하지만 `Depends` 대신 `Security`를 사용하면, **FastAPI**는 보안 스코프를 선언할 수 있음을 알고 내부적으로 이를 사용하며, OpenAPI로 API를 문서화할 수 있습니다.
+
+하지만 `fastapi`에서 `Query`, `Path`, `Depends`, `Security` 등을 import할 때, 이것들은 실제로 특수한 클래스를 반환하는 함수입니다.
+
+///
+
+## `SecurityScopes` 사용하기 { #use-securityscopes }
+
+이제 의존성 `get_current_user`를 업데이트합니다.
+
+이는 위의 의존성들이 사용하는 것입니다.
+
+여기에서 앞서 만든 동일한 OAuth2 스킴을 의존성으로 선언하여 사용합니다: `oauth2_scheme`.
+
+이 의존성 함수 자체에는 스코프 요구사항이 없기 때문에, `oauth2_scheme`와 함께 `Depends`를 사용할 수 있습니다. 보안 스코프를 지정할 필요가 없을 때는 `Security`를 쓸 필요가 없습니다.
+
+또한 `fastapi.security`에서 import한 `SecurityScopes` 타입의 특별한 매개변수를 선언합니다.
+
+이 `SecurityScopes` 클래스는 `Request`와 비슷합니다(`Request`는 요청 객체를 직접 얻기 위해 사용했습니다).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
+
+## `scopes` 사용하기 { #use-the-scopes }
+
+매개변수 `security_scopes`의 타입은 `SecurityScopes`입니다.
+
+여기에는 `scopes` 속성이 있으며, 자기 자신과 이 함수를 하위 의존성으로 사용하는 모든 의존성이 요구하는 스코프 전체를 담은 `list`를 가집니다. 즉, 모든 “dependants”... 다소 헷갈릴 수 있는데, 아래에서 다시 설명합니다.
+
+`security_scopes` 객체(`SecurityScopes` 클래스)에는 또한 `scope_str` 속성이 있는데, 공백으로 구분된 단일 문자열로 스코프들을 담고 있습니다(이를 사용할 것입니다).
+
+나중에 여러 지점에서 재사용(`raise`)할 수 있는 `HTTPException`을 생성합니다.
+
+이 예외에는 필요한 스코프(있다면)를 공백으로 구분된 문자열(`scope_str`)로 포함합니다. 그리고 그 스코프 문자열을 `WWW-Authenticate` 헤더에 넣습니다(이는 사양의 일부입니다).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
+
+## `username`과 데이터 형태 검증하기 { #verify-the-username-and-data-shape }
+
+`username`을 얻었는지 확인하고, 스코프를 추출합니다.
+
+그런 다음 Pydantic 모델로 데이터를 검증합니다(`ValidationError` 예외를 잡습니다). JWT 토큰을 읽거나 Pydantic으로 데이터를 검증하는 과정에서 오류가 나면, 앞에서 만든 `HTTPException`을 raise합니다.
+
+이를 위해 Pydantic 모델 `TokenData`에 새 속성 `scopes`를 추가합니다.
+
+Pydantic으로 데이터를 검증하면, 예를 들어 스코프가 정확히 `str`의 `list`이고 `username`이 `str`인지 등을 보장할 수 있습니다.
+
+예를 들어 `dict`나 다른 형태라면, 나중에 애플리케이션이 어느 시점에 깨지면서 보안 위험이 될 수 있습니다.
+
+또한 해당 username을 가진 사용자가 있는지 확인하고, 없다면 앞에서 만든 동일한 예외를 raise합니다.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}
+
+## `scopes` 검증하기 { #verify-the-scopes }
+
+이제 이 의존성과 모든 dependant( *경로 처리* 포함)가 요구하는 모든 스코프가, 받은 토큰의 스코프에 포함되어 있는지 확인합니다. 그렇지 않으면 `HTTPException`을 raise합니다.
+
+이를 위해, 모든 스코프를 `str`로 담고 있는 `security_scopes.scopes`를 사용합니다.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
+
+## 의존성 트리와 스코프 { #dependency-tree-and-scopes }
+
+이 의존성 트리와 스코프를 다시 살펴보겠습니다.
+
+`get_current_active_user` 의존성은 `get_current_user`를 하위 의존성으로 가지므로, `get_current_active_user`에서 선언된 스코프 `"me"`는 `get_current_user`에 전달되는 `security_scopes.scopes`의 요구 스코프 목록에 포함됩니다.
+
+*경로 처리* 자체도 스코프 `"items"`를 선언하므로, 이것 또한 `get_current_user`에 전달되는 `security_scopes.scopes` 목록에 포함됩니다.
+
+의존성과 스코프의 계층 구조는 다음과 같습니다:
+
+* *경로 처리* `read_own_items`는:
+ * 의존성과 함께 요구 스코프 `["items"]`를 가집니다:
+ * `get_current_active_user`:
+ * 의존성 함수 `get_current_active_user`는:
+ * 의존성과 함께 요구 스코프 `["me"]`를 가집니다:
+ * `get_current_user`:
+ * 의존성 함수 `get_current_user`는:
+ * 자체적으로는 요구 스코프가 없습니다.
+ * `oauth2_scheme`를 사용하는 의존성이 있습니다.
+ * `SecurityScopes` 타입의 `security_scopes` 매개변수가 있습니다:
+ * 이 `security_scopes` 매개변수는 위에서 선언된 모든 스코프를 담은 `list`인 `scopes` 속성을 가지므로:
+ * *경로 처리* `read_own_items`의 경우 `security_scopes.scopes`에는 `["me", "items"]`가 들어갑니다.
+ * *경로 처리* `read_users_me`의 경우 `security_scopes.scopes`에는 `["me"]`가 들어갑니다. 이는 의존성 `get_current_active_user`에서 선언되기 때문입니다.
+ * *경로 처리* `read_system_status`의 경우 `security_scopes.scopes`에는 `[]`(없음)가 들어갑니다. `scopes`가 있는 `Security`를 선언하지 않았고, 그 의존성인 `get_current_user`도 `scopes`를 선언하지 않았기 때문입니다.
+
+/// tip | 팁
+
+여기서 중요한 “마법 같은” 점은 `get_current_user`가 각 *경로 처리*마다 검사해야 하는 `scopes` 목록이 달라진다는 것입니다.
+
+이는 특정 *경로 처리*에 대한 의존성 트리에서, 각 *경로 처리*와 각 의존성에 선언된 `scopes`에 따라 달라집니다.
+
+///
+
+## `SecurityScopes`에 대한 추가 설명 { #more-details-about-securityscopes }
+
+`SecurityScopes`는 어느 지점에서든, 그리고 여러 곳에서 사용할 수 있으며, “루트” 의존성에만 있어야 하는 것은 아닙니다.
+
+`SecurityScopes`는 **해당 특정** *경로 처리*와 **해당 특정** 의존성 트리에 대해, 현재 `Security` 의존성과 모든 dependant에 선언된 보안 스코프를 항상 갖고 있습니다.
+
+`SecurityScopes`에는 dependant가 선언한 모든 스코프가 포함되므로, 중앙의 의존성 함수에서 토큰이 필요한 스코프를 가지고 있는지 검증한 다음, 서로 다른 *경로 처리*에서 서로 다른 스코프 요구사항을 선언할 수 있습니다.
+
+이들은 각 *경로 처리*마다 독립적으로 검사됩니다.
+
+## 확인하기 { #check-it }
+
+API 문서를 열면, 인증하고 인가할 스코프를 지정할 수 있습니다.
+
+
+
+어떤 스코프도 선택하지 않으면 “인증”은 되지만, `/users/me/` 또는 `/users/me/items/`에 접근하려고 하면 권한이 충분하지 않다는 오류가 발생합니다. `/status/`에는 여전히 접근할 수 있습니다.
+
+그리고 스코프 `me`는 선택했지만 스코프 `items`는 선택하지 않았다면, `/users/me/`에는 접근할 수 있지만 `/users/me/items/`에는 접근할 수 없습니다.
+
+이는 사용자가 애플리케이션에 얼마나 많은 권한을 부여했는지에 따라, 제3자 애플리케이션이 사용자로부터 제공받은 토큰으로 이 *경로 처리*들 중 하나에 접근하려고 할 때 발생하는 상황과 같습니다.
+
+## 제3자 통합에 대해 { #about-third-party-integrations }
+
+이 예제에서는 OAuth2 “password” 플로우를 사용하고 있습니다.
+
+이는 보통 자체 프론트엔드가 있는 우리 애플리케이션에 로그인할 때 적합합니다.
+
+우리가 이를 통제하므로 `username`과 `password`를 받는 것을 신뢰할 수 있기 때문입니다.
+
+하지만 다른 사람들이 연결할 OAuth2 애플리케이션(즉, Facebook, Google, GitHub 등과 동등한 인증 제공자를 만들고 있다면)을 구축한다면, 다른 플로우 중 하나를 사용해야 합니다.
+
+가장 흔한 것은 implicit 플로우입니다.
+
+가장 안전한 것은 code 플로우이지만, 더 많은 단계가 필요해 구현이 더 복잡합니다. 복잡하기 때문에 많은 제공자는 implicit 플로우를 권장하게 됩니다.
+
+/// note | 참고
+
+인증 제공자마다 자신들의 브랜드의 일부로 만들기 위해, 각 플로우를 서로 다른 방식으로 이름 붙이는 경우가 흔합니다.
+
+하지만 결국, 동일한 OAuth2 표준을 구현하고 있는 것입니다.
+
+///
+
+**FastAPI**는 `fastapi.security.oauth2`에 이러한 모든 OAuth2 인증 플로우를 위한 유틸리티를 포함합니다.
+
+## 데코레이터 `dependencies`에서의 `Security` { #security-in-decorator-dependencies }
+
+[경로 처리 데코레이터의 의존성](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}에서 설명한 것처럼 데코레이터의 `dependencies` 매개변수에 `Depends`의 `list`를 정의할 수 있는 것과 같은 방식으로, 거기에서 `scopes`와 함께 `Security`를 사용할 수도 있습니다.
diff --git a/docs/ko/docs/advanced/settings.md b/docs/ko/docs/advanced/settings.md
new file mode 100644
index 000000000..6fa7c644c
--- /dev/null
+++ b/docs/ko/docs/advanced/settings.md
@@ -0,0 +1,302 @@
+# 설정과 환경 변수 { #settings-and-environment-variables }
+
+많은 경우 애플리케이션에는 외부 설정이나 구성(예: secret key, 데이터베이스 자격 증명, 이메일 서비스 자격 증명 등)이 필요할 수 있습니다.
+
+이러한 설정 대부분은 데이터베이스 URL처럼 변동 가능(변경될 수 있음)합니다. 그리고 많은 설정은 secret처럼 민감할 수 있습니다.
+
+이 때문에 보통 애플리케이션이 읽어들이는 환경 변수로 이를 제공하는 것이 일반적입니다.
+
+/// tip | 팁
+
+환경 변수를 이해하려면 [환경 변수](../environment-variables.md){.internal-link target=_blank}를 읽어보세요.
+
+///
+
+## 타입과 검증 { #types-and-validation }
+
+이 환경 변수들은 Python 외부에 있으며 다른 프로그램 및 시스템의 나머지 부분(그리고 Linux, Windows, macOS 같은 서로 다른 운영체제와도)과 호환되어야 하므로, 텍스트 문자열만 다룰 수 있습니다.
+
+즉, Python에서 환경 변수로부터 읽어온 어떤 값이든 `str`이 되며, 다른 타입으로의 변환이나 검증은 코드에서 수행해야 합니다.
+
+## Pydantic `Settings` { #pydantic-settings }
+
+다행히 Pydantic은 Pydantic: Settings management를 통해 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 제공합니다.
+
+### `pydantic-settings` 설치하기 { #install-pydantic-settings }
+
+먼저 [가상 환경](../virtual-environments.md){.internal-link target=_blank}을 만들고 활성화한 다음, `pydantic-settings` 패키지를 설치하세요:
+
+
+
-다음으로, http://127.0.0.1:8000/subapi/docs에서 하위 응용프로그램의 문서를 여십시오.
+그 다음, http://127.0.0.1:8000/subapi/docs에서 하위 응용프로그램의 문서를 여세요.
-하위 경로 접두사 `/subapi` 아래에 선언된 *경로 동작* 을 포함하는, 하위 응용프로그램에 대한 자동 API 문서를 확인할 수 있습니다:
+하위 응용프로그램의 자동 API 문서를 보게 될 것이며, 하위 경로 접두사 `/subapi` 아래에 올바르게 포함된 하위 응용프로그램 자체의 _경로 처리_만 포함됩니다:
-
+
-두 사용자 인터페이스 중 어느 하나를 사용해야하는 경우, 브라우저는 특정 응용프로그램 또는 하위 응용프로그램과 각각 통신할 수 있기 때문에 올바르게 동작할 것입니다.
+두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 앱 또는 하위 앱과 통신할 수 있기 때문입니다.
-### 기술적 세부사항: `root_path`
+### 기술적 세부사항: `root_path` { #technical-details-root-path }
-위에 설명된 것과 같이 하위 응용프로그램을 마운트하는 경우, FastAPI는 `root_path`라고 하는 ASGI 명세의 매커니즘을 사용하여 하위 응용프로그램에 대한 마운트 경로 통신을 처리합니다.
+위에서 설명한 대로 하위 응용프로그램을 마운트하면, FastAPI는 ASGI 명세의 메커니즘인 `root_path`를 사용해 하위 응용프로그램에 대한 마운트 경로를 전달하는 작업을 처리합니다.
-이를 통해, 하위 응용프로그램은 문서 UI를 위해 경로 접두사를 사용해야 한다는 사실을 인지합니다.
+이렇게 하면 하위 응용프로그램은 문서 UI를 위해 해당 경로 접두사를 사용해야 한다는 것을 알게 됩니다.
-하위 응용프로그램에도 역시 다른 하위 응용프로그램을 마운트하는 것이 가능하며 FastAPI가 모든 `root_path` 들을 자동적으로 처리하기 때문에 모든 것은 올바르게 동작할 것입니다.
+또한 하위 응용프로그램도 자체적으로 하위 앱을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다.
-`root_path`와 이것을 사용하는 방법에 대해서는 [프록시의 뒷단](./behind-a-proxy.md){.internal-link target=_blank} 섹션에서 배울 수 있습니다.
+`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
index 4cb4cbe0d..fffffa6a5 100644
--- a/docs/ko/docs/advanced/templates.md
+++ b/docs/ko/docs/advanced/templates.md
@@ -1,4 +1,4 @@
-# 템플릿
+# 템플릿 { #templates }
**FastAPI**와 함께 원하는 어떤 템플릿 엔진도 사용할 수 있습니다.
@@ -6,10 +6,9 @@
설정을 쉽게 할 수 있는 유틸리티가 있으며, 이를 **FastAPI** 애플리케이션에서 직접 사용할 수 있습니다(Starlette 제공).
-## 의존성 설치
-
-가상 환경을 생성하고(virtual environment{.internal-link target=_blank}), 활성화한 후 jinja2를 설치해야 합니다:
+## 의존성 설치 { #install-dependencies }
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고, 활성화한 후 `jinja2`를 설치해야 합니다:
-**FastAPI** WebSocket 응용 프로그램이 응답을 돌려줄 것입니다:
+그리고 WebSockets가 포함된 **FastAPI** 응용 프로그램이 응답을 돌려줄 것입니다:
@@ -94,9 +94,9 @@ $ fastapi dev main.py
-모든 메시지는 동일한 WebSocket 연결을 사용합니다.
+그리고 모든 메시지는 동일한 WebSocket 연결을 사용합니다.
-## `Depends` 및 기타 사용하기
+## `Depends` 및 기타 사용하기 { #using-depends-and-others }
WebSocket 엔드포인트에서 `fastapi`에서 다음을 가져와 사용할 수 있습니다:
@@ -107,21 +107,21 @@ WebSocket 엔드포인트에서 `fastapi`에서 다음을 가져와 사용할
* `Path`
* `Query`
-이들은 다른 FastAPI 엔드포인트/*경로 작동*과 동일하게 동작합니다:
+이들은 다른 FastAPI 엔드포인트/*경로 처리*와 동일하게 동작합니다:
{* ../../docs_src/websockets/tutorial002_an_py310.py hl[68:69,82] *}
/// info | 정보
-WebSocket에서는 `HTTPException`을 발생시키는 것이 적합하지 않습니다. 대신 `WebSocketException`을 발생시킵니다.
+WebSocket이기 때문에 `HTTPException`을 발생시키는 것은 적절하지 않습니다. 대신 `WebSocketException`을 발생시킵니다.
명세서에 정의된 유효한 코드를 사용하여 종료 코드를 설정할 수 있습니다.
///
-### 종속성을 가진 WebSockets 테스트
+### 종속성을 가진 WebSockets 시도해보기 { #try-the-websockets-with-dependencies }
-파일 이름이 `main.py`라고 가정하고 응용 프로그램을 실행합니다:
+파일 이름이 `main.py`라고 가정하고 다음으로 응용 프로그램을 실행합니다:
-## 연결 해제 및 다중 클라이언트 처리
+## 연결 해제 및 다중 클라이언트 처리 { #handling-disconnections-and-multiple-clients }
-WebSocket 연결이 닫히면, `await websocket.receive_text()`가 `WebSocketDisconnect` 예외를 발생시킵니다. 이를 잡아 처리할 수 있습니다:
+WebSocket 연결이 닫히면, `await websocket.receive_text()`가 `WebSocketDisconnect` 예외를 발생시킵니다. 그러면 이 예제처럼 이를 잡아 처리할 수 있습니다.
{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
@@ -160,7 +160,7 @@ WebSocket 연결이 닫히면, `await websocket.receive_text()`가 `WebSocketDis
* 여러 브라우저 탭에서 앱을 엽니다.
* 각 탭에서 메시지를 작성합니다.
-* 한 탭을 닫아보세요.
+* 그런 다음 탭 중 하나를 닫아보세요.
`WebSocketDisconnect` 예외가 발생하며, 다른 모든 클라이언트가 다음과 같은 메시지를 수신합니다:
@@ -170,17 +170,17 @@ Client #1596980209979 left the chat
/// tip | 팁
-위 응용 프로그램은 여러 WebSocket 연결에 메시지를 브로드캐스트하는 방법을 보여주는 간단한 예제입니다.
+위 앱은 여러 WebSocket 연결에 메시지를 처리하고 브로드캐스트하는 방법을 보여주는 최소한의 간단한 예제입니다.
-그러나 모든 것을 메모리의 단일 리스트로 처리하므로, 프로세스가 실행 중인 동안만 동작하며 단일 프로세스에서만 작동합니다.
+하지만 모든 것을 메모리의 단일 리스트로 처리하므로, 프로세스가 실행 중인 동안만 동작하며 단일 프로세스에서만 작동한다는 점을 기억하세요.
-FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL 등을 지원하는 도구를 찾고 있다면, encode/broadcaster를 확인하세요.
+FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL 등을 지원하는 도구가 필요하다면, encode/broadcaster를 확인하세요.
///
-## 추가 정보
+## 추가 정보 { #more-info }
-다음 옵션에 대한 자세한 내용을 보려면 Starlette의 문서를 확인하세요:
+다음 옵션에 대해 더 알아보려면 Starlette의 문서를 확인하세요:
-* `WebSocket` 클래스.
-* 클래스 기반 WebSocket 처리.
+* `WebSocket` 클래스.
+* 클래스 기반 WebSocket 처리.
diff --git a/docs/ko/docs/advanced/wsgi.md b/docs/ko/docs/advanced/wsgi.md
index 3e9de3e6c..89cf57cfe 100644
--- a/docs/ko/docs/advanced/wsgi.md
+++ b/docs/ko/docs/advanced/wsgi.md
@@ -1,10 +1,10 @@
-# WSGI 포함하기 - Flask, Django 그 외
+# WSGI 포함하기 - Flask, Django 그 외 { #including-wsgi-flask-django-others }
-[서브 응용 프로그램 - 마운트](sub-applications.md){.internal-link target=_blank}, [프록시 뒤편에서](behind-a-proxy.md){.internal-link target=_blank}에서 보았듯이 WSGI 응용 프로그램들을 다음과 같이 마운트 할 수 있습니다.
+[서브 응용 프로그램 - 마운트](sub-applications.md){.internal-link target=_blank}, [프록시 뒤편에서](behind-a-proxy.md){.internal-link target=_blank}에서 보았듯이 WSGI 응용 프로그램들을 마운트 할 수 있습니다.
-`WSGIMiddleware`를 사용하여 WSGI 응용 프로그램(예: Flask, Django 등)을 감쌀 수 있습니다.
+이를 위해 `WSGIMiddleware`를 사용해 WSGI 응용 프로그램(예: Flask, Django 등)을 감쌀 수 있습니다.
-## `WSGIMiddleware` 사용하기
+## `WSGIMiddleware` 사용하기 { #using-wsgimiddleware }
`WSGIMiddleware`를 불러와야 합니다.
@@ -12,9 +12,9 @@
그 후, 해당 경로에 마운트합니다.
-{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *}
+{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *}
-## 확인하기
+## 확인하기 { #check-it }
이제 `/v1/` 경로에 있는 모든 요청은 Flask 응용 프로그램에서 처리됩니다.
@@ -26,7 +26,7 @@
Hello, World from Flask!
```
-그리고 다음으로 이동하면 http://localhost:8000/v2 Flask의 응답을 볼 수 있습니다:
+그리고 다음으로 이동하면 http://localhost:8000/v2 **FastAPI**의 응답을 볼 수 있습니다:
```JSON
{
diff --git a/docs/ko/docs/alternatives.md b/docs/ko/docs/alternatives.md
new file mode 100644
index 000000000..d8c2df2d8
--- /dev/null
+++ b/docs/ko/docs/alternatives.md
@@ -0,0 +1,485 @@
+# 대안, 영감, 비교 { #alternatives-inspiration-and-comparisons }
+
+**FastAPI**에 영감을 준 것들, 대안과의 비교, 그리고 그로부터 무엇을 배웠는지에 대한 내용입니다.
+
+## 소개 { #intro }
+
+다른 사람들의 이전 작업이 없었다면 **FastAPI**는 존재하지 않았을 것입니다.
+
+그 전에 만들어진 많은 도구들이 **FastAPI**의 탄생에 영감을 주었습니다.
+
+저는 여러 해 동안 새로운 framework를 만드는 것을 피하고 있었습니다. 먼저 **FastAPI**가 다루는 모든 기능을 여러 서로 다른 framework, plug-in, 도구를 사용해 해결해 보려고 했습니다.
+
+하지만 어느 시점에는, 이전 도구들의 가장 좋은 아이디어를 가져와 가능한 최선의 방식으로 조합하고, 이전에는 존재하지 않았던 언어 기능(Python 3.6+ type hints)을 활용해 이 모든 기능을 제공하는 무언가를 만드는 것 외에는 다른 선택지가 없었습니다.
+
+## 이전 도구들 { #previous-tools }
+
+### Django { #django }
+
+가장 인기 있는 Python framework이며 널리 신뢰받고 있습니다. Instagram 같은 시스템을 만드는 데 사용됩니다.
+
+상대적으로 관계형 데이터베이스(예: MySQL 또는 PostgreSQL)와 강하게 결합되어 있어서, NoSQL 데이터베이스(예: Couchbase, MongoDB, Cassandra 등)를 주 저장 엔진으로 사용하는 것은 그리 쉽지 않습니다.
+
+백엔드에서 HTML을 생성하기 위해 만들어졌지, 현대적인 프런트엔드(예: React, Vue.js, Angular)나 다른 시스템(예: IoT 기기)에서 사용되는 API를 만들기 위해 설계된 것은 아닙니다.
+
+### Django REST Framework { #django-rest-framework }
+
+Django REST framework는 Django를 기반으로 Web API를 구축하기 위한 유연한 toolkit으로 만들어졌고, Django의 API 기능을 개선하기 위한 목적이었습니다.
+
+Mozilla, Red Hat, Eventbrite를 포함해 많은 회사에서 사용합니다.
+
+**자동 API 문서화**의 초기 사례 중 하나였고, 이것이 특히 **FastAPI**를 "찾게 된" 첫 아이디어 중 하나였습니다.
+
+/// note | 참고
+
+Django REST Framework는 Tom Christie가 만들었습니다. **FastAPI**의 기반이 되는 Starlette와 Uvicorn을 만든 사람과 동일합니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+자동 API 문서화 웹 사용자 인터페이스를 제공하기.
+
+///
+
+### Flask { #flask }
+
+Flask는 "microframework"로, Django에 기본으로 포함된 데이터베이스 통합이나 여러 기능들을 포함하지 않습니다.
+
+이 단순함과 유연성 덕분에 NoSQL 데이터베이스를 주 데이터 저장 시스템으로 사용하는 같은 작업이 가능합니다.
+
+매우 단순하기 때문에 비교적 직관적으로 배울 수 있지만, 문서가 어떤 지점에서는 다소 기술적으로 깊어지기도 합니다.
+
+또한 데이터베이스, 사용자 관리, 혹은 Django에 미리 구축되어 있는 다양한 기능들이 꼭 필요하지 않은 다른 애플리케이션에도 흔히 사용됩니다. 물론 이런 기능들 중 다수는 plug-in으로 추가할 수 있습니다.
+
+이런 구성요소의 분리와, 필요한 것만 정확히 덧붙여 확장할 수 있는 "microframework"라는 점은 제가 유지하고 싶었던 핵심 특성이었습니다.
+
+Flask의 단순함을 고려하면 API를 구축하는 데 잘 맞는 것처럼 보였습니다. 다음으로 찾고자 했던 것은 Flask용 "Django REST Framework"였습니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+micro-framework가 되기. 필요한 도구와 구성요소를 쉽게 조합할 수 있도록 하기.
+
+단순하고 사용하기 쉬운 routing 시스템을 갖기.
+
+///
+
+### Requests { #requests }
+
+**FastAPI**는 실제로 **Requests**의 대안이 아닙니다. 둘의 범위는 매우 다릅니다.
+
+실제로 FastAPI 애플리케이션 *내부에서* Requests를 사용하는 경우도 흔합니다.
+
+그럼에도 FastAPI는 Requests로부터 꽤 많은 영감을 얻었습니다.
+
+**Requests**는 (클라이언트로서) API와 *상호작용*하기 위한 라이브러리이고, **FastAPI**는 (서버로서) API를 *구축*하기 위한 라이브러리입니다.
+
+대략 말하면 서로 반대편에 있으며, 서로를 보완합니다.
+
+Requests는 매우 단순하고 직관적인 설계를 가졌고, 합리적인 기본값을 바탕으로 사용하기가 아주 쉽습니다. 동시에 매우 강력하고 커스터마이징도 가능합니다.
+
+그래서 공식 웹사이트에서 말하듯이:
+
+> Requests is one of the most downloaded Python packages of all time
+
+사용 방법은 매우 간단합니다. 예를 들어 `GET` 요청을 하려면 다음처럼 작성합니다:
+
+```Python
+response = requests.get("http://example.com/some/url")
+```
+
+이에 대응하는 FastAPI의 API *경로 처리*는 다음과 같이 보일 수 있습니다:
+
+```Python hl_lines="1"
+@app.get("/some/url")
+def read_url():
+ return {"message": "Hello World"}
+```
+
+`requests.get(...)`와 `@app.get(...)`의 유사성을 확인해 보세요.
+
+/// check | **FastAPI**에 영감을 준 것
+
+* 단순하고 직관적인 API를 갖기.
+* HTTP method 이름(operations)을 직접, 직관적이고 명확한 방식으로 사용하기.
+* 합리적인 기본값을 제공하되, 강력한 커스터마이징을 가능하게 하기.
+
+///
+
+### Swagger / OpenAPI { #swagger-openapi }
+
+제가 Django REST Framework에서 가장 원했던 주요 기능은 자동 API 문서화였습니다.
+
+그 후 JSON(또는 JSON의 확장인 YAML)을 사용해 API를 문서화하는 표준인 Swagger가 있다는 것을 알게 되었습니다.
+
+그리고 Swagger API를 위한 웹 사용자 인터페이스도 이미 만들어져 있었습니다. 그래서 API에 대한 Swagger 문서를 생성할 수 있다면, 이 웹 사용자 인터페이스를 자동으로 사용할 수 있게 됩니다.
+
+어느 시점에 Swagger는 Linux Foundation으로 넘어가 OpenAPI로 이름이 바뀌었습니다.
+
+그래서 2.0 버전을 이야기할 때는 "Swagger"라고 말하는 것이 일반적이고, 3+ 버전은 "OpenAPI"라고 말하는 것이 일반적입니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+커스텀 schema 대신, API 사양을 위한 열린 표준을 채택하고 사용하기.
+
+또한 표준 기반의 사용자 인터페이스 도구를 통합하기:
+
+* Swagger UI
+* ReDoc
+
+이 두 가지는 꽤 대중적이고 안정적이기 때문에 선택되었습니다. 하지만 간단히 검색해보면 OpenAPI를 위한 대안 UI가 수십 가지나 있다는 것을 알 수 있습니다(**FastAPI**와 함께 사용할 수 있습니다).
+
+///
+
+### Flask REST framework들 { #flask-rest-frameworks }
+
+Flask REST framework는 여러 개가 있지만, 시간을 들여 조사해 본 결과, 상당수가 중단되었거나 방치되어 있었고, 해결되지 않은 여러 이슈 때문에 적합하지 않은 경우가 많았습니다.
+
+### Marshmallow { #marshmallow }
+
+API 시스템에 필요한 주요 기능 중 하나는 데이터 "serialization"입니다. 이는 코드(Python)에서 데이터를 가져와 네트워크로 전송할 수 있는 형태로 변환하는 것을 의미합니다. 예를 들어 데이터베이스의 데이터를 담은 객체를 JSON 객체로 변환하거나, `datetime` 객체를 문자열로 변환하는 등의 작업입니다.
+
+API에 또 하나 크게 필요한 기능은 데이터 검증입니다. 특정 파라미터를 기준으로 데이터가 유효한지 확인하는 것입니다. 예를 들어 어떤 필드가 `int`인지, 임의의 문자열이 아닌지 확인하는 식입니다. 이는 특히 들어오는 데이터에 유용합니다.
+
+데이터 검증 시스템이 없다면, 모든 검사를 코드에서 수동으로 해야 합니다.
+
+이런 기능들을 제공하기 위해 Marshmallow가 만들어졌습니다. 훌륭한 라이브러리이며, 저도 이전에 많이 사용했습니다.
+
+하지만 Python type hints가 존재하기 전에 만들어졌습니다. 그래서 각 schema를 정의하려면 Marshmallow가 제공하는 특정 유틸리티와 클래스를 사용해야 합니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+데이터 타입과 검증을 제공하는 "schema"를 코드로 정의하고, 이를 자동으로 활용하기.
+
+///
+
+### Webargs { #webargs }
+
+API에 필요한 또 다른 큰 기능은 들어오는 요청에서 데이터를 parsing하는 것입니다.
+
+Webargs는 Flask를 포함한 여러 framework 위에서 이를 제공하기 위해 만들어진 도구입니다.
+
+내부적으로 Marshmallow를 사용해 데이터 검증을 수행합니다. 그리고 같은 개발자들이 만들었습니다.
+
+아주 훌륭한 도구이며, 저도 **FastAPI**를 만들기 전에 많이 사용했습니다.
+
+/// info | 정보
+
+Webargs는 Marshmallow와 같은 개발자들이 만들었습니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+들어오는 요청 데이터의 자동 검증을 갖기.
+
+///
+
+### APISpec { #apispec }
+
+Marshmallow와 Webargs는 plug-in 형태로 검증, parsing, serialization을 제공합니다.
+
+하지만 문서화는 여전히 부족했습니다. 그래서 APISpec이 만들어졌습니다.
+
+이는 여러 framework를 위한 plug-in이며(Starlette용 plug-in도 있습니다).
+
+작동 방식은, 각 route를 처리하는 함수의 docstring 안에 YAML 형식으로 schema 정의를 작성하고,
+
+그로부터 OpenAPI schema를 생성합니다.
+
+Flask, Starlette, Responder 등에서 이런 방식으로 동작합니다.
+
+하지만 다시, Python 문자열 내부(큰 YAML)에서 micro-syntax를 다루어야 한다는 문제가 있습니다.
+
+에디터가 이를 크게 도와주지 못합니다. 또한 파라미터나 Marshmallow schema를 수정해놓고 YAML docstring도 같이 수정하는 것을 잊어버리면, 생성된 schema는 오래된 상태가 됩니다.
+
+/// info | 정보
+
+APISpec은 Marshmallow와 같은 개발자들이 만들었습니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+API를 위한 열린 표준인 OpenAPI를 지원하기.
+
+///
+
+### Flask-apispec { #flask-apispec }
+
+Flask plug-in으로, Webargs, Marshmallow, APISpec을 묶어줍니다.
+
+Webargs와 Marshmallow의 정보를 사용해 APISpec으로 OpenAPI schema를 자동 생성합니다.
+
+훌륭한 도구인데도 과소평가되어 있습니다. 다른 많은 Flask plug-in보다 훨씬 더 유명해져야 합니다. 문서가 너무 간결하고 추상적이라서 그럴 수도 있습니다.
+
+이 도구는 Python docstring 내부에 YAML(또 다른 문법)을 작성해야 하는 문제를 해결했습니다.
+
+Flask + Flask-apispec + Marshmallow + Webargs 조합은 **FastAPI**를 만들기 전까지 제가 가장 좋아하던 백엔드 stack이었습니다.
+
+이를 사용하면서 여러 Flask full-stack generator가 만들어졌습니다. 이것들이 지금까지 저(그리고 여러 외부 팀)가 사용해 온 주요 stack입니다:
+
+* https://github.com/tiangolo/full-stack
+* https://github.com/tiangolo/full-stack-flask-couchbase
+* https://github.com/tiangolo/full-stack-flask-couchdb
+
+그리고 이 동일한 full-stack generator들이 [**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}의 기반이 되었습니다.
+
+/// info | 정보
+
+Flask-apispec은 Marshmallow와 같은 개발자들이 만들었습니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+serialization과 validation을 정의하는 동일한 코드로부터 OpenAPI schema를 자동 생성하기.
+
+///
+
+### NestJS (그리고 Angular) { #nestjs-and-angular }
+
+이건 Python도 아닙니다. NestJS는 Angular에서 영감을 받은 JavaScript(TypeScript) NodeJS framework입니다.
+
+Flask-apispec으로 할 수 있는 것과 어느 정도 비슷한 것을 달성합니다.
+
+Angular 2에서 영감을 받은 의존성 주입 시스템이 통합되어 있습니다. 제가 아는 다른 의존성 주입 시스템들처럼 "injectable"을 사전에 등록해야 하므로, 장황함과 코드 반복이 늘어납니다.
+
+파라미터가 TypeScript 타입(Python type hints와 유사함)으로 설명되기 때문에 에디터 지원은 꽤 좋습니다.
+
+하지만 TypeScript 데이터는 JavaScript로 컴파일된 뒤에는 보존되지 않기 때문에, 타입에 의존해 검증, serialization, 문서화를 동시에 정의할 수 없습니다. 이 점과 일부 설계 결정 때문에, 검증/serialization/자동 schema 생성을 하려면 여러 곳에 decorator를 추가해야 하며, 결과적으로 매우 장황해집니다.
+
+중첩 모델을 잘 처리하지 못합니다. 즉, 요청의 JSON body가 내부 필드를 가진 JSON 객체이고 그 내부 필드들이 다시 중첩된 JSON 객체인 경우, 제대로 문서화하고 검증할 수 없습니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+Python 타입을 사용해 뛰어난 에디터 지원을 제공하기.
+
+강력한 의존성 주입 시스템을 갖추기. 코드 반복을 최소화하는 방법을 찾기.
+
+///
+
+### Sanic { #sanic }
+
+`asyncio` 기반의 매우 빠른 Python framework 중 초기 사례였습니다. Flask와 매우 유사하게 만들어졌습니다.
+
+/// note | 기술 세부사항
+
+기본 Python `asyncio` 루프 대신 `uvloop`를 사용했습니다. 이것이 매우 빠르게 만든 요인입니다.
+
+이는 Uvicorn과 Starlette에 명확히 영감을 주었고, 현재 공개 benchmark에서는 이 둘이 Sanic보다 더 빠릅니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+미친 성능을 낼 수 있는 방법을 찾기.
+
+그래서 **FastAPI**는 Starlette를 기반으로 합니다. Starlette는 사용 가능한 framework 중 가장 빠르기 때문입니다(서드파티 benchmark로 테스트됨).
+
+///
+
+### Falcon { #falcon }
+
+Falcon은 또 다른 고성능 Python framework로, 최소한으로 설계되었고 Hug 같은 다른 framework의 기반으로 동작하도록 만들어졌습니다.
+
+함수가 두 개의 파라미터(하나는 "request", 하나는 "response")를 받도록 설계되어 있습니다. 그런 다음 request에서 일부를 "읽고", response에 일부를 "작성"합니다. 이 설계 때문에, 표준 Python type hints를 함수 파라미터로 사용해 요청 파라미터와 body를 선언하는 것이 불가능합니다.
+
+따라서 데이터 검증, serialization, 문서화는 자동으로 되지 않고 코드로 해야 합니다. 또는 Hug처럼 Falcon 위에 framework를 얹어 구현해야 합니다. request 객체 하나와 response 객체 하나를 파라미터로 받는 Falcon의 설계에서 영감을 받은 다른 framework에서도 같은 구분이 나타납니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+훌륭한 성능을 얻는 방법을 찾기.
+
+Hug(= Falcon 기반)과 함께, 함수에서 `response` 파라미터를 선언하도록 **FastAPI**에 영감을 주었습니다.
+
+다만 FastAPI에서는 선택 사항이며, 주로 헤더, 쿠키, 그리고 대체 status code를 설정하는 데 사용됩니다.
+
+///
+
+### Molten { #molten }
+
+**FastAPI**를 만들기 시작한 초기 단계에서 Molten을 알게 되었고, 꽤 비슷한 아이디어를 갖고 있었습니다:
+
+* Python type hints 기반
+* 이 타입으로부터 검증과 문서화 생성
+* 의존성 주입 시스템
+
+Pydantic 같은 서드파티 라이브러리를 사용해 데이터 검증/serialization/문서화를 하지 않고 자체 구현을 사용합니다. 그래서 이런 데이터 타입 정의를 쉽게 재사용하기는 어렵습니다.
+
+조금 더 장황한 설정이 필요합니다. 또한 WSGI(ASGI가 아니라) 기반이므로, Uvicorn, Starlette, Sanic 같은 도구가 제공하는 고성능을 활용하도록 설계되지 않았습니다.
+
+의존성 주입 시스템은 의존성을 사전에 등록해야 하고, 선언된 타입을 기반으로 의존성을 해결합니다. 따라서 특정 타입을 제공하는 "component"를 두 개 이상 선언할 수 없습니다.
+
+Route는 한 곳에서 선언하고, 다른 곳에 선언된 함수를 사용합니다(엔드포인트를 처리하는 함수 바로 위에 둘 수 있는 decorator를 사용하는 대신). 이는 Flask(및 Starlette)보다는 Django 방식에 가깝습니다. 코드에서 상대적으로 강하게 결합된 것들을 분리해 놓습니다.
+
+/// check | **FastAPI**에 영감을 준 것
+
+모델 속성의 "default" 값으로 데이터 타입에 대한 추가 검증을 정의하기. 이는 에디터 지원을 개선하며, 이전에는 Pydantic에 없었습니다.
+
+이것은 실제로 Pydantic의 일부를 업데이트하여 같은 검증 선언 스타일을 지원하도록 하는 데 영감을 주었습니다(이 기능은 이제 Pydantic에 이미 포함되어 있습니다).
+
+///
+
+### Hug { #hug }
+
+Hug는 Python type hints를 사용해 API 파라미터 타입을 선언하는 기능을 구현한 초기 framework 중 하나였습니다. 이는 다른 도구들도 같은 방식을 하도록 영감을 준 훌륭한 아이디어였습니다.
+
+표준 Python 타입 대신 커스텀 타입을 선언에 사용했지만, 여전히 큰 진전이었습니다.
+
+또한 전체 API를 JSON으로 선언하는 커스텀 schema를 생성한 초기 framework 중 하나였습니다.
+
+OpenAPI나 JSON Schema 같은 표준을 기반으로 하지 않았기 때문에 Swagger UI 같은 다른 도구와 통합하는 것은 직관적이지 않았습니다. 하지만 역시 매우 혁신적인 아이디어였습니다.
+
+흥미롭고 흔치 않은 기능이 하나 있습니다. 같은 framework로 API뿐 아니라 CLI도 만들 수 있습니다.
+
+동기식 Python 웹 framework의 이전 표준(WSGI) 기반이어서 Websockets와 다른 것들을 처리할 수는 없지만, 성능은 여전히 높습니다.
+
+/// info | 정보
+
+Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 `isort`의 제작자이기도 합니다.
+
+///
+
+/// check | **FastAPI**에 영감을 준 아이디어들
+
+Hug는 APIStar의 일부에 영감을 주었고, 저는 APIStar와 함께 Hug를 가장 유망한 도구 중 하나로 보았습니다.
+
+Hug는 Python type hints로 파라미터를 선언하고, API를 정의하는 schema를 자동으로 생성하도록 **FastAPI**에 영감을 주었습니다.
+
+Hug는 헤더와 쿠키를 설정하기 위해 함수에 `response` 파라미터를 선언하도록 **FastAPI**에 영감을 주었습니다.
+
+///
+
+### APIStar (<= 0.5) { #apistar-0-5 }
+
+**FastAPI**를 만들기로 결정하기 직전에 **APIStar** 서버를 발견했습니다. 찾고 있던 거의 모든 것을 갖추고 있었고 설계도 훌륭했습니다.
+
+NestJS와 Molten보다 앞서, Python type hints를 사용해 파라미터와 요청을 선언하는 framework 구현을 제가 처음 본 사례들 중 하나였습니다. Hug와 거의 같은 시기에 발견했습니다. 하지만 APIStar는 OpenAPI 표준을 사용했습니다.
+
+여러 위치에서 동일한 type hints를 기반으로 자동 데이터 검증, 데이터 serialization, OpenAPI schema 생성을 제공했습니다.
+
+Body schema 정의는 Pydantic처럼 동일한 Python type hints를 사용하지는 않았고 Marshmallow와 조금 더 비슷해서 에디터 지원은 그만큼 좋지 않았지만, 그래도 APIStar는 당시 사용할 수 있는 최선의 선택지였습니다.
+
+당시 최고의 성능 benchmark를 가졌습니다(Starlette에 의해서만 추월됨).
+
+처음에는 자동 API 문서화 웹 UI가 없었지만, Swagger UI를 추가할 수 있다는 것을 알고 있었습니다.
+
+의존성 주입 시스템도 있었습니다. 위에서 언급한 다른 도구들처럼 component의 사전 등록이 필요했지만, 여전히 훌륭한 기능이었습니다.
+
+보안 통합이 없어서 전체 프로젝트에서 사용해 볼 수는 없었습니다. 그래서 Flask-apispec 기반 full-stack generator로 갖추고 있던 모든 기능을 대체할 수 없었습니다. 그 기능을 추가하는 pull request를 만드는 것이 제 백로그에 있었습니다.
+
+하지만 이후 프로젝트의 초점이 바뀌었습니다.
+
+더 이상 API web framework가 아니게 되었는데, 제작자가 Starlette에 집중해야 했기 때문입니다.
+
+이제 APIStar는 web framework가 아니라 OpenAPI 사양을 검증하기 위한 도구 모음입니다.
+
+/// info | 정보
+
+APIStar는 Tom Christie가 만들었습니다. 다음을 만든 사람과 동일합니다:
+
+* Django REST Framework
+* Starlette(**FastAPI**의 기반)
+* Uvicorn(Starlette와 **FastAPI**에서 사용)
+
+///
+
+/// check | **FastAPI**에 영감을 준 것
+
+존재하게 만들기.
+
+동일한 Python 타입으로 여러 가지(데이터 검증, serialization, 문서화)를 선언하면서 동시에 뛰어난 에디터 지원을 제공한다는 아이디어는 제가 매우 훌륭하다고 생각했습니다.
+
+그리고 오랫동안 비슷한 framework를 찾아 여러 대안을 테스트한 끝에, APIStar가 그때 이용 가능한 최선의 선택지였습니다.
+
+그 후 APIStar 서버가 더는 존재하지 않게 되고 Starlette가 만들어졌는데, 이는 그런 시스템을 위한 더 새롭고 더 나은 기반이었습니다. 이것이 **FastAPI**를 만들게 된 최종 영감이었습니다.
+
+저는 **FastAPI**를 APIStar의 "정신적 후계자"로 생각합니다. 동시에, 이 모든 이전 도구들에서 배운 것들을 바탕으로 기능, typing 시스템, 그리고 다른 부분들을 개선하고 확장했습니다.
+
+///
+
+## **FastAPI**가 사용하는 것 { #used-by-fastapi }
+
+### Pydantic { #pydantic }
+
+Pydantic은 Python type hints를 기반으로 데이터 검증, serialization, 문서화(JSON Schema 사용)를 정의하는 라이브러리입니다.
+
+그 덕분에 매우 직관적입니다.
+
+Marshmallow와 비교할 수 있습니다. 다만 benchmark에서 Marshmallow보다 빠릅니다. 그리고 동일한 Python type hints를 기반으로 하므로 에디터 지원도 훌륭합니다.
+
+/// check | **FastAPI**가 이를 사용하는 목적
+
+모든 데이터 검증, 데이터 serialization, 자동 모델 문서화(JSON Schema 기반)를 처리하기.
+
+그 다음 **FastAPI**는 그 JSON Schema 데이터를 가져와 OpenAPI에 포함시키며, 그 외에도 여러 작업을 수행합니다.
+
+///
+
+### Starlette { #starlette }
+
+Starlette는 경량 ASGI framework/toolkit으로, 고성능 asyncio 서비스를 만들기에 이상적입니다.
+
+매우 단순하고 직관적입니다. 쉽게 확장할 수 있도록 설계되었고, 모듈식 component를 갖습니다.
+
+다음이 포함됩니다:
+
+* 정말 인상적인 성능.
+* WebSocket 지원.
+* 프로세스 내 백그라운드 작업.
+* 시작 및 종료 이벤트.
+* HTTPX 기반의 테스트 클라이언트.
+* CORS, GZip, Static Files, Streaming responses.
+* 세션 및 쿠키 지원.
+* 100% 테스트 커버리지.
+* 100% 타입 주석이 달린 코드베이스.
+* 소수의 필수 의존성.
+
+Starlette는 현재 테스트된 Python framework 중 가장 빠릅니다. 단, framework가 아니라 서버인 Uvicorn이 더 빠릅니다.
+
+Starlette는 웹 microframework의 기본 기능을 모두 제공합니다.
+
+하지만 자동 데이터 검증, serialization, 문서화는 제공하지 않습니다.
+
+그것이 **FastAPI**가 위에 추가하는 핵심 중 하나이며, 모두 Python type hints(Pydantic 사용)를 기반으로 합니다. 여기에 더해 의존성 주입 시스템, 보안 유틸리티, OpenAPI schema 생성 등도 포함됩니다.
+
+/// note | 기술 세부사항
+
+ASGI는 Django 코어 팀 멤버들이 개발 중인 새로운 "표준"입니다. 아직 "Python 표준"(PEP)은 아니지만, 그 방향으로 진행 중입니다.
+
+그럼에도 이미 여러 도구에서 "표준"으로 사용되고 있습니다. 이는 상호운용성을 크게 개선합니다. 예를 들어 Uvicorn을 다른 ASGI 서버(예: Daphne 또는 Hypercorn)로 교체할 수도 있고, `python-socketio` 같은 ASGI 호환 도구를 추가할 수도 있습니다.
+
+///
+
+/// check | **FastAPI**가 이를 사용하는 목적
+
+핵심 웹 부분을 모두 처리하기. 그 위에 기능을 추가하기.
+
+`FastAPI` 클래스 자체는 `Starlette` 클래스를 직접 상속합니다.
+
+따라서 Starlette로 할 수 있는 모든 것은 기본적으로 **FastAPI**로도 직접 할 수 있습니다. 즉, **FastAPI**는 사실상 Starlette에 강력한 기능을 더한 것입니다.
+
+///
+
+### Uvicorn { #uvicorn }
+
+Uvicorn은 uvloop과 httptools로 구축된 초고속 ASGI 서버입니다.
+
+web framework가 아니라 서버입니다. 예를 들어 경로 기반 routing을 위한 도구는 제공하지 않습니다. 그런 것은 Starlette(또는 **FastAPI**) 같은 framework가 위에서 제공합니다.
+
+Starlette와 **FastAPI**에서 권장하는 서버입니다.
+
+/// check | **FastAPI**가 이를 권장하는 방식
+
+**FastAPI** 애플리케이션을 실행하기 위한 주요 웹 서버.
+
+또한 `--workers` 커맨드라인 옵션을 사용하면 비동기 멀티프로세스 서버로 실행할 수도 있습니다.
+
+자세한 내용은 [배포](deployment/index.md){.internal-link target=_blank} 섹션을 확인하세요.
+
+///
+
+## 벤치마크와 속도 { #benchmarks-and-speed }
+
+Uvicorn, Starlette, FastAPI 사이의 차이를 이해하고 비교하려면 [벤치마크](benchmarks.md){.internal-link target=_blank} 섹션을 확인하세요.
diff --git a/docs/ko/docs/async.md b/docs/ko/docs/async.md
index ec503d540..36f1ca6bf 100644
--- a/docs/ko/docs/async.md
+++ b/docs/ko/docs/async.md
@@ -1,18 +1,18 @@
-# 동시성과 async / await
+# 동시성과 async / await { #concurrency-and-async-await }
-*경로 작동 함수*에서의 `async def` 문법에 대한 세부사항과 비동기 코드, 동시성 및 병렬성에 대한 배경
+*경로 처리 함수*에서의 `async def` 문법에 대한 세부사항과 비동기 코드, 동시성 및 병렬성에 대한 배경
-## 바쁘신 경우
+## 바쁘신가요? { #in-a-hurry }
-요약
+TL;DR:
-다음과 같이 `await`를 사용해 호출하는 제3의 라이브러리를 사용하는 경우:
+다음과 같이 `await`를 사용해 호출하라고 안내하는 제3자 라이브러리를 사용하는 경우:
```Python
results = await some_library()
```
-다음처럼 *경로 작동 함수*를 `async def`를 사용해 선언하십시오:
+다음처럼 *경로 처리 함수*를 `async def`를 사용해 선언하십시오:
```Python hl_lines="2"
@app.get('/')
@@ -29,7 +29,7 @@ async def read_results():
---
-데이터베이스, API, 파일시스템 등과 의사소통하는 제3의 라이브러리를 사용하고, 그것이 `await`를 지원하지 않는 경우(현재 거의 모든 데이터베이스 라이브러리가 그러합니다), *경로 작동 함수*를 일반적인 `def`를 사용해 선언하십시오:
+데이터베이스, API, 파일시스템 등과 의사소통하는 제3자 라이브러리를 사용하고, 그것이 `await` 사용을 지원하지 않는 경우(현재 대부분의 데이터베이스 라이브러리가 그러합니다), *경로 처리 함수*를 일반적인 `def`를 사용해 선언하십시오:
```Python hl_lines="2"
@app.get('/')
@@ -40,23 +40,23 @@ def results():
---
-만약 당신의 응용프로그램이 (어째서인지) 다른 무엇과 의사소통하고 그것이 응답하기를 기다릴 필요가 없다면 `async def`를 사용하십시오.
+만약 여러분의 애플리케이션이 (어째서인지) 다른 어떤 것과도 통신하고 그 응답을 기다릴 필요가 없다면, 내부에서 `await`를 사용할 필요가 없더라도 `async def`를 사용하세요.
---
-모르겠다면, 그냥 `def`를 사용하십시오.
+잘 모르겠다면, 일반적인 `def`를 사용하세요.
---
-**참고**: *경로 작동 함수*에서 필요한만큼 `def`와 `async def`를 혼용할 수 있고, 가장 알맞은 것을 선택해서 정의할 수 있습니다. FastAPI가 자체적으로 알맞은 작업을 수행할 것입니다.
+**참고**: *경로 처리 함수*에서 필요한 만큼 `def`와 `async def`를 혼용할 수 있으며, 각각에 대해 가장 알맞은 옵션을 선택해 정의하면 됩니다. FastAPI가 올바르게 처리합니다.
-어찌되었든, 상기 어떠한 경우라도, FastAPI는 여전히 비동기적으로 작동하고 매우 빠릅니다.
+어쨌든 위의 어떤 경우에서도 FastAPI는 여전히 비동기적으로 동작하며 매우 빠릅니다.
-그러나 상기 작업을 수행함으로써 어느 정도의 성능 최적화가 가능합니다.
+하지만 위의 단계를 따르면, 몇 가지 성능 최적화를 할 수 있습니다.
-## 기술적 세부사항
+## 기술적 세부사항 { #technical-details }
-최신 파이썬 버전은 `async`와 `await` 문법과 함께 **“코루틴”**이라고 하는 것을 사용하는 **“비동기 코드”**를 지원합니다.
+최신 파이썬 버전은 **“코루틴”**이라고 하는 것을 사용하는 **“비동기 코드”**를 **`async` 및 `await`** 문법과 함께 지원합니다.
아래 섹션들에서 해당 문장을 부분별로 살펴보겠습니다:
@@ -64,251 +64,283 @@ def results():
* **`async`와 `await`**
* **코루틴**
-## 비동기 코드
+## 비동기 코드 { #asynchronous-code }
-비동기 코드란 언어 💬 가 코드의 어느 한 부분에서, 컴퓨터 / 프로그램🤖에게 *다른 무언가*가 어딘가에서 끝날 때까지 기다려야한다고 말하는 방식입니다. *다른 무언가*가 “느린-파일" 📝 이라고 불린다고 가정해봅시다.
+비동기 코드는 언어 💬 가 코드의 어느 한 부분에서 컴퓨터/프로그램 🤖 에게, 어느 시점에는 어딘가에서 *다른 무언가*가 끝날 때까지 기다려야 한다고 말할 수 있는 방법이 있다는 의미입니다. 그 *다른 무언가*를 "slow-file" 📝 이라고 해보겠습니다.
-따라서 “느린-파일” 📝이 끝날때까지 컴퓨터는 다른 작업을 수행할 수 있습니다.
+따라서 그 시간 동안 컴퓨터는 "slow-file" 📝 이 끝나는 동안 다른 작업을 하러 갈 수 있습니다.
-그 다음 컴퓨터 / 프로그램 🤖 은 다시 기다리고 있기 때문에 기회가 있을 때마다 다시 돌아오거나, 혹은 당시에 수행해야하는 작업들이 완료될 때마다 다시 돌아옵니다. 그리고 그것 🤖 은 기다리고 있던 작업 중 어느 것이 이미 완료되었는지, 그것 🤖 이 해야하는 모든 작업을 수행하면서 확인합니다.
+그 다음 컴퓨터/프로그램 🤖 은 다시 기다리는 중이기 때문에 기회가 있을 때마다 돌아오거나, 혹은 그 시점에 해야 할 작업을 모두 끝낼 때마다 돌아옵니다. 그리고 기다리던 작업 중 이미 끝난 것이 있는지 확인하면서, 해야 했던 작업을 수행합니다.
-다음으로, 그것 🤖 은 완료할 첫번째 작업에 착수하고(우리의 "느린-파일" 📝 이라고 가정합시다) 그에 대해 수행해야하는 작업을 계속합니다.
+다음으로, 완료된 첫 번째 작업(우리의 "slow-file" 📝 이라고 해보겠습니다)을 가져와서, 그에 대해 해야 했던 작업을 계속합니다.
-"다른 무언가를 기다리는 것"은 일반적으로 비교적 "느린" (프로세서와 RAM 메모리 속도에 비해) I/O 작업을 의미합니다. 예를 들면 다음의 것들을 기다리는 것입니다:
+이 "다른 무언가를 기다리는 것"은 일반적으로 프로세서와 RAM 메모리 속도에 비해 상대적으로 "느린" I/O 작업을 의미합니다. 예를 들어 다음을 기다리는 것입니다:
-* 네트워크를 통해 클라이언트로부터 전송되는 데이터
-* 네트워크를 통해 클라이언트가 수신할, 당신의 프로그램으로부터 전송되는 데이터
-* 시스템이 읽고 프로그램에 전달할 디스크 내의 파일 내용
-* 당신의 프로그램이 시스템에 전달하는, 디스크에 작성될 내용
+* 네트워크를 통해 클라이언트가 데이터를 보내는 것
+* 네트워크를 통해 클라이언트가 여러분의 프로그램이 보낸 데이터를 받는 것
+* 시스템이 디스크의 파일 내용을 읽어서 프로그램에 전달하는 것
+* 프로그램이 시스템에 전달한 내용을 디스크에 쓰는 것
* 원격 API 작업
-* 완료될 데이터베이스 작업
-* 결과를 반환하는 데이터베이스 쿼리
-* 기타
+* 데이터베이스 작업이 완료되는 것
+* 데이터베이스 쿼리가 결과를 반환하는 것
+* 기타 등등
-수행 시간의 대부분이 I/O 작업을 기다리는데에 소요되기 때문에, "I/O에 묶인" 작업이라고 불립니다.
+실행 시간의 대부분이 I/O 작업을 기다리는 데 소비되기 때문에, 이를 "I/O bound" 작업이라고 부릅니다.
-이것은 "비동기"라고 불리는데 컴퓨터 / 프로그램이 작업 결과를 가지고 일을 수행할 수 있도록, 느린 작업에 "동기화"되어 아무것도 하지 않으면서 작업이 완료될 정확한 시점만을 기다릴 필요가 없기 때문입니다.
+이것은 컴퓨터/프로그램이 느린 작업과 "동기화"되어, 아무것도 하지 않은 채 그 작업이 끝나는 정확한 시점만 기다렸다가 결과를 가져와 일을 계속할 필요가 없기 때문에 "비동기"라고 불립니다.
-이 대신에, "비동기" 시스템에서는, 작업은 일단 완료되면, 컴퓨터 / 프로그램이 수행하고 있는 일을 완료하고 이후 다시 돌아와서 그것의 결과를 받아 이를 사용해 작업을 지속할 때까지 잠시 (몇 마이크로초) 대기할 수 있습니다.
+대신 "비동기" 시스템에서는, 작업이 끝나면 컴퓨터/프로그램이 하러 갔던 일을 마칠 때까지 잠시(몇 마이크로초) 줄에서 기다렸다가, 다시 돌아와 결과를 받아 이를 사용해 작업을 계속할 수 있습니다.
-"동기"("비동기"의 반대)는 컴퓨터 / 프로그램이 상이한 작업들간 전환을 하기 전에 그것이 대기를 동반하게 될지라도 모든 순서를 따르기 때문에 "순차"라는 용어로도 흔히 불립니다.
+"동기"(“비동기”의 반대)는 보통 "순차"라는 용어로도 불리는데, 컴퓨터/프로그램이 다른 작업으로 전환하기 전에 모든 단계를 순서대로 따르기 때문이며, 그 단계들에 기다림이 포함되어 있더라도 마찬가지입니다.
-### 동시성과 버거
+### 동시성과 햄버거 { #concurrency-and-burgers }
-위에서 설명한 **비동기** 코드에 대한 개념은 종종 **"동시성"**이라고도 불립니다. 이것은 **"병렬성"**과는 다릅니다.
+위에서 설명한 **비동기** 코드에 대한 개념은 때때로 **"동시성"**이라고도 불립니다. 이는 **"병렬성"**과는 다릅니다.
-**동시성**과 **병렬성**은 모두 "동시에 일어나는 서로 다른 일들"과 관련이 있습니다.
+**동시성**과 **병렬성**은 모두 "대략 같은 시간에 일어나는 서로 다른 일들"과 관련이 있습니다.
하지만 *동시성*과 *병렬성*의 세부적인 개념에는 꽤 차이가 있습니다.
-차이를 확인하기 위해, 다음의 버거에 대한 이야기를 상상해보십시오:
+차이를 보기 위해, 다음의 햄버거 이야기를 상상해보세요:
-### 동시 버거
+### 동시 햄버거 { #concurrent-burgers }
-당신은 짝사랑 상대 😍 와 패스트푸드 🍔 를 먹으러 갔습니다. 당신은 점원 💁 이 당신 앞에 있는 사람들의 주문을 받을 동안 줄을 서서 기다리고 있습니다.
+여러분은 짝사랑 상대와 패스트푸드를 먹으러 갔고, 점원이 여러분 앞 사람들의 주문을 받는 동안 줄을 서서 기다립니다. 😍
-이제 당신의 순서가 되어서, 당신은 당신과 짝사랑 상대 😍 를 위한 두 개의 고급스러운 버거 🍔 를 주문합니다.
+
-당신이 돈을 냅니다 💸.
+이제 여러분 차례가 되어, 여러분과 짝사랑 상대를 위해 매우 고급스러운 햄버거 2개를 주문합니다. 🍔🍔
-점원 💁 은 주방 👨🍳 에 요리를 하라고 전달하고, 따라서 그들은 당신의 버거 🍔 를 준비해야한다는 사실을 알게됩니다(그들이 지금은 당신 앞 고객들의 주문을 준비하고 있을지라도 말입니다).
+
-점원 💁 은 당신의 순서가 적힌 번호표를 줍니다.
+점원은 주방의 요리사에게 무언가를 말해, (지금은 앞선 손님들의 주문을 준비하고 있더라도) 여러분의 햄버거를 준비해야 한다는 것을 알게 합니다.
-기다리는 동안, 당신은 짝사랑 상대 😍 와 함께 테이블을 고르고, 자리에 앉아 오랫동안 (당신이 주문한 버거는 꽤나 고급스럽기 때문에 준비하는데 시간이 조금 걸립니다 ✨🍔✨) 대화를 나눕니다.
+
-짝사랑 상대 😍 와 테이블에 앉아서 버거 🍔 를 기다리는 동안, 그 사람 😍 이 얼마나 멋지고, 사랑스럽고, 똑똑한지 감탄하며 시간을 보냅니다 ✨😍✨.
+여러분이 돈을 냅니다. 💸
-짝사랑 상대 😍 와 기다리면서 얘기하는 동안, 때때로, 당신은 당신의 차례가 되었는지 보기 위해 카운터의 번호를 확인합니다.
+점원은 여러분 차례 번호를 줍니다.
-그러다 어느 순간, 당신의 차례가 됩니다. 카운터에 가서, 버거 🍔 를 받고, 테이블로 다시 돌아옵니다.
+
-당신과 짝사랑 상대 😍 는 버거 🍔 를 먹으며 좋은 시간을 보냅니다 ✨.
+기다리는 동안, 여러분은 짝사랑 상대와 함께 자리를 고르고 앉아 오랫동안 대화를 나눕니다(여러분의 햄버거는 매우 고급스럽기 때문에 준비하는 데 시간이 좀 걸립니다).
+
+짝사랑 상대와 테이블에 앉아 햄버거를 기다리는 동안, 그 사람이 얼마나 멋지고 귀엽고 똑똑한지 감탄하며 시간을 보낼 수 있습니다 ✨😍✨.
+
+
+
+기다리며 대화하는 동안, 때때로 여러분은 카운터에 표시되는 번호를 확인해 여러분 차례인지 봅니다.
+
+그러다 어느 순간 마침내 여러분 차례가 됩니다. 여러분은 카운터에 가서 햄버거를 받고, 테이블로 돌아옵니다.
+
+
+
+여러분과 짝사랑 상대는 햄버거를 먹으며 좋은 시간을 보냅니다. ✨
+
+
+
+/// info | 정보
+
+아름다운 일러스트: Ketrina Thompson. 🎨
+
+///
---
-당신이 이 이야기에서 컴퓨터 / 프로그램 🤖 이라고 상상해보십시오.
+이 이야기에서 여러분이 컴퓨터/프로그램 🤖 이라고 상상해보세요.
-줄을 서서 기다리는 동안, 당신은 아무것도 하지 않고 😴 당신의 차례를 기다리며, 어떠한 "생산적인" 일도 하지 않습니다. 하지만 점원 💁 이 (음식을 준비하지는 않고) 주문을 받기만 하기 때문에 줄이 빨리 줄어들어서 괜찮습니다.
+줄을 서 있는 동안, 여러분은 그냥 쉬고 😴, 차례를 기다리며, 그다지 "생산적인" 일을 하지 않습니다. 하지만 점원은 주문만 받지(음식을 준비하진 않기) 때문에 줄이 빠르게 줄어들어 괜찮습니다.
-그다음, 당신이 차례가 오면, 당신은 실제로 "생산적인" 일 🤓 을 합니다. 당신은 메뉴를 보고, 무엇을 먹을지 결정하고, 짝사랑 상대 😍 의 선택을 묻고, 돈을 내고 💸 , 맞는 카드를 냈는지 확인하고, 비용이 제대로 지불되었는지 확인하고, 주문이 제대로 들어갔는지 확인을 하는 작업 등등을 수행합니다.
+그 다음 여러분 차례가 되면, 여러분은 실제로 "생산적인" 일을 합니다. 메뉴를 처리하고, 무엇을 먹을지 결정하고, 짝사랑 상대의 선택을 확인하고, 결제하고, 올바른 현금이나 카드를 냈는지 확인하고, 정확히 청구되었는지 확인하고, 주문에 올바른 항목들이 들어갔는지 확인하는 등등을 합니다.
-하지만 이후에는, 버거 🍔 를 아직 받지 못했음에도, 버거가 준비될 때까지 기다려야 🕙 하기 때문에 점원 💁 과의 작업은 "일시정지" ⏸ 상태입니다.
+하지만 그 다음에는, 아직 햄버거를 받지 못했더라도, 햄버거가 준비될 때까지 기다려야 🕙 하므로 점원과의 작업은 "일시정지" ⏸ 상태입니다.
-하지만 번호표를 받고 카운터에서 나와 테이블에 앉으면, 당신은 짝사랑 상대 😍 와 그 "작업" ⏯ 🤓 에 번갈아가며 🔀 집중합니다. 그러면 당신은 다시 짝사랑 상대 😍 에게 작업을 거는 매우 "생산적인" 일 🤓 을 합니다.
+하지만 번호를 들고 카운터에서 벗어나 테이블에 앉으면, 여러분은 짝사랑 상대에게 관심을 전환 🔀 하고, 그에 대한 "작업" ⏯ 🤓 을 할 수 있습니다. 그러면 여러분은 다시 짝사랑 상대에게 작업을 거는 매우 "생산적인" 일을 하게 됩니다 😍.
-점원 💁 이 카운터 화면에 당신의 번호를 표시함으로써 "버거 🍔 가 준비되었습니다"라고 해도, 당신은 즉시 뛰쳐나가지는 않을 것입니다. 당신은 당신의 번호를 갖고있고, 다른 사람들은 그들의 번호를 갖고있기 때문에, 아무도 당신의 버거 🍔 를 훔쳐가지 않는다는 사실을 알기 때문입니다.
+그 다음 점원 💁 이 카운터 화면에 여러분 번호를 띄워 "햄버거를 만들었어요"라고 말하지만, 표시된 번호가 여러분 차례로 바뀌었다고 해서 즉시 미친 듯이 뛰어가지는 않습니다. 여러분은 여러분 번호를 갖고 있고, 다른 사람들은 그들의 번호를 갖고 있으니, 아무도 여러분 햄버거를 훔쳐갈 수 없다는 것을 알기 때문입니다.
-그래서 당신은 짝사랑 상대 😍 가 이야기를 끝낼 때까지 기다린 후 (현재 작업 완료 ⏯ / 진행 중인 작업 처리 🤓 ), 정중하게 미소짓고 버거를 가지러 가겠다고 말합니다 ⏸.
+그래서 여러분은 짝사랑 상대가 이야기를 끝낼 때까지 기다린 다음(현재 작업 ⏯ / 처리 중인 작업 🤓 을 끝내고), 부드럽게 미소 지으며 햄버거를 가지러 가겠다고 말합니다 ⏸.
-그다음 당신은 카운터에 가서 🔀 , 초기 작업을 이제 완료하고 ⏯ , 버거 🍔 를 받고, 감사하다고 말하고 테이블로 가져옵니다. 이로써 카운터와의 상호작용 단계 / 작업이 종료됩니다 ⏹.
+그 다음 여러분은 카운터로 가서 🔀, 이제 끝난 초기 작업 ⏯ 으로 돌아와 햄버거를 받고, 감사 인사를 하고, 테이블로 가져옵니다. 이로써 카운터와 상호작용하는 그 단계/작업이 끝납니다 ⏹. 그리고 이는 새로운 작업인 "햄버거 먹기" 🔀 ⏯ 를 만들지만, 이전 작업인 "햄버거 받기"는 끝났습니다 ⏹.
-이전 작업인 "버거 받기"가 종료되면 ⏹ "버거 먹기"라는 새로운 작업이 생성됩니다 🔀 ⏯.
+### 병렬 햄버거 { #parallel-burgers }
-### 병렬 버거
+이제 이것이 "동시 햄버거"가 아니라 "병렬 햄버거"라고 상상해봅시다.
-이제 "동시 버거"가 아닌 "병렬 버거"를 상상해보십시오.
+여러분은 짝사랑 상대와 함께 병렬 패스트푸드를 먹으러 갑니다.
-당신은 짝사랑 상대 😍 와 함께 병렬 패스트푸드 🍔 를 먹으러 갔습니다.
+여러분은 여러 명(예: 8명)의 점원이 동시에 요리사이기도 하여 여러분 앞 사람들의 주문을 받는 동안 줄을 서 있습니다.
-당신은 여러명(8명이라고 가정합니다)의 점원이 당신 앞 사람들의 주문을 받으며 동시에 요리 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳 도 하는 동안 줄을 서서 기다립니다.
+여러분 앞의 모든 사람들은, 8명의 점원 각각이 다음 주문을 받기 전에 바로 햄버거를 준비하러 가기 때문에, 카운터를 떠나지 않고 햄버거가 준비될 때까지 기다립니다.
-당신 앞 모든 사람들이 버거가 준비될 때까지 카운터에서 떠나지 않고 기다립니다 🕙 . 왜냐하면 8명의 직원들이 다음 주문을 받기 전에 버거를 준비하러 가기 때문입니다.
+
-마침내 당신의 차례가 왔고, 당신은 당신과 짝사랑 상대 😍 를 위한 두 개의 고급스러운 버거 🍔 를 주문합니다.
+마침내 여러분 차례가 되어, 여러분과 짝사랑 상대를 위해 매우 고급스러운 햄버거 2개를 주문합니다.
-당신이 비용을 지불합니다 💸 .
+여러분이 돈을 냅니다 💸.
-점원이 주방에 갑니다 👨🍳 .
+
-당신은 번호표가 없기 때문에 누구도 당신의 버거 🍔 를 대신 가져갈 수 없도록 카운터에 서서 기다립니다 🕙 .
+점원은 주방으로 갑니다.
-당신과 짝사랑 상대 😍 는 다른 사람이 새치기해서 버거를 가져가지 못하게 하느라 바쁘기 때문에 🕙 , 짝사랑 상대에게 주의를 기울일 수 없습니다 😞 .
+여러분은 번호표가 없으므로, 다른 사람이 여러분보다 먼저 햄버거를 가져가지 못하도록 카운터 앞에 서서 기다립니다 🕙.
-이것은 "동기" 작업이고, 당신은 점원/요리사 👨🍳 와 "동기화" 되었습니다. 당신은 기다리고 🕙 , 점원/요리사 👨🍳 가 버거 🍔 준비를 완료한 후 당신에게 주거나, 누군가가 그것을 가져가는 그 순간에 그 곳에 있어야합니다.
+
-카운터 앞에서 오랫동안 기다린 후에 🕙 , 점원/요리사 👨🍳 가 당신의 버거 🍔 를 가지고 돌아옵니다.
+여러분과 짝사랑 상대는 햄버거가 나오면 다른 사람이 끼어들어 가져가지 못하게 하느라 바쁘기 때문에, 짝사랑 상대에게 집중할 수 없습니다. 😞
-당신은 버거를 받고 짝사랑 상대와 함께 테이블로 돌아옵니다.
+이것은 "동기" 작업이며, 여러분은 점원/요리사 👨🍳 와 "동기화"되어 있습니다. 점원/요리사 👨🍳 가 햄버거를 완성해 여러분에게 주는 정확한 순간에 그 자리에 있어야 하므로, 여러분은 기다려야 🕙 하고, 그렇지 않으면 다른 사람이 가져갈 수도 있습니다.
-단지 먹기만 하다가, 다 먹었습니다 🍔 ⏹.
+
-카운터 앞에서 기다리면서 🕙 너무 많은 시간을 허비했기 때문에 대화를 하거나 작업을 걸 시간이 거의 없었습니다 😞 .
+그러다 점원/요리사 👨🍳 가 카운터 앞에서 오랫동안 기다린 🕙 끝에 마침내 햄버거를 가지고 돌아옵니다.
----
+
+
+여러분은 햄버거를 받아 짝사랑 상대와 테이블로 갑니다.
+
+그냥 먹고, 끝입니다. ⏹
+
+
+
+대부분의 시간을 카운터 앞에서 기다리는 데 🕙 썼기 때문에, 대화하거나 작업을 걸 시간은 많지 않았습니다. 😞
-이 병렬 버거 시나리오에서, 당신은 기다리고 🕙 , 오랜 시간동안 "카운터에서 기다리는" 🕙 데에 주의를 기울이는 ⏯ 두 개의 프로세서(당신과 짝사랑 상대😍)를 가진 컴퓨터 / 프로그램 🤖 입니다.
+/// info | 정보
-패스트푸드점에는 8개의 프로세서(점원/요리사) 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳 가 있습니다. 동시 버거는 단 두 개(한 명의 직원과 한 명의 요리사) 💁 👨🍳 만을 가지고 있었습니다.
+아름다운 일러스트: Ketrina Thompson. 🎨
-하지만 여전히, 병렬 버거 예시가 최선은 아닙니다 😞 .
+///
---
-이 예시는 버거🍔 이야기와 결이 같습니다.
+이 병렬 햄버거 시나리오에서, 여러분은 두 개의 프로세서(여러분과 짝사랑 상대)를 가진 컴퓨터/프로그램 🤖 이며, 둘 다 기다리고 🕙 오랫동안 "카운터에서 기다리기" 🕙 에 주의를 ⏯ 기울입니다.
+
+패스트푸드점에는 8개의 프로세서(점원/요리사)가 있습니다. 동시 햄버거 가게는 2개(점원 1명, 요리사 1명)만 있었을 것입니다.
-더 "현실적인" 예시로, 은행을 상상해보십시오.
+하지만 여전히 최종 경험은 그다지 좋지 않습니다. 😞
-최근까지, 대다수의 은행에는 다수의 은행원들 👨💼👨💼👨💼👨💼 과 긴 줄 🕙🕙🕙🕙🕙🕙🕙🕙 이 있습니다.
+---
-모든 은행원들은 한 명 한 명의 고객들을 차례로 상대합니다 👨💼⏯ .
+이것이 햄버거의 병렬 버전에 해당하는 이야기입니다. 🍔
-그리고 당신은 오랫동안 줄에서 기다려야하고 🕙 , 그렇지 않으면 당신의 차례를 잃게 됩니다.
+좀 더 "현실적인" 예시로, 은행을 상상해보세요.
-아마 당신은 은행 🏦 심부름에 짝사랑 상대 😍 를 데려가고 싶지는 않을 것입니다.
+최근까지 대부분의 은행에는 여러 은행원 👨💼👨💼👨💼👨💼 과 긴 줄 🕙🕙🕙🕙🕙🕙🕙🕙 이 있었습니다.
-### 버거 예시의 결론
+모든 은행원이 한 고객씩 순서대로 모든 일을 처리합니다 👨💼⏯.
-"짝사랑 상대와의 패스트푸드점 버거" 시나리오에서, 오랜 기다림 🕙 이 있기 때문에 동시 시스템 ⏸🔀⏯ 을 사용하는 것이 더 합리적입니다.
+그리고 여러분은 오랫동안 줄에서 기다려야 🕙 하며, 그렇지 않으면 차례를 잃습니다.
-대다수의 웹 응용프로그램의 경우가 그러합니다.
+아마 은행 🏦 업무를 보러 갈 때 짝사랑 상대 😍 를 데려가고 싶지는 않을 것입니다.
-매우 많은 수의 유저가 있지만, 서버는 그들의 요청을 전송하기 위해 그닥-좋지-않은 연결을 기다려야 합니다 🕙 .
+### 햄버거 예시의 결론 { #burger-conclusion }
-그리고 응답이 돌아올 때까지 다시 기다려야 합니다 🕙 .
+"짝사랑 상대와의 패스트푸드점 햄버거" 시나리오에서는 기다림 🕙 이 많기 때문에, 동시 시스템 ⏸🔀⏯ 을 사용하는 것이 훨씬 더 합리적입니다.
-이 "기다림" 🕙 은 마이크로초 단위이지만, 모두 더해지면, 결국에는 매우 긴 대기시간이 됩니다.
+대부분의 웹 애플리케이션이 그렇습니다.
-따라서 웹 API를 위해 비동기 ⏸🔀⏯ 코드를 사용하는 것이 합리적입니다.
+매우 많은 사용자들이 있고, 서버는 그들의 좋지 않은 연결을 통해 요청이 전송되기를 기다립니다 🕙.
-대부분의 존재하는 유명한 파이썬 프레임워크 (Flask와 Django 등)은 새로운 비동기 기능들이 파이썬에 존재하기 전에 만들어졌습니다. 그래서, 그들의 배포 방식은 병렬 실행과 새로운 기능만큼 강력하지는 않은 예전 버전의 비동기 실행을 지원합니다.
+그리고 응답이 돌아오기를 다시 기다립니다 🕙.
-비동기 웹 파이썬(ASGI)에 대한 주요 명세가 웹소켓을 지원하기 위해 Django에서 개발 되었음에도 그렇습니다.
+이 "기다림" 🕙 은 마이크로초 단위로 측정되지만, 모두 합치면 결국 꽤 많은 대기 시간이 됩니다.
-이러한 종류의 비동기성은 (NodeJS는 병렬적이지 않음에도) NodeJS가 사랑받는 이유이고, 프로그래밍 언어로서의 Go의 강점입니다.
+그래서 웹 API에는 비동기 ⏸🔀⏯ 코드를 사용하는 것이 매우 합리적입니다.
-그리고 **FastAPI**를 사용함으로써 동일한 성능을 낼 수 있습니다.
+이러한 종류의 비동기성은 NodeJS가 인기 있는 이유(비록 NodeJS가 병렬은 아니지만)이자, 프로그래밍 언어로서 Go의 강점입니다.
-또한 병렬성과 비동기성을 동시에 사용할 수 있기 때문에, 대부분의 테스트가 완료된 NodeJS 프레임워크보다 더 높은 성능을 얻고 C에 더 가까운 컴파일 언어인 Go와 동등한 성능을 얻을 수 있습니다(모두 Starlette 덕분입니다).
+그리고 이것이 **FastAPI**로 얻는 것과 같은 수준의 성능입니다.
-### 동시성이 병렬성보다 더 나은가?
+또한 병렬성과 비동기성을 동시에 사용할 수 있으므로, 대부분의 테스트된 NodeJS 프레임워크보다 더 높은 성능을 얻고, C에 더 가까운 컴파일 언어인 Go와 동등한 성능을 얻을 수 있습니다 (모두 Starlette 덕분입니다).
-그렇지 않습니다! 그것이 이야기의 교훈은 아닙니다.
+### 동시성이 병렬성보다 더 나은가요? { #is-concurrency-better-than-parallelism }
-동시성은 병렬성과 다릅니다. 그리고 그것은 많은 대기를 필요로하는 **특정한** 시나리오에서는 더 낫습니다. 이로 인해, 웹 응용프로그램 개발에서 동시성이 병렬성보다 일반적으로 훨씬 낫습니다. 하지만 모든 경우에 그런 것은 아닙니다.
+아니요! 그게 이 이야기의 교훈은 아닙니다.
-따라서, 균형을 맞추기 위해, 다음의 짧은 이야기를 상상해보십시오:
+동시성은 병렬성과 다릅니다. 그리고 많은 기다림이 포함되는 **특정한** 시나리오에서는 더 낫습니다. 그 때문에 웹 애플리케이션 개발에서는 일반적으로 병렬성보다 훨씬 더 낫습니다. 하지만 모든 것에 해당하진 않습니다.
-> 당신은 크고, 더러운 집을 청소해야합니다.
+그래서 균형을 맞추기 위해, 다음의 짧은 이야기를 상상해보세요:
+
+> 여러분은 크고 더러운 집을 청소해야 합니다.
*네, 이게 전부입니다*.
---
-어디에도 대기 🕙 는 없고, 집안 곳곳에서 해야하는 많은 작업들만 있습니다.
+어디에도 기다림 🕙 은 없고, 집의 여러 장소에서 해야 할 일이 많을 뿐입니다.
-버거 예시처럼 처음에는 거실, 그 다음은 부엌과 같은 식으로 순서를 정할 수도 있으나, 무엇도 기다리지 🕙 않고 계속해서 청소 작업만 수행하기 때문에, 순서는 아무런 영향을 미치지 않습니다.
+햄버거 예시처럼 거실부터, 그 다음은 부엌처럼 순서를 정할 수도 있지만, 어떤 것도 기다리지 🕙 않고 계속 청소만 하기 때문에, 순서는 아무런 영향을 주지 않습니다.
-순서가 있든 없든 동일한 시간이 소요될 것이고(동시성) 동일한 양의 작업을 하게 될 것입니다.
+순서가 있든 없든(동시성) 끝내는 데 걸리는 시간은 같고, 같은 양의 일을 하게 됩니다.
-하지만 이 경우에서, 8명의 전(前)-점원/요리사이면서-현(現)-청소부 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳 를 고용할 수 있고, 그들 각자(그리고 당신)가 집의 한 부분씩 맡아 청소를 한다면, 당신은 **병렬적**으로 작업을 수행할 수 있고, 조금의 도움이 있다면, 훨씬 더 빨리 끝낼 수 있습니다.
+하지만 이 경우, 전(前) 점원/요리사이자 현(現) 청소부가 된 8명을 데려올 수 있고, 각자(그리고 여러분)가 집의 구역을 하나씩 맡아 청소한다면, 추가 도움과 함께 모든 일을 **병렬**로 수행하여 훨씬 더 빨리 끝낼 수 있습니다.
-이 시나리오에서, (당신을 포함한) 각각의 청소부들은 프로세서가 될 것이고, 각자의 역할을 수행합니다.
+이 시나리오에서 (여러분을 포함한) 각 청소부는 프로세서가 되어, 맡은 일을 수행합니다.
-실행 시간의 대부분이 대기가 아닌 실제 작업에 소요되고, 컴퓨터에서 작업은 CPU에서 이루어지므로, 이러한 문제를 "CPU에 묶였"다고 합니다.
+그리고 실행 시간의 대부분이 기다림이 아니라 실제 작업에 쓰이고, 컴퓨터에서 작업은 CPU가 수행하므로, 이런 문제를 "CPU bound"라고 부릅니다.
---
-CPU에 묶인 연산에 관한 흔한 예시는 복잡한 수학 처리를 필요로 하는 경우입니다.
+CPU bound 작업의 흔한 예시는 복잡한 수학 처리가 필요한 것들입니다.
예를 들어:
-* **오디오** 또는 **이미지** 처리.
-* **컴퓨터 비전**: 하나의 이미지는 수백개의 픽셀로 구성되어있고, 각 픽셀은 3개의 값 / 색을 갖고 있으며, 일반적으로 해당 픽셀들에 대해 동시에 무언가를 계산해야하는 처리.
-* **머신러닝**: 일반적으로 많은 "행렬"과 "벡터" 곱셈이 필요합니다. 거대한 스프레드 시트에 수들이 있고 그 수들을 동시에 곱해야 한다고 생각해보십시오.
-* **딥러닝**: 머신러닝의 하위영역으로, 동일한 예시가 적용됩니다. 단지 이 경우에는 하나의 스프레드 시트에 곱해야할 수들이 있는 것이 아니라, 거대한 세트의 스프레드 시트들이 있고, 많은 경우에, 이 모델들을 만들고 사용하기 위해 특수한 프로세서를 사용합니다.
+* **오디오** 또는 **이미지** 처리
+* **컴퓨터 비전**: 이미지는 수백만 개의 픽셀로 구성되며, 각 픽셀은 3개의 값/색을 갖습니다. 보통 그 픽셀들에 대해 동시에 무언가를 계산해야 합니다.
+* **머신러닝**: 보통 많은 "matrix"와 "vector" 곱셈이 필요합니다. 숫자가 있는 거대한 스프레드시트를 생각하고, 그 모든 수를 동시에 곱한다고 생각해보세요.
+* **딥러닝**: 머신러닝의 하위 분야이므로 동일하게 적용됩니다. 다만 곱해야 할 숫자가 있는 스프레드시트가 하나가 아니라, 아주 큰 집합이며, 많은 경우 그 모델을 만들고/또는 사용하기 위해 특별한 프로세서를 사용합니다.
-### 동시성 + 병렬성: 웹 + 머신러닝
+### 동시성 + 병렬성: 웹 + 머신러닝 { #concurrency-parallelism-web-machine-learning }
-**FastAPI**를 사용하면 웹 개발에서는 매우 흔한 동시성의 이점을 (NodeJS의 주된 매력만큼) 얻을 수 있습니다.
+**FastAPI**를 사용하면 웹 개발에서 매우 흔한 동시성의 이점을( NodeJS의 주요 매력과 같은) 얻을 수 있습니다.
-뿐만 아니라 머신러닝 시스템과 같이 **CPU에 묶인** 작업을 위해 병렬성과 멀티프로세싱(다수의 프로세스를 병렬적으로 동작시키는 것)을 이용하는 것도 가능합니다.
+또한 머신러닝 시스템처럼 **CPU bound** 워크로드에 대해 병렬성과 멀티프로세싱(여러 프로세스를 병렬로 실행)을 활용할 수도 있습니다.
-파이썬이 **데이터 사이언스**, 머신러닝과 특히 딥러닝에 의 주된 언어라는 간단한 사실에 더해서, 이것은 FastAPI를 데이터 사이언스 / 머신러닝 웹 API와 응용프로그램에 (다른 것들보다) 좋은 선택지가 되게 합니다.
+이것은 파이썬이 **데이터 사이언스**, 머신러닝, 특히 딥러닝의 주요 언어라는 단순한 사실과 더해져, FastAPI를 데이터 사이언스/머신러닝 웹 API 및 애플리케이션(그 외에도 많은 것들)에 매우 잘 맞는 선택으로 만들어 줍니다.
-배포시 병렬을 어떻게 가능하게 하는지 알고싶다면, [배포](deployment/index.md){.internal-link target=_blank}문서를 참고하십시오.
+프로덕션에서 이 병렬성을 어떻게 달성하는지 보려면 [배포](deployment/index.md){.internal-link target=_blank} 섹션을 참고하세요.
-## `async`와 `await`
+## `async`와 `await` { #async-and-await }
-최신 파이썬 버전에는 비동기 코드를 정의하는 매우 직관적인 방법이 있습니다. 이는 이것을 평범한 "순차적" 코드로 보이게 하고, 적절한 순간에 당신을 위해 "대기"합니다.
+최신 파이썬 버전에는 비동기 코드를 정의하는 매우 직관적인 방법이 있습니다. 이 방법은 이를 평범한 "순차" 코드처럼 보이게 하고, 적절한 순간에 여러분을 위해 "기다림"을 수행합니다.
-연산이 결과를 전달하기 전에 대기를 해야하고 새로운 파이썬 기능들을 지원한다면, 이렇게 코드를 작성할 수 있습니다:
+결과를 주기 전에 기다림이 필요한 작업이 있고, 이러한 새로운 파이썬 기능을 지원한다면, 다음과 같이 작성할 수 있습니다:
```Python
burgers = await get_burgers(2)
```
-여기서 핵심은 `await`입니다. 이것은 파이썬에게 `burgers` 결과를 저장하기 이전에 `get_burgers(2)`의 작업이 완료되기를 🕙 기다리라고 ⏸ 말합니다. 이로 인해, 파이썬은 그동안 (다른 요청을 받는 것과 같은) 다른 작업을 수행해도 된다는 것을 🔀 ⏯ 알게될 것입니다.
+여기서 핵심은 `await`입니다. 이는 파이썬에게 `get_burgers(2)`가 그 일을 끝낼 때까지 🕙 기다리도록 ⏸ 말하고, 그 결과를 `burgers`에 저장하기 전에 완료되기를 기다리라고 합니다. 이를 통해 파이썬은 그동안(예: 다른 요청을 받는 것처럼) 다른 일을 하러 갈 수 있다는 것 🔀 ⏯ 을 알게 됩니다.
-`await`가 동작하기 위해, 이것은 비동기를 지원하는 함수 내부에 있어야 합니다. 이를 위해서 함수를 `async def`를 사용해 정의하기만 하면 됩니다:
+`await`가 동작하려면, 이 비동기성을 지원하는 함수 내부에 있어야 합니다. 그러려면 `async def`로 선언하기만 하면 됩니다:
```Python hl_lines="1"
async def get_burgers(number: int):
- # Do some asynchronous stuff to create the burgers
+ # 햄버거를 만들기 위한 비동기 처리를 수행
return burgers
```
-...`def`를 사용하는 대신:
+...`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`를 사용하면, 파이썬은 해당 함수 내에서 `await` 표현에 주의해야한다는 사실과, 해당 함수의 실행을 "일시정지"⏸하고 다시 돌아오기 전까지 다른 작업을 수행🔀할 수 있다는 것을 알게됩니다.
+`async def`를 사용하면, 파이썬은 그 함수 내부에서 `await` 표현식에 주의해야 하며, 그 함수의 실행을 "일시정지" ⏸ 하고 다시 돌아오기 전에 다른 일을 하러 갈 수 있다는 것 🔀 을 알게 됩니다.
-`async def`f 함수를 호출하고자 할 때, "대기"해야합니다. 따라서, 아래는 동작하지 않습니다.
+`async def` 함수를 호출하고자 할 때는, 그 함수를 "await" 해야 합니다. 따라서 아래는 동작하지 않습니다:
```Python
-# This won't work, because get_burgers was defined with: async def
+# 동작하지 않습니다. get_burgers는 async def로 정의되었습니다
burgers = get_burgers(2)
```
---
-따라서, `await`f를 사용해서 호출할 수 있는 라이브러리를 사용한다면, 다음과 같이 `async def`를 사용하는 *경로 작동 함수*를 생성해야 합니다:
+따라서, `await`로 호출할 수 있다고 말하는 라이브러리를 사용한다면, 다음과 같이 그것을 사용하는 *경로 처리 함수*를 `async def`로 만들어야 합니다:
```Python hl_lines="2-3"
@app.get('/burgers')
@@ -317,94 +349,96 @@ async def read_burgers():
return burgers
```
-### 더 세부적인 기술적 사항
+### 더 세부적인 기술적 사항 { #more-technical-details }
+
+`await`는 `async def`로 정의된 함수 내부에서만 사용할 수 있다는 것을 눈치채셨을 것입니다.
-`await`가 `async def`를 사용하는 함수 내부에서만 사용이 가능하다는 것을 눈치채셨을 것입니다.
+하지만 동시에, `async def`로 정의된 함수는 "await" 되어야 합니다. 따라서 `async def`를 가진 함수는 `async def`로 정의된 함수 내부에서만 호출될 수 있습니다.
-하지만 동시에, `async def`로 정의된 함수들은 "대기"되어야만 합니다. 따라서, `async def`를 사용한 함수들은 역시 `async def`를 사용한 함수 내부에서만 호출될 수 있습니다.
+그렇다면, 닭이 먼저냐 달걀이 먼저냐처럼, 첫 번째 `async` 함수는 어떻게 호출할 수 있을까요?
-그렇다면 닭이 먼저냐, 달걀이 먼저냐, 첫 `async` 함수를 어떻게 호출할 수 있겠습니까?
+**FastAPI**로 작업한다면 걱정할 필요가 없습니다. 그 "첫" 함수는 여러분의 *경로 처리 함수*가 될 것이고, FastAPI는 올바르게 처리하는 방법을 알고 있기 때문입니다.
-**FastAPI**를 사용해 작업한다면 이것을 걱정하지 않아도 됩니다. 왜냐하면 그 "첫" 함수는 당신의 *경로 작동 함수*가 될 것이고, FastAPI는 어떻게 올바르게 처리할지 알고있기 때문입니다.
+하지만 FastAPI 없이 `async` / `await`를 사용하고 싶다면, 그것도 가능합니다.
-하지만 FastAPI를 사용하지 않고 `async` / `await`를 사용하고 싶다면, 이 역시 가능합니다.
+### 여러분만의 async 코드 작성하기 { #write-your-own-async-code }
-### 당신만의 비동기 코드 작성하기
+Starlette(그리고 **FastAPI**)는 AnyIO를 기반으로 하고 있으며, 파이썬 표준 라이브러리 asyncio와 Trio 모두와 호환됩니다.
-Starlette(그리고 FastAPI)는 AnyIO를 기반으로 하고있고, 따라서 파이썬 표준 라이브러리인 asyncio 및 Trio와 호환됩니다.
+특히, 코드에서 더 고급 패턴이 필요한 고급 동시성 사용 사례에서는 직접 AnyIO를 사용할 수 있습니다.
-특히, 코드에서 고급 패턴이 필요한 고급 동시성을 사용하는 경우 직접적으로 AnyIO를 사용할 수 있습니다.
+그리고 FastAPI를 사용하지 않더라도, 높은 호환성을 확보하고 그 이점(예: *structured concurrency*)을 얻기 위해 AnyIO로 여러분만의 async 애플리케이션을 작성할 수도 있습니다.
-FastAPI를 사용하지 않더라도, 높은 호환성 및 AnyIO의 이점(예: *구조화된 동시성*)을 취하기 위해 AnyIO를 사용해 비동기 응용프로그램을 작성할 수 있습니다.
+저는 AnyIO 위에 얇은 레이어로 또 다른 라이브러리를 만들었는데, 타입 어노테이션을 조금 개선하고 더 나은 **자동완성**, **인라인 오류** 등을 얻기 위한 것입니다. 또한 **이해**하고 **여러분만의 async 코드**를 작성하도록 돕는 친절한 소개와 튜토리얼도 제공합니다: Asyncer. 특히 **async 코드와 일반**(blocking/동기) 코드를 **결합**해야 한다면 아주 유용합니다.
-### 비동기 코드의 다른 형태
+### 비동기 코드의 다른 형태 { #other-forms-of-asynchronous-code }
-파이썬에서 `async`와 `await`를 사용하게 된 것은 비교적 최근의 일입니다.
+`async`와 `await`를 사용하는 이 스타일은 언어에서 비교적 최근에 추가되었습니다.
-하지만 이로 인해 비동기 코드 작업이 훨씬 간단해졌습니다.
+하지만 비동기 코드를 다루는 일을 훨씬 더 쉽게 만들어 줍니다.
-같은 (또는 거의 유사한) 문법은 최신 버전의 자바스크립트(브라우저와 NodeJS)에도 추가되었습니다.
+거의 동일한 문법이 최근 브라우저와 NodeJS의 최신 JavaScript에도 포함되었습니다.
-하지만 그 이전에, 비동기 코드를 처리하는 것은 꽤 복잡하고 어려운 일이었습니다.
+하지만 그 이전에는 비동기 코드를 처리하는 것이 훨씬 더 복잡하고 어려웠습니다.
-파이썬의 예전 버전이라면, 스레드 또는 Gevent를 사용할 수 있을 것입니다. 하지만 코드를 이해하고, 디버깅하고, 이에 대해 생각하는게 훨씬 복잡합니다.
+이전 버전의 파이썬에서는 스레드 또는 Gevent를 사용할 수 있었을 것입니다. 하지만 코드를 이해하고, 디버깅하고, 이에 대해 생각하는 것이 훨씬 더 복잡합니다.
-예전 버전의 NodeJS / 브라우저 자바스크립트라면, "콜백 함수"를 사용했을 것입니다. 그리고 이로 인해 "콜백 지옥"에 빠지게 될 수 있습니다.
+이전 버전의 NodeJS/브라우저 JavaScript에서는 "callback"을 사용했을 것입니다. 이는 "callback hell"로 이어집니다.
-## 코루틴
+## 코루틴 { #coroutines }
-**코루틴**은 `async def` 함수가 반환하는 것을 칭하는 매우 고급스러운 용어일 뿐입니다. 파이썬은 그것이 시작되고 어느 시점에서 완료되지만 내부에 `await`가 있을 때마다 내부적으로 일시정지⏸될 수도 있는 함수와 유사한 것이라는 사실을 알고있습니다.
+**코루틴**은 `async def` 함수가 반환하는 것에 대한 매우 고급스러운 용어일 뿐입니다. 파이썬은 그것이 함수와 비슷한 무언가로서 시작할 수 있고, 어느 시점에 끝나지만, 내부에 `await`가 있을 때마다 내부적으로도 일시정지 ⏸ 될 수 있다는 것을 알고 있습니다.
-그러나 `async` 및 `await`와 함께 비동기 코드를 사용하는 이 모든 기능들은 "코루틴"으로 간단히 요약됩니다. 이것은 Go의 주된 핵심 기능인 "고루틴"에 견줄 수 있습니다.
+하지만 `async` 및 `await`와 함께 비동기 코드를 사용하는 이 모든 기능은 종종 "코루틴"을 사용한다고 요약됩니다. 이는 Go의 주요 핵심 기능인 "Goroutines"에 비견됩니다.
-## 결론
+## 결론 { #conclusion }
-상기 문장을 다시 한 번 봅시다:
+위의 같은 문장을 다시 봅시다:
-> 최신 파이썬 버전은 **`async` 및 `await`** 문법과 함께 **“코루틴”**이라고 하는 것을 사용하는 **“비동기 코드”**를 지원합니다.
+> 최신 파이썬 버전은 **“코루틴”**이라고 하는 것을 사용하는 **“비동기 코드”**를 **`async` 및 `await`** 문법과 함께 지원합니다.
-이제 이 말을 조금 더 이해할 수 있을 것입니다. ✨
+이제 더 이해가 될 것입니다. ✨
-이것이 (Starlette을 통해) FastAPI를 강하게 하면서 그것이 인상적인 성능을 낼 수 있게 합니다.
+이 모든 것이 FastAPI(Starlette을 통해)를 구동하고, 인상적인 성능을 내게 하는 원동력입니다.
-## 매우 세부적인 기술적 사항
+## 매우 세부적인 기술적 사항 { #very-technical-details }
/// warning | 경고
-이 부분은 넘어가도 됩니다.
+이 부분은 아마 건너뛰어도 됩니다.
이것들은 **FastAPI**가 내부적으로 어떻게 동작하는지에 대한 매우 세부적인 기술사항입니다.
-만약 기술적 지식(코루틴, 스레드, 블록킹 등)이 있고 FastAPI가 어떻게 `async def` vs `def`를 다루는지 궁금하다면, 계속하십시오.
+(코루틴, 스레드, 블로킹 등) 같은 기술 지식이 꽤 있고 FastAPI가 `async def`와 일반 `def`를 어떻게 처리하는지 궁금하다면, 계속 읽어보세요.
///
-### 경로 작동 함수
+### 경로 처리 함수 { #path-operation-functions }
-경로 작동 함수를 `async def` 대신 일반적인 `def`로 선언하는 경우, (서버를 차단하는 것처럼) 그것을 직접 호출하는 대신 대기중인 외부 스레드풀에서 실행됩니다.
+*경로 처리 함수*를 `async def` 대신 일반적인 `def`로 선언하면, (서버를 블로킹할 수 있으므로 직접 호출하는 대신) 외부 스레드풀에서 실행되고 그 결과를 await 합니다.
-만약 상기에 묘사된대로 동작하지 않는 비동기 프로그램을 사용해왔고 약간의 성능 향상 (약 100 나노초)을 위해 `def`를 사용해서 계산만을 위한 사소한 *경로 작동 함수*를 정의해왔다면, **FastAPI**는 이와는 반대라는 것에 주의하십시오. 이러한 경우에, *경로 작동 함수*가 블로킹 I/O를 수행하는 코드를 사용하지 않는 한 `async def`를 사용하는 편이 더 낫습니다.
+위에서 설명한 방식으로 동작하지 않는 다른 async 프레임워크를 사용해본 적이 있고, 아주 작은 성능 향상(약 100 나노초)을 위해 계산만 하는 사소한 *경로 처리 함수*를 일반 `def`로 정의하곤 했다면, **FastAPI**에서는 그 효과가 정반대가 될 수 있다는 점에 유의하세요. 이런 경우에는 *경로 처리 함수*에서 블로킹 I/O 를 수행하는 코드를 사용하지 않는 한 `async def`를 사용하는 편이 더 낫습니다.
-하지만 두 경우 모두, FastAPI가 당신이 전에 사용하던 프레임워크보다 [더 빠를](index.md#_11){.internal-link target=_blank} (최소한 비견될) 확률이 높습니다.
+그럼에도 두 경우 모두, **FastAPI**는 이전에 사용하던 프레임워크보다 [여전히 더 빠를](index.md#performance){.internal-link target=_blank} 가능성이 높습니다(또는 최소한 비슷합니다).
-### 의존성
+### 의존성 { #dependencies }
-의존성에도 동일하게 적용됩니다. 의존성이 `async def`가 아닌 표준 `def` 함수라면, 외부 스레드풀에서 실행됩니다.
+[의존성](tutorial/dependencies/index.md){.internal-link target=_blank}에도 동일하게 적용됩니다. 의존성이 `async def` 대신 표준 `def` 함수라면, 외부 스레드풀에서 실행됩니다.
-### 하위-의존성
+### 하위 의존성 { #sub-dependencies }
-함수 정의시 매개변수로 서로를 필요로하는 다수의 의존성과 하위-의존성을 가질 수 있고, 그 중 일부는 `async def`로, 다른 일부는 일반적인 `def`로 생성되었을 수 있습니다. 이것은 여전히 잘 동작하고, 일반적인 `def`로 생성된 것들은 "대기"되는 대신에 (스레드풀로부터) 외부 스레드에서 호출됩니다.
+서로를 필요로 하는 여러 의존성과 [하위 의존성](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank}을 함수 정의의 매개변수로 가질 수 있으며, 그중 일부는 `async def`로, 다른 일부는 일반 `def`로 생성되었을 수 있습니다. 그래도 정상 동작하며, 일반 `def`로 생성된 것들은 "await"되는 대신 (스레드풀에서) 외부 스레드에서 호출됩니다.
-### 다른 유틸리티 함수
+### 다른 유틸리티 함수 { #other-utility-functions }
-직접 호출되는 다른 모든 유틸리티 함수는 일반적인 `def`나 `async def`로 생성될 수 있고 FastAPI는 이를 호출하는 방식에 영향을 미치지 않습니다.
+직접 호출하는 다른 모든 유틸리티 함수는 일반 `def`나 `async def`로 생성될 수 있으며, FastAPI는 호출 방식에 영향을 주지 않습니다.
-이것은 FastAPI가 당신을 위해 호출하는 함수와는 반대입니다: *경로 작동 함수*와 의존성
+이는 FastAPI가 여러분을 위해 호출하는 함수(즉, *경로 처리 함수*와 의존성)와 대비됩니다.
-만약 당신의 유틸리티 함수가 `def`를 사용한 일반적인 함수라면, 스레드풀에서가 아니라 직접 호출(당신이 코드에 작성한 대로)될 것이고, `async def`로 생성된 함수라면 코드에서 호출할 때 그 함수를 `await` 해야 합니다.
+유틸리티 함수가 `def`로 만든 일반 함수라면, 스레드풀이 아니라 직접(코드에 작성한 대로) 호출됩니다. 그리고 `async def`로 생성된 함수라면, 코드에서 호출할 때 그 함수를 `await` 해야 합니다.
---
-다시 말하지만, 이것은 당신이 이것에 대해 찾고있던 경우에 한해 유용할 매우 세부적인 기술사항입니다.
+다시 말하지만, 이것들은 아마도 이를 찾고 있었던 경우에 유용한 매우 세부적인 기술사항입니다.
-그렇지 않은 경우, 상기의 가이드라인만으로도 충분할 것입니다: [바쁘신 경우](#_1).
+그렇지 않다면, 위 섹션의 가이드라인이면 충분합니다: 바쁘신가요?.
diff --git a/docs/ko/docs/benchmarks.md b/docs/ko/docs/benchmarks.md
index aff8ae70e..2d4fdbedd 100644
--- a/docs/ko/docs/benchmarks.md
+++ b/docs/ko/docs/benchmarks.md
@@ -1,10 +1,10 @@
-# 벤치마크
+# 벤치마크 { #benchmarks }
-독립적인 TechEmpower 벤치마크에 따르면 **FastAPI** 애플리케이션이 Uvicorn을 사용하여 가장 빠른 Python 프레임워크 중 하나로 실행되며, Starlette와 Uvicorn 자체(내부적으로 FastAPI가 사용하는 도구)보다 조금 아래에 위치합니다.
+독립적인 TechEmpower 벤치마크에 따르면 **FastAPI** 애플리케이션이 Uvicorn을 사용하여 사용 가능한 가장 빠른 Python 프레임워크 중 하나로 실행되며, Starlette와 Uvicorn 자체(내부적으로 FastAPI가 사용하는 도구)보다 조금 아래에 위치합니다.
그러나 벤치마크와 비교를 확인할 때 다음 사항을 염두에 두어야 합니다.
-## 벤치마크와 속도
+## 벤치마크와 속도 { #benchmarks-and-speed }
벤치마크를 확인할 때, 일반적으로 여러 가지 유형의 도구가 동등한 것으로 비교되는 것을 볼 수 있습니다.
@@ -16,7 +16,7 @@
* **Uvicorn**: ASGI 서버
* **Starlette**: (Uvicorn 사용) 웹 마이크로 프레임워크
- * **FastAPI**: (Starlette 사용) API 구축을 위한 데이터 검증 등 여러 추가 기능이 포함된 API 마이크로 프레임워크
+ * **FastAPI**: (Starlette 사용) 데이터 검증 등 API를 구축하기 위한 여러 추가 기능이 포함된 API 마이크로 프레임워크
* **Uvicorn**:
* 서버 자체 외에는 많은 추가 코드가 없기 때문에 최고의 성능을 발휘합니다.
@@ -29,6 +29,6 @@
* **FastAPI**:
* Starlette가 Uvicorn을 사용하므로 Uvicorn보다 빨라질 수 없는 것과 마찬가지로, **FastAPI**는 Starlette를 사용하므로 더 빠를 수 없습니다.
* FastAPI는 Starlette에 추가적으로 더 많은 기능을 제공합니다. API를 구축할 때 거의 항상 필요한 데이터 검증 및 직렬화와 같은 기능들이 포함되어 있습니다. 그리고 이를 사용하면 문서 자동화 기능도 제공됩니다(문서 자동화는 응용 프로그램 실행 시 오버헤드를 추가하지 않고 시작 시 생성됩니다).
- * FastAPI를 사용하지 않고 직접 Starlette(또는 Sanic, Flask, Responder 등)를 사용했다면 데이터 검증 및 직렬화를 직접 구현해야 합니다. 따라서 최종 응용 프로그램은 FastAPI를 사용한 것과 동일한 오버헤드를 가지게 될 것입니다. 많은 경우 데이터 검증 및 직렬화가 응용 프로그램에서 작성된 코드 중 가장 많은 부분을 차지합니다.
- * 따라서 FastAPI를 사용함으로써 개발 시간, 버그, 코드 라인을 줄일 수 있으며, FastAPI를 사용하지 않았을 때와 동일하거나 더 나은 성능을 얻을 수 있습니다(코드에서 모두 구현해야 하기 때문에).
- * FastAPI를 비교할 때는 Flask-apispec, NestJS, Molten 등 데이터 검증, 직렬화 및 문서화가 통합된 자동 데이터 검증, 직렬화 및 문서화를 제공하는 웹 응용 프로그램 프레임워크(또는 도구 집합)와 비교하세요.
+ * FastAPI를 사용하지 않고 직접 Starlette(또는 다른 도구, 예: Sanic, Flask, Responder 등)를 사용했다면 데이터 검증 및 직렬화를 직접 구현해야 합니다. 따라서 최종 응용 프로그램은 FastAPI를 사용한 것과 동일한 오버헤드를 가지게 될 것입니다. 많은 경우 데이터 검증 및 직렬화가 응용 프로그램에서 작성된 코드 중 가장 많은 부분을 차지합니다.
+ * 따라서 FastAPI를 사용함으로써 개발 시간, 버그, 코드 라인을 줄일 수 있으며, FastAPI를 사용하지 않았을 때와 동일한 성능(또는 더 나은 성능)을 얻을 수 있을 것입니다(코드에서 모두 구현해야 하기 때문에).
+ * FastAPI를 비교할 때는 Flask-apispec, NestJS, Molten 등 데이터 검증, 직렬화 및 문서화를 제공하는 웹 애플리케이션 프레임워크(또는 도구 집합)와 비교하세요. 통합된 자동 데이터 검증, 직렬화 및 문서화를 제공하는 프레임워크입니다.
diff --git a/docs/ko/docs/deployment/cloud.md b/docs/ko/docs/deployment/cloud.md
index dbc814bbd..0705e120c 100644
--- a/docs/ko/docs/deployment/cloud.md
+++ b/docs/ko/docs/deployment/cloud.md
@@ -1,13 +1,24 @@
-# FastAPI를 클라우드 제공업체에서 배포하기
+# 클라우드 제공업체에서 FastAPI 배포하기 { #deploy-fastapi-on-cloud-providers }
사실상 거의 **모든 클라우드 제공업체**를 사용하여 여러분의 FastAPI 애플리케이션을 배포할 수 있습니다.
대부분의 경우, 주요 클라우드 제공업체에서는 FastAPI를 배포할 수 있도록 가이드를 제공합니다.
-## 클라우드 제공업체 - 후원자들
+## FastAPI Cloud { #fastapi-cloud }
-몇몇 클라우드 제공업체들은 [**FastAPI를 후원하며**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, 이를 통해 FastAPI와 FastAPI **생태계**가 지속적이고 건전한 **발전**을 할 수 있습니다.
+**FastAPI Cloud**는 **FastAPI**를 만든 동일한 작성자와 팀이 구축했습니다.
-이는 FastAPI와 **커뮤니티** (여러분)에 대한 진정한 헌신을 보여줍니다. 그들은 여러분에게 **좋은 서비스**를 제공할 뿐 만이 아니라 여러분이 **훌륭하고 건강한 프레임워크인** FastAPI 를 사용하길 원하기 때문입니다. 🙇
+최소한의 노력으로 API를 **구축**, **배포**, **접근**하는 과정을 간소화합니다.
-아래와 같은 서비스를 사용해보고 각 서비스의 가이드를 따를 수도 있습니다.
+FastAPI로 앱을 빌드할 때의 동일한 **개발자 경험**을 클라우드에 **배포**하는 데에도 제공합니다. 🎉
+
+FastAPI Cloud는 *FastAPI and friends* 오픈 소스 프로젝트의 주요 후원자이자 자금 제공자입니다. ✨
+
+## 클라우드 제공업체 - 후원자들 { #cloud-providers-sponsors }
+
+다른 몇몇 클라우드 제공업체들도 ✨ [**FastAPI를 후원합니다**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨. 🙇
+
+가이드를 따라 하고 서비스를 사용해보기 위해 이들도 고려해볼 수 있습니다:
+
+* Render
+* Railway
diff --git a/docs/ko/docs/deployment/concepts.md b/docs/ko/docs/deployment/concepts.md
new file mode 100644
index 000000000..dd7edd1ba
--- /dev/null
+++ b/docs/ko/docs/deployment/concepts.md
@@ -0,0 +1,321 @@
+# 배포 개념 { #deployments-concepts }
+
+**FastAPI** 애플리케이션(사실 어떤 종류의 웹 API든)을 배포할 때는, 여러분이 신경 써야 할 여러 개념이 있습니다. 그리고 이 개념들을 활용하면 **애플리케이션을 배포하기 위한 가장 적절한 방법**을 찾을 수 있습니다.
+
+중요한 개념 몇 가지는 다음과 같습니다:
+
+* 보안 - HTTPS
+* 시작 시 실행
+* 재시작
+* 복제(실행 중인 프로세스 수)
+* 메모리
+* 시작 전 사전 단계
+
+이것들이 **배포**에 어떤 영향을 주는지 살펴보겠습니다.
+
+결국 최종 목표는 **API 클라이언트에 서비스를 제공**할 때 **보안**을 보장하고, **중단을 피하며**, **컴퓨팅 리소스**(예: 원격 서버/가상 머신)를 가능한 한 효율적으로 사용하는 것입니다. 🚀
+
+여기서 이 **개념들**을 조금 더 설명하겠습니다. 그러면 서로 매우 다른 환경, 심지어 아직 존재하지 않는 **미래**의 환경에서도 API를 어떻게 배포할지 결정하는 데 필요한 **직관**을 얻을 수 있을 것입니다.
+
+이 개념들을 고려하면, 여러분은 **자신의 API**를 배포하기 위한 최선의 방법을 **평가하고 설계**할 수 있습니다.
+
+다음 장들에서는 FastAPI 애플리케이션을 배포하기 위한 더 **구체적인 레시피**를 제공하겠습니다.
+
+하지만 지금은, 이 중요한 **개념적 아이디어**들을 확인해 봅시다. 이 개념들은 다른 어떤 종류의 웹 API에도 동일하게 적용됩니다. 💡
+
+## 보안 - HTTPS { #security-https }
+
+[이전 HTTPS 장](https.md){.internal-link target=_blank}에서 HTTPS가 API에 암호화를 제공하는 방식에 대해 배웠습니다.
+
+또한 HTTPS는 일반적으로 애플리케이션 서버 바깥의 **외부** 컴포넌트인 **TLS Termination Proxy**가 제공한다는 것도 확인했습니다.
+
+그리고 **HTTPS 인증서 갱신**을 담당하는 무언가가 필요합니다. 같은 컴포넌트가 그 역할을 할 수도 있고, 다른 무언가가 담당할 수도 있습니다.
+
+### HTTPS를 위한 도구 예시 { #example-tools-for-https }
+
+TLS Termination Proxy로 사용할 수 있는 도구는 예를 들어 다음과 같습니다:
+
+* Traefik
+ * 인증서 갱신을 자동으로 처리 ✨
+* Caddy
+ * 인증서 갱신을 자동으로 처리 ✨
+* Nginx
+ * 인증서 갱신을 위해 Certbot 같은 외부 컴포넌트 사용
+* HAProxy
+ * 인증서 갱신을 위해 Certbot 같은 외부 컴포넌트 사용
+* Nginx 같은 Ingress Controller를 사용하는 Kubernetes
+ * 인증서 갱신을 위해 cert-manager 같은 외부 컴포넌트 사용
+* 클라우드 제공자가 서비스 일부로 내부적으로 처리(아래를 읽어보세요 👇)
+
+또 다른 선택지는 HTTPS 설정을 포함해 더 많은 일을 대신해주는 **클라우드 서비스**를 사용하는 것입니다. 제약이 있거나 비용이 더 들 수도 있습니다. 하지만 그 경우에는 TLS Termination Proxy를 직접 설정할 필요가 없습니다.
+
+다음 장에서 구체적인 예시를 보여드리겠습니다.
+
+---
+
+다음으로 고려할 개념들은 실제로 여러분의 API를 실행하는 프로그램(예: Uvicorn)과 관련된 내용입니다.
+
+## 프로그램과 프로세스 { #program-and-process }
+
+실행 중인 "**프로세스**"에 대해 많이 이야기하게 될 텐데, 이 말이 무엇을 의미하는지, 그리고 "**프로그램**"이라는 단어와 무엇이 다른지 명확히 해두는 것이 유용합니다.
+
+### 프로그램이란 { #what-is-a-program }
+
+**프로그램**이라는 단어는 보통 여러 가지를 가리키는 데 사용됩니다:
+
+* 여러분이 작성하는 **코드**, 즉 **Python 파일**들
+* 운영체제에서 **실행**할 수 있는 **파일**, 예: `python`, `python.exe`, `uvicorn`
+* 운영체제에서 **실행 중**인 특정 프로그램으로, CPU를 사용하고 메모리에 내용을 저장합니다. 이것을 **프로세스**라고도 합니다.
+
+### 프로세스란 { #what-is-a-process }
+
+**프로세스**라는 단어는 보통 더 구체적으로, 운영체제에서 실행 중인 것(위 마지막 항목처럼)만을 가리키는 데 사용됩니다:
+
+* 운영체제에서 **실행 중**인 특정 프로그램
+ * 파일이나 코드를 의미하는 것이 아니라, 운영체제가 **실제로 실행**하고 관리하는 대상을 **구체적으로** 의미합니다.
+* 어떤 프로그램이든 어떤 코드든, **실행**될 때만 무언가를 **할 수 있습니다**. 즉, **프로세스가 실행 중**일 때입니다.
+* 프로세스는 여러분이, 혹은 운영체제가 **종료**(또는 “kill”)할 수 있습니다. 그러면 실행이 멈추고, 더 이상 **아무것도 할 수 없습니다**.
+* 컴퓨터에서 실행 중인 각 애플리케이션 뒤에는 프로세스가 있습니다. 실행 중인 프로그램, 각 창 등도 마찬가지입니다. 그리고 컴퓨터가 켜져 있는 동안 보통 많은 프로세스가 **동시에** 실행됩니다.
+* **같은 프로그램**의 **여러 프로세스**가 동시에 실행될 수도 있습니다.
+
+운영체제의 “작업 관리자(task manager)”나 “시스템 모니터(system monitor)”(또는 비슷한 도구)를 확인해 보면, 이런 프로세스가 많이 실행 중인 것을 볼 수 있습니다.
+
+또 예를 들어, 같은 브라우저 프로그램(Firefox, Chrome, Edge 등)을 실행하는 프로세스가 여러 개 있는 것도 보일 가능성이 큽니다. 보통 탭마다 하나의 프로세스를 실행하고, 그 외에도 추가 프로세스 몇 개가 더 있습니다.
+
+
+
+---
+
+이제 **프로세스**와 **프로그램**의 차이를 알았으니, 배포에 대한 이야기를 계속해 보겠습니다.
+
+## 시작 시 실행 { #running-on-startup }
+
+대부분의 경우 웹 API를 만들면, 클라이언트가 언제나 접근할 수 있도록 **항상 실행**되고 중단되지 않기를 원합니다. 물론 특정 상황에서만 실행하고 싶은 특별한 이유가 있을 수는 있지만, 대부분은 지속적으로 실행되며 **사용 가능**한 상태이기를 원합니다.
+
+### 원격 서버에서 { #in-a-remote-server }
+
+원격 서버(클라우드 서버, 가상 머신 등)를 설정할 때, 가장 단순한 방법은 로컬 개발 때처럼 수동으로 `fastapi run`(Uvicorn을 사용합니다)이나 비슷한 명령을 실행하는 것입니다.
+
+이 방식은 동작하고, **개발 중에는** 유용합니다.
+
+하지만 서버에 대한 연결이 끊기면, 실행 중인 **프로세스**도 아마 종료될 것입니다.
+
+또 서버가 재시작되면(예: 업데이트 이후, 혹은 클라우드 제공자의 마이그레이션 이후) 여러분은 아마 **알아차리지 못할** 겁니다. 그 결과, 프로세스를 수동으로 다시 시작해야 한다는 사실도 모르게 됩니다. 그러면 API는 그냥 죽은 상태로 남습니다. 😱
+
+### 시작 시 자동 실행 { #run-automatically-on-startup }
+
+일반적으로 서버 프로그램(예: Uvicorn)은 서버가 시작될 때 자동으로 시작되고, **사람의 개입** 없이도 FastAPI 앱을 실행하는 프로세스가 항상 실행 중이도록(예: FastAPI 앱을 실행하는 Uvicorn) 구성하고 싶을 것입니다.
+
+### 별도의 프로그램 { #separate-program }
+
+이를 위해 보통 애플리케이션이 시작 시 실행되도록 보장하는 **별도의 프로그램**을 둡니다. 그리고 많은 경우, 데이터베이스 같은 다른 컴포넌트나 애플리케이션도 함께 실행되도록 보장합니다.
+
+### 시작 시 실행을 위한 도구 예시 { #example-tools-to-run-at-startup }
+
+이 역할을 할 수 있는 도구 예시는 다음과 같습니다:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Swarm Mode의 Docker
+* Systemd
+* Supervisor
+* 클라우드 제공자가 서비스 일부로 내부적으로 처리
+* 기타...
+
+다음 장에서 더 구체적인 예시를 제공하겠습니다.
+
+## 재시작 { #restarts }
+
+애플리케이션이 시작 시 실행되도록 보장하는 것과 비슷하게, 장애가 발생했을 때 **재시작**되도록 보장하고 싶을 것입니다.
+
+### 우리는 실수합니다 { #we-make-mistakes }
+
+사람은 언제나 **실수**합니다. 소프트웨어에는 거의 *항상* 여기저기에 숨은 **버그**가 있습니다. 🐛
+
+그리고 개발자는 버그를 발견하고 새로운 기능을 구현하면서 코드를 계속 개선합니다(새로운 버그도 추가할 수 있겠죠 😅).
+
+### 작은 오류는 자동으로 처리됨 { #small-errors-automatically-handled }
+
+FastAPI로 웹 API를 만들 때 코드에 오류가 있으면, FastAPI는 보통 그 오류를 발생시킨 단일 요청 안에만 문제를 가둡니다. 🛡
+
+클라이언트는 해당 요청에 대해 **500 Internal Server Error**를 받지만, 애플리케이션은 완전히 크래시하지 않고 다음 요청부터는 계속 동작합니다.
+
+### 더 큰 오류 - 크래시 { #bigger-errors-crashes }
+
+그럼에도 불구하고, 우리가 작성한 코드가 **전체 애플리케이션을 크래시**시켜 Uvicorn과 Python 자체가 종료되는 경우가 있을 수 있습니다. 💥
+
+그래도 한 군데 오류 때문에 애플리케이션이 죽은 채로 남아 있기를 바라지는 않을 것입니다. 망가진 경로 처리를 제외한 나머지 *경로 처리*라도 **계속 실행**되기를 원할 가능성이 큽니다.
+
+### 크래시 후 재시작 { #restart-after-crash }
+
+하지만 실행 중인 **프로세스**가 크래시하는 정말 심각한 오류의 경우에는, 적어도 몇 번은 프로세스를 **재시작**하도록 담당하는 외부 컴포넌트가 필요합니다...
+
+/// tip | 팁
+
+...다만 애플리케이션 전체가 **즉시 계속 크래시**한다면, 무한히 재시작하는 것은 아마 의미가 없을 것입니다. 그런 경우에는 개발 중에, 또는 최소한 배포 직후에 알아차릴 가능성이 큽니다.
+
+그러니 여기서는, 특정한 경우에만 전체가 크래시할 수 있고 **미래**에도 그럴 수 있으며, 그래도 재시작하는 것이 의미 있는 주요 사례에 집중해 봅시다.
+
+///
+
+애플리케이션을 재시작하는 역할은 **외부 컴포넌트**가 맡는 편이 보통 좋습니다. 그 시점에는 Uvicorn과 Python을 포함한 애플리케이션이 이미 크래시했기 때문에, 같은 앱의 같은 코드 안에서 이를 해결할 방법이 없기 때문입니다.
+
+### 자동 재시작을 위한 도구 예시 { #example-tools-to-restart-automatically }
+
+대부분의 경우 **시작 시 실행**에 사용한 도구가 자동 **재시작**도 함께 처리합니다.
+
+예를 들어 다음이 가능합니다:
+
+* Docker
+* Kubernetes
+* Docker Compose
+* Swarm Mode의 Docker
+* Systemd
+* Supervisor
+* 클라우드 제공자가 서비스 일부로 내부적으로 처리
+* 기타...
+
+## 복제 - 프로세스와 메모리 { #replication-processes-and-memory }
+
+FastAPI 애플리케이션은 Uvicorn을 실행하는 `fastapi` 명령 같은 서버 프로그램을 사용하면, **하나의 프로세스**로 실행하더라도 여러 클라이언트를 동시에 처리할 수 있습니다.
+
+하지만 많은 경우, 여러 워커 프로세스를 동시에 실행하고 싶을 것입니다.
+
+### 여러 프로세스 - 워커 { #multiple-processes-workers }
+
+단일 프로세스가 처리할 수 있는 것보다 클라이언트가 더 많고(예: 가상 머신이 그리 크지 않을 때), 서버 CPU에 **여러 코어**가 있다면, 같은 애플리케이션을 실행하는 **여러 프로세스**를 동시에 띄우고 요청을 분산시킬 수 있습니다.
+
+같은 API 프로그램을 **여러 프로세스**로 실행할 때, 이 프로세스들을 보통 **workers**라고 부릅니다.
+
+### 워커 프로세스와 포트 { #worker-processes-and-ports }
+
+[HTTPS에 대한 문서](https.md){.internal-link target=_blank}에서, 서버에서 하나의 포트와 IP 주소 조합에는 하나의 프로세스만 리스닝할 수 있다는 것을 기억하시나요?
+
+이것은 여전히 사실입니다.
+
+따라서 **여러 프로세스**를 동시에 실행하려면, 먼저 **포트에서 리스닝하는 단일 프로세스**가 있어야 하고, 그 프로세스가 어떤 방식으로든 각 워커 프로세스로 통신을 전달해야 합니다.
+
+### 프로세스당 메모리 { #memory-per-process }
+
+이제 프로그램이 메모리에 무언가를 로드한다고 해봅시다. 예를 들어 머신러닝 모델을 변수에 올리거나 큰 파일 내용을 변수에 올리는 경우입니다. 이런 것들은 서버의 **메모리(RAM)**를 어느 정도 사용합니다.
+
+그리고 여러 프로세스는 보통 **메모리를 공유하지 않습니다**. 즉, 각 실행 중인 프로세스는 자체 변수와 메모리를 갖습니다. 코드에서 메모리를 많이 사용한다면, **각 프로세스**가 그만큼의 메모리를 사용하게 됩니다.
+
+### 서버 메모리 { #server-memory }
+
+예를 들어 코드가 크기 **1 GB**의 머신러닝 모델을 로드한다고 해봅시다. API를 프로세스 하나로 실행하면 RAM을 최소 1GB 사용합니다. 그리고 **4개 프로세스**(워커 4개)를 시작하면 각각 1GB RAM을 사용합니다. 즉 총 **4 GB RAM**을 사용합니다.
+
+그런데 원격 서버나 가상 머신의 RAM이 3GB뿐이라면, 4GB를 넘게 로드하려고 할 때 문제가 생깁니다. 🚨
+
+### 여러 프로세스 - 예시 { #multiple-processes-an-example }
+
+이 예시에서는 **Manager Process**가 두 개의 **Worker Processes**를 시작하고 제어합니다.
+
+이 Manager Process는 아마 IP의 **포트**에서 리스닝하는 역할을 합니다. 그리고 모든 통신을 워커 프로세스로 전달합니다.
+
+워커 프로세스들이 실제로 애플리케이션을 실행하며, **요청**을 받아 **응답**을 반환하는 주요 연산을 수행하고, RAM에 변수로 로드한 모든 내용을 담습니다.
+
+
+
+그리고 물론 같은 머신에는 애플리케이션 외에도 **다른 프로세스**들이 실행 중일 가능성이 큽니다.
+
+흥미로운 점은 각 프로세스의 **CPU 사용률**은 시간에 따라 크게 **변동**할 수 있지만, **메모리(RAM)**는 보통 대체로 **안정적**으로 유지된다는 것입니다.
+
+매번 비슷한 양의 연산을 수행하는 API이고 클라이언트가 많다면, **CPU 사용률**도 (급격히 오르내리기보다는) *안정적일* 가능성이 큽니다.
+
+### 복제 도구와 전략 예시 { #examples-of-replication-tools-and-strategies }
+
+이를 달성하는 접근 방식은 여러 가지가 있을 수 있으며, 다음 장들에서 Docker와 컨테이너를 설명할 때 구체적인 전략을 더 알려드리겠습니다.
+
+고려해야 할 주요 제약은 **공개 IP**의 **포트**를 처리하는 **단일** 컴포넌트가 있어야 한다는 점입니다. 그리고 그 컴포넌트는 복제된 **프로세스/워커**로 통신을 **전달**할 방법이 있어야 합니다.
+
+가능한 조합과 전략 몇 가지는 다음과 같습니다:
+
+* `--workers` 옵션을 사용한 **Uvicorn**
+ * 하나의 Uvicorn **프로세스 매니저**가 **IP**와 **포트**에서 리스닝하고, **여러 Uvicorn 워커 프로세스**를 시작합니다.
+* **Kubernetes** 및 기타 분산 **컨테이너 시스템**
+ * **Kubernetes** 레이어의 무언가가 **IP**와 **포트**에서 리스닝합니다. 그리고 **여러 컨테이너**를 두어 복제하며, 각 컨테이너에는 **하나의 Uvicorn 프로세스**가 실행됩니다.
+* 이를 대신 처리해주는 **클라우드 서비스**
+ * 클라우드 서비스가 **복제를 대신 처리**해줄 가능성이 큽니다. 실행할 **프로세스**나 사용할 **컨테이너 이미지**를 정의하게 해줄 수도 있지만, 어떤 경우든 대개 **단일 Uvicorn 프로세스**를 기준으로 하고, 클라우드 서비스가 이를 복제하는 역할을 맡습니다.
+
+/// tip | 팁
+
+**컨테이너**, Docker, Kubernetes에 대한 일부 내용이 아직은 잘 이해되지 않아도 괜찮습니다.
+
+다음 장에서 컨테이너 이미지, Docker, Kubernetes 등을 더 설명하겠습니다: [컨테이너에서 FastAPI - Docker](docker.md){.internal-link target=_blank}.
+
+///
+
+## 시작 전 사전 단계 { #previous-steps-before-starting }
+
+애플리케이션을 **시작하기 전에** 어떤 단계를 수행하고 싶은 경우가 많습니다.
+
+예를 들어 **데이터베이스 마이그레이션**을 실행하고 싶을 수 있습니다.
+
+하지만 대부분의 경우, 이런 단계는 **한 번만** 수행하고 싶을 것입니다.
+
+그래서 애플리케이션을 시작하기 전에 그 **사전 단계**를 수행할 **단일 프로세스**를 두고 싶을 것입니다.
+
+또한 이후에 애플리케이션 자체를 **여러 프로세스**(여러 워커)로 시작하더라도, 사전 단계를 수행하는 프로세스는 *반드시* 하나만 실행되도록 해야 합니다. 만약 사전 단계를 **여러 프로세스**가 수행하면, **병렬로** 실행하면서 작업이 **중복**될 수 있습니다. 그리고 데이터베이스 마이그레이션처럼 민감한 작업이라면 서로 충돌을 일으킬 수 있습니다.
+
+물론 사전 단계를 여러 번 실행해도 문제가 없는 경우도 있습니다. 그런 경우에는 처리하기가 훨씬 쉽습니다.
+
+/// tip | 팁
+
+또한 설정에 따라, 어떤 경우에는 애플리케이션을 시작하기 전에 **사전 단계가 전혀 필요 없을** 수도 있다는 점을 기억하세요.
+
+그런 경우에는 이런 것들을 전혀 걱정할 필요가 없습니다. 🤷
+
+///
+
+### 사전 단계 전략 예시 { #examples-of-previous-steps-strategies }
+
+이는 여러분이 **시스템을 배포하는 방식**에 크게 좌우되며, 프로그램을 시작하는 방식, 재시작 처리 방식 등과도 연결되어 있을 가능성이 큽니다.
+
+가능한 아이디어는 다음과 같습니다:
+
+* 앱 컨테이너보다 먼저 실행되는 Kubernetes의 “Init Container”
+* 사전 단계를 실행한 다음 애플리케이션을 시작하는 bash 스크립트
+ * 이 bash 스크립트를 시작/재시작하고, 오류를 감지하는 등의 방법도 여전히 필요합니다.
+
+/// tip | 팁
+
+컨테이너로 이를 처리하는 더 구체적인 예시는 다음 장에서 제공하겠습니다: [컨테이너에서 FastAPI - Docker](docker.md){.internal-link target=_blank}.
+
+///
+
+## 리소스 활용 { #resource-utilization }
+
+서버는 여러분이 프로그램으로 소비하거나 **활용(utilize)**할 수 있는 **리소스**입니다. CPU의 계산 시간과 사용 가능한 RAM 메모리가 대표적입니다.
+
+시스템 리소스를 얼마나 소비/활용하고 싶으신가요? “많지 않게”라고 생각하기 쉽지만, 실제로는 **크래시하지 않는 선에서 가능한 한 많이** 사용하고 싶을 가능성이 큽니다.
+
+서버 3대를 비용을 내고 쓰고 있는데 RAM과 CPU를 조금만 사용한다면, 아마 **돈을 낭비**하고 💸, **서버 전력도 낭비**하고 🌎, 기타 등등이 될 수 있습니다.
+
+그 경우에는 서버를 2대만 두고, 각 서버의 리소스(CPU, 메모리, 디스크, 네트워크 대역폭 등)를 더 높은 비율로 사용하는 것이 더 나을 수 있습니다.
+
+반대로 서버 2대를 두고 CPU와 RAM을 **100%** 사용하고 있다면, 어느 시점에 프로세스 하나가 더 많은 메모리를 요청하게 되고, 서버는 디스크를 “메모리”처럼 사용해야 할 수도 있습니다(수천 배 느릴 수 있습니다). 또는 심지어 **크래시**할 수도 있습니다. 혹은 어떤 프로세스가 계산을 해야 하는데 CPU가 다시 비워질 때까지 기다려야 할 수도 있습니다.
+
+이 경우에는 **서버 한 대를 추가**로 확보하고 일부 프로세스를 그쪽에서 실행해, 모두가 **충분한 RAM과 CPU 시간**을 갖도록 하는 편이 더 낫습니다.
+
+또 어떤 이유로 API 사용량이 **급증(spike)**할 가능성도 있습니다. 바이럴이 되었거나, 다른 서비스나 봇이 사용하기 시작했을 수도 있습니다. 그런 경우를 대비해 추가 리소스를 확보해두고 싶을 수 있습니다.
+
+리소스 활용률 목표로 **임의의 수치**를 정할 수 있습니다. 예를 들어 **50%에서 90% 사이**처럼요. 요점은, 이런 것들이 배포를 조정할 때 측정하고 튜닝하는 주요 지표가 될 가능성이 크다는 것입니다.
+
+`htop` 같은 간단한 도구로 서버의 CPU와 RAM 사용량, 또는 각 프로세스별 사용량을 볼 수 있습니다. 혹은 서버 여러 대에 분산될 수도 있는 더 복잡한 모니터링 도구를 사용할 수도 있습니다.
+
+## 요약 { #recap }
+
+여기까지 애플리케이션 배포 방식을 결정할 때 염두에 두어야 할 주요 개념들을 읽었습니다:
+
+* 보안 - HTTPS
+* 시작 시 실행
+* 재시작
+* 복제(실행 중인 프로세스 수)
+* 메모리
+* 시작 전 사전 단계
+
+이 아이디어들을 이해하고 적용하는 방법을 알면, 배포를 구성하고 조정할 때 필요한 직관을 얻는 데 도움이 될 것입니다. 🤓
+
+다음 섹션에서는 따라 할 수 있는 가능한 전략의 더 구체적인 예시를 제공하겠습니다. 🚀
diff --git a/docs/ko/docs/deployment/docker.md b/docs/ko/docs/deployment/docker.md
index e8b2746c5..be04c923a 100644
--- a/docs/ko/docs/deployment/docker.md
+++ b/docs/ko/docs/deployment/docker.md
@@ -1,17 +1,17 @@
-# 컨테이너의 FastAPI - 도커
+# 컨테이너의 FastAPI - 도커 { #fastapi-in-containers-docker }
-FastAPI 어플리케이션을 배포할 때 일반적인 접근 방법은 **리눅스 컨테이너 이미지**를 생성하는 것입니다. 이 방법은 주로 **도커**를 사용해 이루어집니다. 그런 다음 해당 컨테이너 이미지를 몇가지 방법으로 배포할 수 있습니다.
+FastAPI 애플리케이션을 배포할 때 일반적인 접근 방법은 **리눅스 컨테이너 이미지**를 빌드하는 것입니다. 보통 **Docker**를 사용해 수행합니다. 그런 다음 해당 컨테이너 이미지를 몇 가지 가능한 방법 중 하나로 배포할 수 있습니다.
-리눅스 컨테이너를 사용하는 데에는 **보안**, **반복 가능성**, **단순함** 등의 장점이 있습니다.
+리눅스 컨테이너를 사용하면 **보안**, **재현 가능성**, **단순함** 등 여러 장점이 있습니다.
/// tip | 팁
-시간에 쫓기고 있고 이미 이런것들을 알고 있다면 [`Dockerfile`👇](#build-a-docker-image-for-fastapi)로 점프할 수 있습니다.
+시간이 없고 이미 이런 내용들을 알고 계신가요? 아래의 [`Dockerfile` 👇](#build-a-docker-image-for-fastapi)로 이동하세요.
///
+
+### TLS 핸드셰이크 시작 { #tls-handshake-start }
+
+그 다음 브라우저는 **포트 443**(HTTPS 포트)에서 해당 IP 주소와 통신합니다.
+
+통신의 첫 부분은 클라이언트와 서버 사이의 연결을 설정하고, 사용할 암호화 키 등을 결정하는 과정입니다.
+
+
+
+클라이언트와 서버가 TLS 연결을 설정하기 위해 상호작용하는 이 과정을 **TLS 핸드셰이크**라고 합니다.
+
+### SNI 확장을 사용하는 TLS { #tls-with-sni-extension }
+
+서버에서는 특정 **IP 주소**의 특정 **포트**에서 **하나의 프로세스만** 리스닝할 수 있습니다. 같은 IP 주소에서 다른 포트로 리스닝하는 프로세스는 있을 수 있지만, IP 주소와 포트 조합마다 하나만 가능합니다.
+
+TLS(HTTPS)는 기본적으로 특정 포트 `443`을 사용합니다. 따라서 우리가 필요한 포트는 이것입니다.
+
+이 포트에서 하나의 프로세스만 리스닝할 수 있으므로, 그 역할을 하는 프로세스는 **TLS Termination Proxy**가 됩니다.
+
+TLS Termination Proxy는 하나 이상의 **TLS 인증서**(HTTPS 인증서)에 접근할 수 있습니다.
+
+앞에서 설명한 **SNI 확장**을 사용해, TLS Termination Proxy는 이 연결에 사용할 수 있는 TLS(HTTPS) 인증서들 중에서 클라이언트가 기대하는 도메인과 일치하는 것을 확인해 선택합니다.
+
+이 경우에는 `someapp.example.com`에 대한 인증서를 사용합니다.
+
+
+
+클라이언트는 이미 해당 TLS 인증서를 생성한 주체(여기서는 Let's Encrypt이지만, 이는 뒤에서 다시 보겠습니다)를 **신뢰**하므로, 인증서가 유효한지 **검증**할 수 있습니다.
+
+그 다음 인증서를 사용해 클라이언트와 TLS Termination Proxy는 나머지 **TCP 통신**을 어떻게 **암호화할지 결정**합니다. 이로써 **TLS 핸드셰이크** 단계가 완료됩니다.
+
+이후 클라이언트와 서버는 TLS가 제공하는 **암호화된 TCP 연결**을 갖게 됩니다. 그리고 그 연결을 사용해 실제 **HTTP 통신**을 시작할 수 있습니다.
+
+이것이 바로 **HTTPS**입니다. 순수(암호화되지 않은) TCP 연결 대신 **안전한 TLS 연결** 안에서 **HTTP**를 그대로 사용하는 것입니다.
+
+/// tip | 팁
+
+통신의 암호화는 HTTP 레벨이 아니라 **TCP 레벨**에서 일어난다는 점에 주의하세요.
+
+///
+
+### HTTPS 요청 { #https-request }
+
+이제 클라이언트와 서버(구체적으로는 브라우저와 TLS Termination Proxy)가 **암호화된 TCP 연결**을 갖게 되었으니 **HTTP 통신**을 시작할 수 있습니다.
+
+따라서 클라이언트는 **HTTPS 요청**을 보냅니다. 이는 암호화된 TLS 연결을 통해 전달되는 HTTP 요청일 뿐입니다.
+
+
+
+### 요청 복호화 { #decrypt-the-request }
+
+TLS Termination Proxy는 합의된 암호화를 사용해 **요청을 복호화**하고, 애플리케이션을 실행 중인 프로세스(예: FastAPI 애플리케이션을 실행하는 Uvicorn 프로세스)에 **일반(복호화된) HTTP 요청**을 전달합니다.
+
+
+
+### HTTP 응답 { #http-response }
+
+애플리케이션은 요청을 처리하고 **일반(암호화되지 않은) HTTP 응답**을 TLS Termination Proxy로 보냅니다.
+
+
+
+### HTTPS 응답 { #https-response }
+
+그 다음 TLS Termination Proxy는 이전에 합의한 암호화( `someapp.example.com` 인증서로 시작된 것)를 사용해 **응답을 암호화**하고, 브라우저로 다시 보냅니다.
+
+이후 브라우저는 응답이 유효한지, 올바른 암호화 키로 암호화되었는지 등을 확인합니다. 그런 다음 **응답을 복호화**하고 처리합니다.
+
+
+
+클라이언트(브라우저)는 앞서 **HTTPS 인증서**로 합의한 암호화를 사용하고 있으므로, 해당 응답이 올바른 서버에서 왔다는 것을 알 수 있습니다.
+
+### 여러 애플리케이션 { #multiple-applications }
+
+같은 서버(또는 여러 서버)에는 예를 들어 다른 API 프로그램이나 데이터베이스처럼 **여러 애플리케이션**이 있을 수 있습니다.
+
+특정 IP와 포트 조합은 하나의 프로세스만 처리할 수 있지만(예시에서는 TLS Termination Proxy), 다른 애플리케이션/프로세스도 **공개 IP와 포트 조합**을 동일하게 쓰려고만 하지 않는다면 서버에서 함께 실행될 수 있습니다.
+
+
+
+이렇게 하면 TLS Termination Proxy가 **여러 도메인**에 대한 HTTPS와 인증서를 **여러 애플리케이션**에 대해 처리하고, 각 경우에 맞는 애플리케이션으로 요청을 전달할 수 있습니다.
+
+### 인증서 갱신 { #certificate-renewal }
+
+미래의 어느 시점에는 각 인증서가 **만료**됩니다(획득 후 약 3개월).
+
+그 다음에는 또 다른 프로그램(경우에 따라 별도 프로그램일 수도 있고, 경우에 따라 같은 TLS Termination Proxy일 수도 있습니다)이 Let's Encrypt와 통신하여 인증서를 갱신합니다.
+
+
+
+**TLS 인증서**는 IP 주소가 아니라 **도메인 이름**과 **연결**되어 있습니다.
+
+따라서 인증서를 갱신하려면, 갱신 프로그램이 권한 기관(Let's Encrypt)에게 해당 도메인을 실제로 **“소유”하고 제어하고 있음**을 **증명**해야 합니다.
+
+이를 위해, 그리고 다양한 애플리케이션 요구를 수용하기 위해 여러 방법이 있습니다. 널리 쓰이는 방법은 다음과 같습니다:
+
+* **일부 DNS 레코드 수정**.
+ * 이를 위해서는 갱신 프로그램이 DNS 제공업체의 API를 지원해야 하므로, 사용하는 DNS 제공업체에 따라 가능할 수도, 아닐 수도 있습니다.
+* 도메인과 연결된 공개 IP 주소에서 **서버로 실행**(적어도 인증서 발급 과정 동안).
+ * 앞에서 말했듯 특정 IP와 포트에서는 하나의 프로세스만 리스닝할 수 있습니다.
+ * 이것이 동일한 TLS Termination Proxy가 인증서 갱신 과정까지 처리할 때 매우 유용한 이유 중 하나입니다.
+ * 그렇지 않으면 TLS Termination Proxy를 잠시 중지하고, 갱신 프로그램을 시작해 인증서를 획득한 다음, TLS Termination Proxy에 인증서를 설정하고, 다시 TLS Termination Proxy를 재시작해야 할 수도 있습니다. 이는 TLS Termination Proxy가 꺼져 있는 동안 앱(들)을 사용할 수 없으므로 이상적이지 않습니다.
+
+앱을 계속 제공하면서 이 갱신 과정을 처리할 수 있는 것은, 애플리케이션 서버(예: Uvicorn)에서 TLS 인증서를 직접 쓰는 대신 TLS Termination Proxy로 HTTPS를 처리하는 **별도의 시스템**을 두고 싶어지는 주요 이유 중 하나입니다.
+
+## 프록시 전달 헤더 { #proxy-forwarded-headers }
+
+프록시를 사용해 HTTPS를 처리할 때, **애플리케이션 서버**(예: FastAPI CLI를 통한 Uvicorn)는 HTTPS 과정에 대해 아무것도 알지 못하고 **TLS Termination Proxy**와는 일반 HTTP로 통신합니다.
+
+이 **프록시**는 보통 요청을 **애플리케이션 서버**에 전달하기 전에, 요청이 프록시에 의해 **전달(forwarded)**되고 있음을 애플리케이션 서버가 알 수 있도록 일부 HTTP 헤더를 즉석에서 설정합니다.
+
+/// note | 기술 세부사항
+
+프록시 헤더는 다음과 같습니다:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+그럼에도 불구하고 **애플리케이션 서버**는 자신이 신뢰할 수 있는 **프록시** 뒤에 있다는 것을 모르므로, 기본적으로는 그 헤더들을 신뢰하지 않습니다.
+
+하지만 **애플리케이션 서버**가 **프록시**가 보낸 *forwarded* 헤더를 신뢰하도록 설정할 수 있습니다. FastAPI CLI를 사용하고 있다면, *CLI Option* `--forwarded-allow-ips`를 사용해 어떤 IP에서 온 *forwarded* 헤더를 신뢰할지 지정할 수 있습니다.
+
+예를 들어 **애플리케이션 서버**가 신뢰하는 **프록시**로부터만 통신을 받는다면, `--forwarded-allow-ips="*"`로 설정해 들어오는 모든 IP를 신뢰하게 할 수 있습니다. 어차피 **프록시**가 사용하는 IP에서만 요청을 받게 될 것이기 때문입니다.
+
+이렇게 하면 애플리케이션은 자신이 사용하는 공개 URL이 무엇인지, HTTPS를 사용하는지, 도메인이 무엇인지 등을 알 수 있습니다.
+
+예를 들어 리다이렉트를 올바르게 처리하는 데 유용합니다.
+
+/// tip | 팁
+
+이에 대해서는 [프록시 뒤에서 실행하기 - 프록시 전달 헤더 활성화](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} 문서에서 더 알아볼 수 있습니다.
+
+///
+
+## 요약 { #recap }
+
+**HTTPS**는 매우 중요하며, 대부분의 경우 상당히 **핵심적**입니다. 개발자가 HTTPS와 관련해 해야 하는 노력의 대부분은 결국 **이 개념들을 이해**하고 그것들이 어떻게 동작하는지 파악하는 것입니다.
+
+하지만 **개발자를 위한 HTTPS**의 기본 정보를 알고 나면, 여러 도구를 쉽게 조합하고 설정하여 모든 것을 간단하게 관리할 수 있습니다.
+
+다음 장들에서는 **FastAPI** 애플리케이션을 위한 **HTTPS** 설정 방법을 여러 구체적인 예시로 보여드리겠습니다. 🔒
diff --git a/docs/ko/docs/deployment/index.md b/docs/ko/docs/deployment/index.md
index 87b05b68f..e0d237534 100644
--- a/docs/ko/docs/deployment/index.md
+++ b/docs/ko/docs/deployment/index.md
@@ -1,21 +1,23 @@
-# 배포하기 - 들어가면서
+# 배포 { #deployment }
-**FastAPI**을 배포하는 것은 비교적 쉽습니다.
+**FastAPI** 애플리케이션을 배포하는 것은 비교적 쉽습니다.
-## 배포의 의미
+## 배포의 의미 { #what-does-deployment-mean }
-**배포**란 애플리케이션을 **사용자가 사용**할 수 있도록 하는 데 필요한 단계를 수행하는 것을 의미합니다.
+애플리케이션을 **배포**한다는 것은 **사용자가 사용**할 수 있도록 하는 데 필요한 단계를 수행하는 것을 의미합니다.
-**웹 API**의 경우, 일반적으로 **사용자**가 중단이나 오류 없이 애플리케이션에 효율적으로 **접근**할 수 있도록 좋은 성능, 안정성 등을 제공하는 **서버 프로그램과** 함께 **원격 시스템**에 이를 설치하는 작업을 의미합니다.
+**웹 API**의 경우, 일반적으로 **원격 머신**에 이를 설치하고, 좋은 성능, 안정성 등을 제공하는 **서버 프로그램**과 함께 구성하여 **사용자**가 중단이나 문제 없이 애플리케이션에 효율적으로 **접근**할 수 있게 하는 것을 포함합니다.
-이는 지속적으로 코드를 변경하고, 지우고, 수정하고, 개발 서버를 중지했다가 다시 시작하는 등의 **개발** 단계와 대조됩니다.
+이는 지속적으로 코드를 변경하고, 망가뜨리고 고치고, 개발 서버를 중지했다가 다시 시작하는 등의 **개발** 단계와 대조됩니다.
-## 배포 전략
+## 배포 전략 { #deployment-strategies }
-사용하는 도구나 특정 사례에 따라 여러 가지 방법이 있습니다.
+구체적인 사용 사례와 사용하는 도구에 따라 여러 가지 방법이 있습니다.
-배포도구들을 사용하여 직접 **서버에 배포**하거나, 배포작업의 일부를 수행하는 **클라우드 서비스** 또는 다른 방법을 사용할 수도 있습니다.
+여러 도구를 조합해 직접 **서버를 배포**할 수도 있고, 작업의 일부를 대신해 주는 **클라우드 서비스**를 사용할 수도 있으며, 다른 가능한 선택지도 있습니다.
-**FastAPI** 애플리케이션을 배포할 때 선택할 수 있는 몇 가지 주요 방법을 보여 드리겠습니다 (대부분 다른 유형의 웹 애플리케이션에도 적용됩니다).
+예를 들어, FastAPI 뒤에 있는 저희 팀은 FastAPI로 작업하는 것과 같은 개발자 경험을 유지하면서, FastAPI 앱을 클라우드에 가능한 한 간소화된 방식으로 배포할 수 있도록 **FastAPI Cloud**를 만들었습니다.
-다음 차례에 자세한 내용과 이를 위한 몇 가지 기술을 볼 수 있습니다. ✨
+**FastAPI** 애플리케이션을 배포할 때 아마 염두에 두어야 할 몇 가지 주요 개념을 보여드리겠습니다(대부분은 다른 유형의 웹 애플리케이션에도 적용됩니다).
+
+다음 섹션에서 염두에 둘 더 많은 세부사항과 이를 위한 몇 가지 기술을 볼 수 있습니다. ✨
diff --git a/docs/ko/docs/deployment/manually.md b/docs/ko/docs/deployment/manually.md
new file mode 100644
index 000000000..e85dd02a3
--- /dev/null
+++ b/docs/ko/docs/deployment/manually.md
@@ -0,0 +1,157 @@
+# 서버를 수동으로 실행하기 { #run-a-server-manually }
+
+## `fastapi run` 명령 사용하기 { #use-the-fastapi-run-command }
+
+요약하면, `fastapi run`을 사용해 FastAPI 애플리케이션을 서비스하세요:
+
+---- +**FastAPI**는 다른 사람들이 이전에 해온 작업이 없었다면 존재하지 않았을 것입니다. -## 조사 +그 전에 만들어진 많은 도구들이 이것의 탄생에 영감을 주었습니다. -여러 대안을 사용해 보며 다양한 도구에서 배운 점들을 모아 저와 개발팀에게 가장 적합한 방식을 찾았습니다. +저는 여러 해 동안 새로운 프레임워크를 만드는 것을 피하고 있었습니다. 처음에는 **FastAPI**가 다루는 모든 기능을 여러 다른 프레임워크, 플러그인, 도구들을 사용해 해결하려고 했습니다. -예를 들어, 표준 :term:Python 타입 힌트-그래서 **FastAPI**의 코드를 작성하기 전에 몇 달 동안 OpenAPI, JSON Schema, OAuth2 명세를 연구하며 이들의 관계와 겹치는 부분, 차이점을 이해했습니다. +## 조사 { #investigation } ---- +이전의 모든 대안을 사용해 보면서, 각 도구로부터 배울 기회를 얻었고, 아이디어를 가져와 제가 일해온 개발 팀들과 저 자신에게 가장 적합하다고 찾은 방식으로 조합할 수 있었습니다. -## 디자인 +예를 들어, 이상적으로는 표준 Python 타입 힌트에 기반해야 한다는 점이 분명했습니다. -그 후, **FastAPI** 사용자가 될 개발자로서 사용하고 싶은 개발자 "API"를 디자인했습니다. +또한, 가장 좋은 접근법은 이미 존재하는 표준을 사용하는 것이었습니다. -[Python Developer Survey](https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools)에 따르면 약 80%의 Python 개발자가 PyCharm, VS Code, Jedi 기반 편집기 등에서 개발합니다. 이 과정에서 여러 아이디어를 테스트했습니다. +그래서 **FastAPI**의 코딩을 시작하기도 전에, OpenAPI, JSON Schema, OAuth2 등과 같은 명세를 몇 달 동안 공부했습니다. 이들의 관계, 겹치는 부분, 차이점을 이해하기 위해서였습니다. -대부분의 다른 편집기도 유사하게 동작하기 때문에, **FastAPI**의 이점은 거의 모든 편집기에서 누릴 수 있습니다. +## 디자인 { #design } -이 과정을 통해 코드 중복을 최소화하고, 모든 곳에서 자동 완성, 타입 검사, 에러 확인 기능이 제공되는 최적의 방식을 찾아냈습니다. +그 다음에는 (FastAPI를 사용하는 개발자로서) 사용자로서 갖고 싶었던 개발자 "API"를 디자인하는 데 시간을 썼습니다. -이 모든 것은 개발자들에게 최고의 개발 경험을 제공하기 위해 설계되었습니다. +가장 인기 있는 Python 편집기들: PyCharm, VS Code, Jedi 기반 편집기에서 여러 아이디어를 테스트했습니다. ---- +약 80%의 사용자를 포함하는 최근 Python Developer Survey에 따르면 그렇습니다. -## 필요조건 +즉, **FastAPI**는 Python 개발자의 80%가 사용하는 편집기들로 특별히 테스트되었습니다. 그리고 대부분의 다른 편집기도 유사하게 동작하는 경향이 있으므로, 그 모든 이점은 사실상 모든 편집기에서 동작해야 합니다. -여러 대안을 테스트한 후, [Pydantic](https://docs.pydantic.dev/)을 사용하기로 결정했습니다. +그렇게 해서 코드 중복을 가능한 한 많이 줄이고, 어디서나 자동 완성, 타입 및 에러 검사 등을 제공하는 최선의 방법을 찾을 수 있었습니다. -이후 저는 **Pydantic**이 JSON Schema와 완벽히 호환되도록 개선하고, 다양한 제약 조건 선언을 지원하며, 여러 편집기에서의 자동 완성과 타입 검사 기능을 향상하기 위해 기여했습니다. +모든 개발자에게 최고의 개발 경험을 제공하는 방식으로 말입니다. -또한, 또 다른 주요 필요조건이었던 [Starlette](https://www.starlette.io/)에도 기여했습니다. +## 필요조건 { #requirements } ---- +여러 대안을 테스트한 후, 장점 때문에 **Pydantic**을 사용하기로 결정했습니다. -## 개발 +그 후, JSON Schema를 완전히 준수하도록 하고, 제약 조건 선언을 정의하는 다양한 방식을 지원하며, 여러 편집기에서의 테스트를 바탕으로 편집기 지원(타입 검사, 자동 완성)을 개선하기 위해 기여했습니다. -**FastAPI**를 개발하기 시작할 즈음에는 대부분의 준비가 이미 완료된 상태였습니다. 설계가 정의되었고, 필요조건과 도구가 준비되었으며, 표준과 명세에 대한 지식도 충분했습니다. +개발 과정에서, 또 다른 핵심 필요조건인 **Starlette**에도 기여했습니다. ---- +## 개발 { #development } -## 미래 +**FastAPI** 자체를 만들기 시작했을 때쯤에는, 대부분의 조각들이 이미 갖춰져 있었고, 디자인은 정의되어 있었으며, 필요조건과 도구는 준비되어 있었고, 표준과 명세에 대한 지식도 명확하고 최신 상태였습니다. -현시점에서 **FastAPI**가 많은 사람들에게 유용하다는 것이 명백해졌습니다. +## 미래 { #future } -여러 용도에 더 적합한 도구로서 기존 대안보다 선호되고 있습니다. -이미 많은 개발자와 팀들이 **FastAPI**에 의존해 프로젝트를 진행 중입니다 (저와 제 팀도 마찬가지입니다). +이 시점에는, **FastAPI**가 그 아이디어와 함께 많은 사람들에게 유용하다는 것이 이미 분명합니다. -하지만 여전히 개선해야 할 점과 추가할 기능들이 많이 남아 있습니다. +많은 사용 사례에 더 잘 맞기 때문에 이전 대안들보다 선택되고 있습니다. + +많은 개발자와 팀이 이미 자신의 프로젝트를 위해 **FastAPI**에 의존하고 있습니다(저와 제 팀도 포함해서요). + +하지만 여전히, 앞으로 나올 개선 사항과 기능들이 많이 있습니다. + +**FastAPI**의 미래는 밝습니다. -**FastAPI**는 밝은 미래로 나아가고 있습니다. 그리고 [여러분의 도움](help-fastapi.md){.internal-link target=_blank}은 큰 힘이 됩니다. diff --git a/docs/ko/docs/how-to/authentication-error-status-code.md b/docs/ko/docs/how-to/authentication-error-status-code.md new file mode 100644 index 000000000..47120cae6 --- /dev/null +++ b/docs/ko/docs/how-to/authentication-error-status-code.md @@ -0,0 +1,17 @@ +# 이전 403 인증 오류 상태 코드 사용하기 { #use-old-403-authentication-error-status-codes } + +FastAPI 버전 `0.122.0` 이전에는, 통합 보안 유틸리티가 인증 실패 후 클라이언트에 오류를 반환할 때 HTTP 상태 코드 `403 Forbidden`을 사용했습니다. + +FastAPI 버전 `0.122.0`부터는 더 적절한 HTTP 상태 코드 `401 Unauthorized`를 사용하며, HTTP 명세인 RFC 7235, RFC 9110를 따라 응답에 합리적인 `WWW-Authenticate` 헤더를 반환합니다. + +하지만 어떤 이유로든 클라이언트가 이전 동작에 의존하고 있다면, 보안 클래스에서 `make_not_authenticated_error` 메서드를 오버라이드하여 이전 동작으로 되돌릴 수 있습니다. + +예를 들어, 기본값인 `401 Unauthorized` 오류 대신 `403 Forbidden` 오류를 반환하는 `HTTPBearer`의 서브클래스를 만들 수 있습니다: + +{* ../../docs_src/authentication_error_status_code/tutorial001_an_py39.py hl[9:13] *} + +/// tip | 팁 + +함수는 예외를 `raise`하는 것이 아니라 예외 인스턴스를 `return`한다는 점에 유의하세요. 예외를 발생시키는(`raise`) 작업은 내부 코드의 나머지 부분에서 수행됩니다. + +/// diff --git a/docs/ko/docs/how-to/conditional-openapi.md b/docs/ko/docs/how-to/conditional-openapi.md index 79c7f0dd2..16e683366 100644 --- a/docs/ko/docs/how-to/conditional-openapi.md +++ b/docs/ko/docs/how-to/conditional-openapi.md @@ -1,46 +1,41 @@ -# 조건부적인 OpenAPI +# 조건부 OpenAPI { #conditional-openapi } -필요한 경우, 설정 및 환경 변수를 사용하여 환경에 따라 조건부로 OpenAPI를 구성하고 완전히 비활성화할 수도 있습니다. +필요한 경우, 설정 및 환경 변수를 사용하여 환경에 따라 OpenAPI를 조건부로 구성하고 완전히 비활성화할 수도 있습니다. -## 보안, API 및 docs에 대해서 +## 보안, API 및 docs에 대해서 { #about-security-apis-and-docs } 프로덕션에서, 문서화된 사용자 인터페이스(UI)를 숨기는 것이 API를 보호하는 방법이 *되어서는 안 됩니다*. -이는 API에 추가적인 보안을 제공하지 않으며, *경로 작업*은 여전히 동일한 위치에서 사용 할 수 있습니다. +이는 API에 추가적인 보안을 제공하지 않으며, *경로 처리*는 여전히 동일한 위치에서 사용 할 수 있습니다. 코드에 보안 결함이 있다면, 그 결함은 여전히 존재할 것입니다. -문서를 숨기는 것은 API와 상호작용하는 방법을 이해하기 어렵게 만들며, 프로덕션에서 디버깅을 더 어렵게 만들 수 있습니다. 이는 단순히 '모호성에 의한 보안'의 한 형태로 간주될 수 있습니다. +문서를 숨기는 것은 API와 상호작용하는 방법을 이해하기 어렵게 만들며, 프로덕션에서 디버깅을 더 어렵게 만들 수 있습니다. 이는 단순히 Security through obscurity의 한 형태로 간주될 수 있습니다. API를 보호하고 싶다면, 예를 들어 다음과 같은 더 나은 방법들이 있습니다: -* 요청 본문과 응답에 대해 잘 정의된 Pydantic 모델을 사용하도록 하세요. - +* 요청 본문과 응답에 대해 잘 정의된 Pydantic 모델이 있는지 확인하세요. * 종속성을 사용하여 필요한 권한과 역할을 구성하세요. - -* 평문 비밀번호를 절대 저장하지 말고, 오직 암호화된 비밀번호만 저장하세요. - -* Passlib과 JWT 토큰과 같은 잘 알려진 암호화 도구들을 구현하고 사용하세요. - +* 평문 비밀번호를 절대 저장하지 말고, 비밀번호 해시만 저장하세요. +* pwdlib와 JWT 토큰 등과 같은 잘 알려진 암호화 도구들을 구현하고 사용하세요. * 필요한 곳에 OAuth2 범위를 사용하여 더 세분화된 권한 제어를 추가하세요. +* ...등등. -* 등등.... - -그럼에도 불구하고, 특정 환경(예: 프로덕션)에서 또는 환경 변수의 설정에 따라 API 문서를 비활성화해야 하는 매우 특정한 사용 사례가 있을 수 있습니다. +그럼에도 불구하고, 특정 환경(예: 프로덕션)에서 또는 환경 변수의 설정에 따라 API docs를 비활성화해야 하는 매우 특정한 사용 사례가 있을 수 있습니다. -## 설정 및 환경변수의 조건부 OpenAPI +## 설정 및 환경변수의 조건부 OpenAPI { #conditional-openapi-from-settings-and-env-vars } -동일한 Pydantic 설정을 사용하여 생성된 OpenAPI 및 문서 UI를 쉽게 구성할 수 있습니다. +동일한 Pydantic 설정을 사용하여 생성된 OpenAPI 및 docs UI를 쉽게 구성할 수 있습니다. 예를 들어: -{* ../../docs_src/conditional_openapi/tutorial001.py hl[6,11] *} +{* ../../docs_src/conditional_openapi/tutorial001_py39.py hl[6,11] *} 여기서 `openapi_url` 설정을 기본값인 `"/openapi.json"`으로 선언합니다. 그런 뒤, 우리는 `FastAPI` 앱을 만들 때 그것을 사용합니다. -환경 변수 `OPENAPI_URL`을 빈 문자열로 설정하여 OpenAPI(문서 UI 포함)를 비활성화할 수도 있습니다. 예를 들어: +그런 다음 환경 변수 `OPENAPI_URL`을 빈 문자열로 설정하여 OpenAPI(UI docs 포함)를 비활성화할 수도 있습니다. 예를 들어:에 기반하는 것이 이상적이라는 점이 명확했습니다. +하지만 어느 시점에는, 이전 도구들의 최고의 아이디어를 가져와 가능한 한 최선의 방식으로 조합하고, 이전에는 존재하지 않았던 언어 기능(Python 3.6+ type hints)을 사용해 이 모든 기능을 제공하는 무언가를 만드는 것 외에는 다른 선택지가 없었습니다. -또한, 이미 존재하는 표준을 활용하는 것이 가장 좋은 접근법이라 판단했습니다. +
-## 테마 변경
+## 테마 변경 { #change-the-theme }
동일한 방식으로 `"syntaxHighlight.theme"` 키를 사용하여 구문 강조 테마를 설정할 수 있습니다 (중간에 점이 포함된 것을 참고하십시오).
-{* ../../docs_src/configure_swagger_ui/tutorial002.py hl[3] *}
+{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *}
이 설정은 구문 강조 색상 테마를 변경합니다:
-## 기본 Swagger UI 매개변수 변경
+## 기본 Swagger UI 매개변수 변경 { #change-default-swagger-ui-parameters }
FastAPI는 대부분의 사용 사례에 적합한 몇 가지 기본 구성 매개변수를 포함하고 있습니다.
기본 구성에는 다음이 포함됩니다:
-{* ../../fastapi/openapi/docs.py ln[8:23] hl[17:23] *}
+{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}
`swagger_ui_parameters` 인수에 다른 값을 설정하여 이러한 기본값 중 일부를 재정의할 수 있습니다.
예를 들어, `deepLinking`을 비활성화하려면 `swagger_ui_parameters`에 다음 설정을 전달할 수 있습니다:
-{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
+{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *}
-## 기타 Swagger UI 매개변수
+## 기타 Swagger UI 매개변수 { #other-swagger-ui-parameters }
-사용할 수 있는 다른 모든 구성 옵션을 확인하려면, Swagger UI 매개변수에 대한 공식 문서를 참조하십시오.
+사용할 수 있는 다른 모든 구성 옵션을 확인하려면, Swagger UI 매개변수에 대한 공식 Swagger UI 매개변수 문서를 참조하십시오.
-## JavaScript 전용 설정
+## JavaScript 전용 설정 { #javascript-only-settings }
Swagger UI는 **JavaScript 전용** 객체(예: JavaScript 함수)로 다른 구성을 허용하기도 합니다.
@@ -67,4 +67,4 @@ presets: [
이들은 문자열이 아닌 **JavaScript** 객체이므로 Python 코드에서 직접 전달할 수 없습니다.
-이와 같은 JavaScript 전용 구성을 사용해야 하는 경우, 위의 방법 중 하나를 사용하여 모든 Swagger UI 경로 작업을 재정의하고 필요한 JavaScript를 수동으로 작성할 수 있습니다.
+이와 같은 JavaScript 전용 구성을 사용해야 하는 경우, 위의 방법 중 하나를 사용할 수 있습니다. Swagger UI *경로 처리*를 모두 재정의하고 필요한 JavaScript를 수동으로 작성하세요.
diff --git a/docs/ko/docs/how-to/custom-docs-ui-assets.md b/docs/ko/docs/how-to/custom-docs-ui-assets.md
new file mode 100644
index 000000000..d6383c29c
--- /dev/null
+++ b/docs/ko/docs/how-to/custom-docs-ui-assets.md
@@ -0,0 +1,185 @@
+# 커스텀 Docs UI 정적 에셋(자체 호스팅) { #custom-docs-ui-static-assets-self-hosting }
+
+API 문서는 **Swagger UI**와 **ReDoc**을 사용하며, 각각 JavaScript와 CSS 파일이 필요합니다.
+
+기본적으로 이러한 파일은 CDN에서 제공됩니다.
+
+하지만 이를 커스터마이징할 수 있으며, 특정 CDN을 지정하거나 파일을 직접 제공할 수도 있습니다.
+
+## JavaScript와 CSS용 커스텀 CDN { #custom-cdn-for-javascript-and-css }
+
+예를 들어 다른 CDN을 사용하고 싶다고 해봅시다. 예를 들면 `https://unpkg.com/`을 사용하려는 경우입니다.
+
+이는 예를 들어 특정 국가에서 일부 URL을 제한하는 경우에 유용할 수 있습니다.
+
+### 자동 문서 비활성화하기 { #disable-the-automatic-docs }
+
+첫 번째 단계는 자동 문서를 비활성화하는 것입니다. 기본적으로 자동 문서는 기본 CDN을 사용하기 때문입니다.
+
+비활성화하려면 `FastAPI` 앱을 생성할 때 해당 URL을 `None`으로 설정하세요:
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *}
+
+### 커스텀 문서 포함하기 { #include-the-custom-docs }
+
+이제 커스텀 문서를 위한 *경로 처리*를 만들 수 있습니다.
+
+FastAPI 내부 함수를 재사용해 문서용 HTML 페이지를 생성하고, 필요한 인자를 전달할 수 있습니다:
+
+* `openapi_url`: 문서 HTML 페이지가 API의 OpenAPI 스키마를 가져올 수 있는 URL입니다. 여기서는 `app.openapi_url` 속성을 사용할 수 있습니다.
+* `title`: API의 제목입니다.
+* `oauth2_redirect_url`: 기본값을 사용하려면 여기서 `app.swagger_ui_oauth2_redirect_url`을 사용할 수 있습니다.
+* `swagger_js_url`: Swagger UI 문서의 HTML이 **JavaScript** 파일을 가져올 수 있는 URL입니다. 커스텀 CDN URL입니다.
+* `swagger_css_url`: Swagger UI 문서의 HTML이 **CSS** 파일을 가져올 수 있는 URL입니다. 커스텀 CDN URL입니다.
+
+ReDoc도 마찬가지입니다...
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *}
+
+/// tip | 팁
+
+`swagger_ui_redirect`에 대한 *경로 처리*는 OAuth2를 사용할 때 도움이 되는 헬퍼입니다.
+
+API를 OAuth2 provider와 통합하면 인증을 수행한 뒤 획득한 자격 증명으로 API 문서로 다시 돌아올 수 있습니다. 그리고 실제 OAuth2 인증을 사용해 API와 상호작용할 수 있습니다.
+
+Swagger UI가 이 과정을 백그라운드에서 처리해 주지만, 이를 위해 이 "redirect" 헬퍼가 필요합니다.
+
+///
+
+### 테스트용 *경로 처리* 만들기 { #create-a-path-operation-to-test-it }
+
+이제 모든 것이 제대로 동작하는지 테스트할 수 있도록 *경로 처리*를 하나 만드세요:
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *}
+
+### 테스트하기 { #test-it }
+
+이제 http://127.0.0.1:8000/docs에서 문서에 접속한 뒤 페이지를 새로고침하면, 새 CDN에서 에셋을 불러오는 것을 확인할 수 있습니다.
+
+## 문서용 JavaScript와 CSS 자체 호스팅하기 { #self-hosting-javascript-and-css-for-docs }
+
+JavaScript와 CSS를 자체 호스팅하는 것은 예를 들어, 오프라인 상태이거나 외부 인터넷에 접근할 수 없는 환경, 또는 로컬 네트워크에서도 앱이 계속 동작해야 할 때 유용할 수 있습니다.
+
+여기서는 동일한 FastAPI 앱에서 해당 파일을 직접 제공하고, 문서가 이를 사용하도록 설정하는 방법을 살펴봅니다.
+
+### 프로젝트 파일 구조 { #project-file-structure }
+
+프로젝트 파일 구조가 다음과 같다고 해봅시다:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+```
+
+이제 해당 정적 파일을 저장할 디렉터리를 만드세요.
+
+새 파일 구조는 다음과 같을 수 있습니다:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static/
+```
+
+### 파일 다운로드하기 { #download-the-files }
+
+문서에 필요한 정적 파일을 다운로드해서 `static/` 디렉터리에 넣으세요.
+
+각 링크를 우클릭한 뒤 "링크를 다른 이름으로 저장..."과 비슷한 옵션을 선택하면 될 것입니다.
+
+**Swagger UI**는 다음 파일을 사용합니다:
+
+* `swagger-ui-bundle.js`
+* `swagger-ui.css`
+
+**ReDoc**은 다음 파일을 사용합니다:
+
+* `redoc.standalone.js`
+
+이후 파일 구조는 다음과 같을 수 있습니다:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static
+ ├── redoc.standalone.js
+ ├── swagger-ui-bundle.js
+ └── swagger-ui.css
+```
+
+### 정적 파일 제공하기 { #serve-the-static-files }
+
+* `StaticFiles`를 import합니다.
+* 특정 경로에 `StaticFiles()` 인스턴스를 "마운트(mount)"합니다.
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *}
+
+### 정적 파일 테스트하기 { #test-the-static-files }
+
+애플리케이션을 시작하고 http://127.0.0.1:8000/static/redoc.standalone.js로 이동하세요.
+
+**ReDoc**용 매우 긴 JavaScript 파일이 보일 것입니다.
+
+예를 들어 다음과 같이 시작할 수 있습니다:
+
+```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")):
+...
+```
+
+이는 앱에서 정적 파일을 제공할 수 있고, 문서용 정적 파일을 올바른 위치에 배치했다는 것을 확인해 줍니다.
+
+이제 문서가 이 정적 파일을 사용하도록 앱을 설정할 수 있습니다.
+
+### 정적 파일을 위한 자동 문서 비활성화하기 { #disable-the-automatic-docs-for-static-files }
+
+커스텀 CDN을 사용할 때와 마찬가지로, 첫 단계는 자동 문서를 비활성화하는 것입니다. 자동 문서는 기본적으로 CDN을 사용합니다.
+
+비활성화하려면 `FastAPI` 앱을 생성할 때 해당 URL을 `None`으로 설정하세요:
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *}
+
+### 정적 파일을 위한 커스텀 문서 포함하기 { #include-the-custom-docs-for-static-files }
+
+그리고 커스텀 CDN을 사용할 때와 동일한 방식으로, 이제 커스텀 문서를 위한 *경로 처리*를 만들 수 있습니다.
+
+다시 한 번, FastAPI 내부 함수를 재사용해 문서용 HTML 페이지를 생성하고, 필요한 인자를 전달할 수 있습니다:
+
+* `openapi_url`: 문서 HTML 페이지가 API의 OpenAPI 스키마를 가져올 수 있는 URL입니다. 여기서는 `app.openapi_url` 속성을 사용할 수 있습니다.
+* `title`: API의 제목입니다.
+* `oauth2_redirect_url`: 기본값을 사용하려면 여기서 `app.swagger_ui_oauth2_redirect_url`을 사용할 수 있습니다.
+* `swagger_js_url`: Swagger UI 문서의 HTML이 **JavaScript** 파일을 가져올 수 있는 URL입니다. **이제는 여러분의 앱이 직접 제공하는 파일입니다**.
+* `swagger_css_url`: Swagger UI 문서의 HTML이 **CSS** 파일을 가져올 수 있는 URL입니다. **이제는 여러분의 앱이 직접 제공하는 파일입니다**.
+
+ReDoc도 마찬가지입니다...
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[2:6,14:22,25:27,30:36] *}
+
+/// tip | 팁
+
+`swagger_ui_redirect`에 대한 *경로 처리*는 OAuth2를 사용할 때 도움이 되는 헬퍼입니다.
+
+API를 OAuth2 provider와 통합하면 인증을 수행한 뒤 획득한 자격 증명으로 API 문서로 다시 돌아올 수 있습니다. 그리고 실제 OAuth2 인증을 사용해 API와 상호작용할 수 있습니다.
+
+Swagger UI가 이 과정을 백그라운드에서 처리해 주지만, 이를 위해 이 "redirect" 헬퍼가 필요합니다.
+
+///
+
+### 정적 파일 테스트용 *경로 처리* 만들기 { #create-a-path-operation-to-test-static-files }
+
+이제 모든 것이 제대로 동작하는지 테스트할 수 있도록 *경로 처리*를 하나 만드세요:
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[39:41] *}
+
+### 정적 파일 UI 테스트하기 { #test-static-files-ui }
+
+이제 WiFi 연결을 끊고 http://127.0.0.1:8000/docs에서 문서에 접속한 뒤 페이지를 새로고침해 보세요.
+
+인터넷이 없어도 API 문서를 보고, API와 상호작용할 수 있을 것입니다.
diff --git a/docs/ko/docs/how-to/custom-request-and-route.md b/docs/ko/docs/how-to/custom-request-and-route.md
new file mode 100644
index 000000000..335193bb3
--- /dev/null
+++ b/docs/ko/docs/how-to/custom-request-and-route.md
@@ -0,0 +1,109 @@
+# 커스텀 Request 및 APIRoute 클래스 { #custom-request-and-apiroute-class }
+
+일부 경우에는 `Request`와 `APIRoute` 클래스에서 사용되는 로직을 오버라이드하고 싶을 수 있습니다.
+
+특히, 이는 middleware에 있는 로직의 좋은 대안이 될 수 있습니다.
+
+예를 들어, 애플리케이션에서 처리되기 전에 요청 바디를 읽거나 조작하고 싶을 때가 그렇습니다.
+
+/// danger | 위험
+
+이 기능은 "고급" 기능입니다.
+
+**FastAPI**를 이제 막 시작했다면 이 섹션은 건너뛰는 것이 좋습니다.
+
+///
+
+## 사용 사례 { #use-cases }
+
+사용 사례에는 다음이 포함됩니다:
+
+* JSON이 아닌 요청 바디를 JSON으로 변환하기(예: `msgpack`).
+* gzip으로 압축된 요청 바디 압축 해제하기.
+* 모든 요청 바디를 자동으로 로깅하기.
+
+## 커스텀 요청 바디 인코딩 처리하기 { #handling-custom-request-body-encodings }
+
+커스텀 `Request` 서브클래스를 사용해 gzip 요청의 압축을 해제하는 방법을 살펴보겠습니다.
+
+그리고 그 커스텀 요청 클래스를 사용하기 위한 `APIRoute` 서브클래스도 함께 보겠습니다.
+
+### 커스텀 `GzipRequest` 클래스 만들기 { #create-a-custom-gziprequest-class }
+
+/// tip | 팁
+
+이 예시는 동작 방식 시연을 위한 장난감 예제입니다. Gzip 지원이 필요하다면 제공되는 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}를 사용할 수 있습니다.
+
+///
+
+먼저, `GzipRequest` 클래스를 만듭니다. 이 클래스는 `Request.body()` 메서드를 덮어써서, 적절한 헤더가 있는 경우 바디를 압축 해제합니다.
+
+헤더에 `gzip`이 없으면 바디를 압축 해제하려고 시도하지 않습니다.
+
+이렇게 하면 동일한 route 클래스가 gzip으로 압축된 요청과 압축되지 않은 요청을 모두 처리할 수 있습니다.
+
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}
+
+### 커스텀 `GzipRoute` 클래스 만들기 { #create-a-custom-gziproute-class }
+
+다음으로, `GzipRequest`를 활용하는 `fastapi.routing.APIRoute`의 커스텀 서브클래스를 만듭니다.
+
+이번에는 `APIRoute.get_route_handler()` 메서드를 오버라이드합니다.
+
+이 메서드는 함수를 반환합니다. 그리고 그 함수가 요청을 받아 응답을 반환합니다.
+
+여기서는 원본 요청으로부터 `GzipRequest`를 만들기 위해 이를 사용합니다.
+
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *}
+
+/// note | 기술 세부사항
+
+`Request`에는 `request.scope` 속성이 있는데, 이는 요청과 관련된 메타데이터를 담고 있는 Python `dict`입니다.
+
+`Request`에는 또한 `request.receive`가 있는데, 이는 요청의 바디를 "받기(receive)" 위한 함수입니다.
+
+`scope` `dict`와 `receive` 함수는 모두 ASGI 명세의 일부입니다.
+
+그리고 이 두 가지, `scope`와 `receive`가 새로운 `Request` 인스턴스를 만드는 데 필요한 것들입니다.
+
+`Request`에 대해 더 알아보려면 Starlette의 Requests 문서를 확인하세요.
+
+///
+
+`GzipRequest.get_route_handler`가 반환하는 함수가 다르게 하는 유일한 것은 `Request`를 `GzipRequest`로 변환하는 것입니다.
+
+이렇게 하면, 우리의 `GzipRequest`가 *경로 처리*로 전달하기 전에(필요하다면) 데이터의 압축 해제를 담당하게 됩니다.
+
+그 이후의 모든 처리 로직은 동일합니다.
+
+하지만 `GzipRequest.body`에서 변경을 했기 때문에, 필요할 때 **FastAPI**가 로드하는 시점에 요청 바디는 자동으로 압축 해제됩니다.
+
+## 예외 핸들러에서 요청 바디 접근하기 { #accessing-the-request-body-in-an-exception-handler }
+
+/// tip | 팁
+
+같은 문제를 해결하려면 `RequestValidationError`에 대한 커스텀 핸들러에서 `body`를 사용하는 편이 아마 훨씬 더 쉽습니다([오류 처리하기](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+하지만 이 예시도 여전히 유효하며, 내부 컴포넌트와 상호작용하는 방법을 보여줍니다.
+
+///
+
+같은 접근 방식을 사용해 예외 핸들러에서 요청 바디에 접근할 수도 있습니다.
+
+필요한 것은 `try`/`except` 블록 안에서 요청을 처리하는 것뿐입니다:
+
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *}
+
+예외가 발생하더라도 `Request` 인스턴스는 여전히 스코프 안에 남아 있으므로, 오류를 처리할 때 요청 바디를 읽고 활용할 수 있습니다:
+
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *}
+
+## 라우터에서의 커스텀 `APIRoute` 클래스 { #custom-apiroute-class-in-a-router }
+
+`APIRouter`의 `route_class` 파라미터를 설정할 수도 있습니다:
+
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[26] *}
+
+이 예시에서는 `router` 아래의 *경로 처리*들이 커스텀 `TimedRoute` 클래스를 사용하며, 응답을 생성하는 데 걸린 시간을 담은 추가 `X-Response-Time` 헤더가 응답에 포함됩니다:
+
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *}
diff --git a/docs/ko/docs/how-to/extending-openapi.md b/docs/ko/docs/how-to/extending-openapi.md
new file mode 100644
index 000000000..d04d6c23e
--- /dev/null
+++ b/docs/ko/docs/how-to/extending-openapi.md
@@ -0,0 +1,80 @@
+# OpenAPI 확장하기 { #extending-openapi }
+
+생성된 OpenAPI 스키마를 수정해야 하는 경우가 있습니다.
+
+이 섹션에서 그 방법을 살펴보겠습니다.
+
+## 일반적인 과정 { #the-normal-process }
+
+일반적인(기본) 과정은 다음과 같습니다.
+
+`FastAPI` 애플리케이션(인스턴스)에는 OpenAPI 스키마를 반환해야 하는 `.openapi()` 메서드가 있습니다.
+
+애플리케이션 객체를 생성하는 과정에서 `/openapi.json`(또는 `openapi_url`에 설정한 경로)용 *경로 처리*가 등록됩니다.
+
+이 경로 처리는 애플리케이션의 `.openapi()` 메서드 결과를 JSON 응답으로 반환할 뿐입니다.
+
+기본적으로 `.openapi()` 메서드는 프로퍼티 `.openapi_schema`에 내용이 있는지 확인하고, 있으면 그 내용을 반환합니다.
+
+없으면 `fastapi.openapi.utils.get_openapi`에 있는 유틸리티 함수를 사용해 생성합니다.
+
+그리고 `get_openapi()` 함수는 다음을 파라미터로 받습니다:
+
+* `title`: 문서에 표시되는 OpenAPI 제목.
+* `version`: API 버전. 예: `2.5.0`.
+* `openapi_version`: 사용되는 OpenAPI 스펙 버전. 기본값은 최신인 `3.1.0`.
+* `summary`: API에 대한 짧은 요약.
+* `description`: API 설명. markdown을 포함할 수 있으며 문서에 표시됩니다.
+* `routes`: 라우트 목록. 각각 등록된 *경로 처리*입니다. `app.routes`에서 가져옵니다.
+
+/// info | 정보
+
+`summary` 파라미터는 OpenAPI 3.1.0 이상에서 사용할 수 있으며, FastAPI 0.99.0 이상에서 지원됩니다.
+
+///
+
+## 기본값 덮어쓰기 { #overriding-the-defaults }
+
+위 정보를 바탕으로, 동일한 유틸리티 함수를 사용해 OpenAPI 스키마를 생성하고 필요한 각 부분을 덮어쓸 수 있습니다.
+
+예를 들어, 커스텀 로고를 포함하기 위한 ReDoc의 OpenAPI 확장을 추가해 보겠습니다.
+
+### 일반적인 **FastAPI** { #normal-fastapi }
+
+먼저, 평소처럼 **FastAPI** 애플리케이션을 모두 작성합니다:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[1,4,7:9] *}
+
+### OpenAPI 스키마 생성하기 { #generate-the-openapi-schema }
+
+그다음 `custom_openapi()` 함수 안에서, 동일한 유틸리티 함수를 사용해 OpenAPI 스키마를 생성합니다:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[2,15:21] *}
+
+### OpenAPI 스키마 수정하기 { #modify-the-openapi-schema }
+
+이제 OpenAPI 스키마의 `info` "object"에 커스텀 `x-logo`를 추가하여 ReDoc 확장을 더할 수 있습니다:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[22:24] *}
+
+### OpenAPI 스키마 캐시하기 { #cache-the-openapi-schema }
+
+생성한 스키마를 저장하기 위한 "cache"로 `.openapi_schema` 프로퍼티를 사용할 수 있습니다.
+
+이렇게 하면 사용자가 API 문서를 열 때마다 애플리케이션이 스키마를 매번 생성하지 않아도 됩니다.
+
+스키마는 한 번만 생성되고, 이후 요청에서는 같은 캐시된 스키마가 사용됩니다.
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[13:14,25:26] *}
+
+### 메서드 오버라이드하기 { #override-the-method }
+
+이제 `.openapi()` 메서드를 새 함수로 교체할 수 있습니다.
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[29] *}
+
+### 확인하기 { #check-it }
+
+http://127.0.0.1:8000/redoc로 이동하면 커스텀 로고(이 예시에서는 **FastAPI** 로고)를 사용하는 것을 확인할 수 있습니다:
+
+
diff --git a/docs/ko/docs/how-to/general.md b/docs/ko/docs/how-to/general.md
new file mode 100644
index 000000000..a18dc68a2
--- /dev/null
+++ b/docs/ko/docs/how-to/general.md
@@ -0,0 +1,39 @@
+# 일반 - 사용 방법 - 레시피 { #general-how-to-recipes }
+
+일반적이거나 자주 나오는 질문에 대해, 문서의 다른 위치로 안내하는 몇 가지 포인터를 소개합니다.
+
+## 데이터 필터링 - 보안 { #filter-data-security }
+
+반환하면 안 되는 데이터를 과도하게 반환하지 않도록 하려면, [튜토리얼 - 응답 모델 - 반환 타입](../tutorial/response-model.md){.internal-link target=_blank} 문서를 읽어보세요.
+
+## 문서화 태그 - OpenAPI { #documentation-tags-openapi }
+
+*경로 처리*에 태그를 추가하고, 문서 UI에서 이를 그룹화하려면 [튜토리얼 - 경로 처리 구성 - 태그](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank} 문서를 읽어보세요.
+
+## 문서화 요약 및 설명 - OpenAPI { #documentation-summary-and-description-openapi }
+
+*경로 처리*에 요약과 설명을 추가하고, 문서 UI에 표시하려면 [튜토리얼 - 경로 처리 구성 - 요약 및 설명](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank} 문서를 읽어보세요.
+
+## 문서화 응답 설명 - OpenAPI { #documentation-response-description-openapi }
+
+문서 UI에 표시되는 응답의 설명을 정의하려면 [튜토리얼 - 경로 처리 구성 - 응답 설명](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank} 문서를 읽어보세요.
+
+## 문서화 *경로 처리* 지원 중단하기 - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
+
+*경로 처리*를 지원 중단(deprecate)으로 표시하고, 문서 UI에 보여주려면 [튜토리얼 - 경로 처리 구성 - 지원 중단](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank} 문서를 읽어보세요.
+
+## 어떤 데이터든 JSON 호환으로 변환하기 { #convert-any-data-to-json-compatible }
+
+어떤 데이터든 JSON 호환 형식으로 변환하려면 [튜토리얼 - JSON 호환 인코더](../tutorial/encoder.md){.internal-link target=_blank} 문서를 읽어보세요.
+
+## OpenAPI 메타데이터 - 문서 { #openapi-metadata-docs }
+
+라이선스, 버전, 연락처 등의 정보를 포함해 OpenAPI 스키마에 메타데이터를 추가하려면 [튜토리얼 - 메타데이터와 문서 URL](../tutorial/metadata.md){.internal-link target=_blank} 문서를 읽어보세요.
+
+## OpenAPI 사용자 정의 URL { #openapi-custom-url }
+
+OpenAPI URL을 커스터마이즈(또는 제거)하려면 [튜토리얼 - 메타데이터와 문서 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank} 문서를 읽어보세요.
+
+## OpenAPI 문서 URL { #openapi-docs-urls }
+
+자동으로 생성되는 문서 사용자 인터페이스에서 사용하는 URL을 업데이트하려면 [튜토리얼 - 메타데이터와 문서 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank} 문서를 읽어보세요.
diff --git a/docs/ko/docs/how-to/graphql.md b/docs/ko/docs/how-to/graphql.md
new file mode 100644
index 000000000..3cc467eb7
--- /dev/null
+++ b/docs/ko/docs/how-to/graphql.md
@@ -0,0 +1,60 @@
+# GraphQL { #graphql }
+
+**FastAPI**는 **ASGI** 표준을 기반으로 하므로, ASGI와도 호환되는 어떤 **GraphQL** 라이브러리든 매우 쉽게 통합할 수 있습니다.
+
+같은 애플리케이션에서 일반 FastAPI **경로 처리**와 GraphQL을 함께 조합할 수 있습니다.
+
+/// tip | 팁
+
+**GraphQL**은 몇 가지 매우 특정한 사용 사례를 해결합니다.
+
+일반적인 **web API**와 비교했을 때 **장점**과 **단점**이 있습니다.
+
+여러분의 사용 사례에서 **이점**이 **단점**을 상쇄하는지 꼭 평가해 보세요. 🤓
+
+///
+
+## GraphQL 라이브러리 { #graphql-libraries }
+
+다음은 **ASGI** 지원이 있는 **GraphQL** 라이브러리들입니다. **FastAPI**와 함께 사용할 수 있습니다:
+
+* Strawberry 🍓
+ * FastAPI용 문서 제공
+* Ariadne
+ * FastAPI용 문서 제공
+* Tartiflette
+ * ASGI 통합을 제공하기 위해 Tartiflette ASGI 사용
+* Graphene
+ * starlette-graphene3 사용
+
+## Strawberry로 GraphQL 사용하기 { #graphql-with-strawberry }
+
+**GraphQL**로 작업해야 하거나 작업하고 싶다면, **Strawberry**를 **권장**합니다. **FastAPI**의 설계와 가장 가깝고, 모든 것이 **type annotations**에 기반해 있기 때문입니다.
+
+사용 사례에 따라 다른 라이브러리를 선호할 수도 있지만, 제게 묻는다면 아마 **Strawberry**를 먼저 시도해 보라고 제안할 것입니다.
+
+다음은 Strawberry를 FastAPI와 통합하는 방법에 대한 간단한 미리보기입니다:
+
+{* ../../docs_src/graphql_/tutorial001_py39.py hl[3,22,25] *}
+
+Strawberry 문서에서 Strawberry에 대해 더 알아볼 수 있습니다.
+
+또한 FastAPI에서 Strawberry 사용에 대한 문서도 확인해 보세요.
+
+## Starlette의 예전 `GraphQLApp` { #older-graphqlapp-from-starlette }
+
+이전 버전의 Starlette에는 Graphene과 통합하기 위한 `GraphQLApp` 클래스가 포함되어 있었습니다.
+
+이것은 Starlette에서 deprecated 되었지만, 이를 사용하던 코드가 있다면 같은 사용 사례를 다루고 **거의 동일한 인터페이스**를 가진 starlette-graphene3로 쉽게 **마이그레이션**할 수 있습니다.
+
+/// tip | 팁
+
+GraphQL이 필요하다면, 커스텀 클래스와 타입 대신 type annotations에 기반한 Strawberry를 여전히 확인해 보시길 권장합니다.
+
+///
+
+## 더 알아보기 { #learn-more }
+
+공식 GraphQL 문서에서 **GraphQL**에 대해 더 알아볼 수 있습니다.
+
+또한 위에서 설명한 각 라이브러리에 대해서도 해당 링크에서 더 자세히 읽어볼 수 있습니다.
diff --git a/docs/ko/docs/how-to/index.md b/docs/ko/docs/how-to/index.md
new file mode 100644
index 000000000..9321c488b
--- /dev/null
+++ b/docs/ko/docs/how-to/index.md
@@ -0,0 +1,13 @@
+# How To - 레시피 { #how-to-recipes }
+
+여기에서는 **여러 주제**에 대한 다양한 레시피(“how to” 가이드)를 볼 수 있습니다.
+
+대부분의 아이디어는 어느 정도 **서로 독립적**이며, 대부분의 경우 **여러분의 프로젝트**에 직접 적용되는 경우에만 학습하면 됩니다.
+
+프로젝트에 흥미롭고 유용해 보이는 것이 있다면 확인해 보세요. 그렇지 않다면 아마 건너뛰어도 됩니다.
+
+/// tip | 팁
+
+**FastAPI를 구조적으로 학습**하고 싶다면(권장), 대신 [튜토리얼 - 사용자 가이드](../tutorial/index.md){.internal-link target=_blank}를 장별로 읽어보세요.
+
+///
diff --git a/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
new file mode 100644
index 000000000..6e528ecaf
--- /dev/null
+++ b/docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
@@ -0,0 +1,135 @@
+# Pydantic v1에서 Pydantic v2로 마이그레이션하기 { #migrate-from-pydantic-v1-to-pydantic-v2 }
+
+오래된 FastAPI 앱이 있다면 Pydantic 버전 1을 사용하고 있을 수 있습니다.
+
+FastAPI 0.100.0 버전은 Pydantic v1 또는 v2 중 하나를 지원했습니다. 설치되어 있는 쪽을 사용했습니다.
+
+FastAPI 0.119.0 버전에서는 v2로의 마이그레이션을 쉽게 하기 위해, Pydantic v2 내부에서 Pydantic v1을(`pydantic.v1`로) 부분적으로 지원하기 시작했습니다.
+
+FastAPI 0.126.0 버전에서는 Pydantic v1 지원을 중단했지만, `pydantic.v1`은 잠시 동안 계속 지원했습니다.
+
+/// warning | 경고
+
+Pydantic 팀은 **Python 3.14**부터 최신 Python 버전에서 Pydantic v1 지원을 중단했습니다.
+
+여기에는 `pydantic.v1`도 포함되며, Python 3.14 이상에서는 더 이상 지원되지 않습니다.
+
+Python의 최신 기능을 사용하려면 Pydantic v2를 사용하고 있는지 확인해야 합니다.
+
+///
+
+Pydantic v1을 사용하는 오래된 FastAPI 앱이 있다면, 여기서는 이를 Pydantic v2로 마이그레이션하는 방법과 점진적 마이그레이션을 돕는 **FastAPI 0.119.0의 기능**을 소개하겠습니다.
+
+## 공식 가이드 { #official-guide }
+
+Pydantic에는 v1에서 v2로의 공식 Migration Guide가 있습니다.
+
+여기에는 무엇이 바뀌었는지, 검증이 이제 어떻게 더 정확하고 엄격해졌는지, 가능한 주의사항 등도 포함되어 있습니다.
+
+변경된 내용을 더 잘 이해하기 위해 읽어보면 좋습니다.
+
+## 테스트 { #tests }
+
+앱에 대한 [tests](../tutorial/testing.md){.internal-link target=_blank}가 있는지 확인하고, 지속적 통합(CI)에서 테스트를 실행하세요.
+
+이렇게 하면 업그레이드를 진행하면서도 모든 것이 기대한 대로 계속 동작하는지 확인할 수 있습니다.
+
+## `bump-pydantic` { #bump-pydantic }
+
+많은 경우, 커스터마이징 없이 일반적인 Pydantic 모델을 사용하고 있다면 Pydantic v1에서 Pydantic v2로의 마이그레이션 과정 대부분을 자동화할 수 있습니다.
+
+같은 Pydantic 팀이 제공하는 `bump-pydantic`를 사용할 수 있습니다.
+
+이 도구는 변경해야 하는 코드의 대부분을 자동으로 바꾸는 데 도움을 줍니다.
+
+그 다음 테스트를 실행해서 모든 것이 동작하는지 확인하면 됩니다. 잘 된다면 끝입니다. 😎
+
+## v2 안의 Pydantic v1 { #pydantic-v1-in-v2 }
+
+Pydantic v2는 Pydantic v1의 모든 것을 서브모듈 `pydantic.v1`로 포함합니다. 하지만 이는 Python 3.13보다 높은 버전에서는 더 이상 지원되지 않습니다.
+
+즉, Pydantic v2의 최신 버전을 설치한 뒤, 이 서브모듈에서 예전 Pydantic v1 구성 요소를 import하여 예전 Pydantic v1을 설치한 것처럼 사용할 수 있습니다.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *}
+
+### v2 안의 Pydantic v1에 대한 FastAPI 지원 { #fastapi-support-for-pydantic-v1-in-v2 }
+
+FastAPI 0.119.0부터는 v2로의 마이그레이션을 쉽게 하기 위해, Pydantic v2 내부의 Pydantic v1에 대해서도 부분적인 지원이 있습니다.
+
+따라서 Pydantic을 최신 v2로 업그레이드하고, import를 `pydantic.v1` 서브모듈을 사용하도록 바꾸면, 많은 경우 그대로 동작합니다.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *}
+
+/// warning | 경고
+
+Pydantic 팀이 Python 3.14부터 최신 Python 버전에서 Pydantic v1을 더 이상 지원하지 않으므로, `pydantic.v1`을 사용하는 것 역시 Python 3.14 이상에서는 지원되지 않는다는 점을 염두에 두세요.
+
+///
+
+### 같은 앱에서 Pydantic v1과 v2 함께 사용하기 { #pydantic-v1-and-v2-on-the-same-app }
+
+Pydantic에서는 Pydantic v2 모델의 필드를 Pydantic v1 모델로 정의하거나 그 반대로 하는 것을 **지원하지 않습니다**.
+
+```mermaid
+graph TB
+ subgraph "❌ Not Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+...하지만 같은 앱에서 Pydantic v1과 v2를 사용하되, 모델을 분리해서 둘 수는 있습니다.
+
+```mermaid
+graph TB
+ subgraph "✅ Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+어떤 경우에는 FastAPI 앱의 같은 **경로 처리**에서 Pydantic v1과 v2 모델을 함께 사용하는 것도 가능합니다:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *}
+
+위 예제에서 입력 모델은 Pydantic v1 모델이고, 출력 모델(`response_model=ItemV2`로 정의됨)은 Pydantic v2 모델입니다.
+
+### Pydantic v1 파라미터 { #pydantic-v1-parameters }
+
+Pydantic v1 모델과 함께 `Body`, `Query`, `Form` 등 파라미터용 FastAPI 전용 도구 일부를 사용해야 한다면, Pydantic v2로의 마이그레이션을 마칠 때까지 `fastapi.temp_pydantic_v1_params`에서 import할 수 있습니다:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *}
+
+### 단계적으로 마이그레이션하기 { #migrate-in-steps }
+
+/// tip | 팁
+
+먼저 `bump-pydantic`로 시도해 보세요. 테스트가 통과하고 잘 동작한다면, 한 번의 명령으로 끝입니다. ✨
+
+///
+
+`bump-pydantic`가 여러분의 사용 사례에 맞지 않는다면, 같은 앱에서 Pydantic v1과 v2 모델을 모두 지원하는 기능을 이용해 Pydantic v2로 점진적으로 마이그레이션할 수 있습니다.
+
+먼저 Pydantic을 최신 v2로 업그레이드하고, 모든 모델의 import를 `pydantic.v1`을 사용하도록 바꿀 수 있습니다.
+
+그 다음 Pydantic v1에서 v2로 모델을 그룹 단위로, 점진적인 단계로 마이그레이션을 시작하면 됩니다. 🚶
diff --git a/docs/ko/docs/how-to/separate-openapi-schemas.md b/docs/ko/docs/how-to/separate-openapi-schemas.md
new file mode 100644
index 000000000..055429c26
--- /dev/null
+++ b/docs/ko/docs/how-to/separate-openapi-schemas.md
@@ -0,0 +1,102 @@
+# 입력과 출력에 대해 OpenAPI 스키마를 분리할지 여부 { #separate-openapi-schemas-for-input-and-output-or-not }
+
+**Pydantic v2**가 릴리스된 이후, 생성되는 OpenAPI는 이전보다 조금 더 정확하고 **올바르게** 만들어집니다. 😎
+
+실제로 어떤 경우에는, 같은 Pydantic 모델에 대해 OpenAPI 안에 **두 개의 JSON Schema**가 생기기도 합니다. **기본값(default value)**이 있는지 여부에 따라, 입력용과 출력용으로 나뉩니다.
+
+이것이 어떻게 동작하는지, 그리고 필요하다면 어떻게 변경할 수 있는지 살펴보겠습니다.
+
+## 입력과 출력을 위한 Pydantic 모델 { #pydantic-models-for-input-and-output }
+
+예를 들어, 다음처럼 기본값이 있는 Pydantic 모델이 있다고 해보겠습니다:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
+
+### 입력용 모델 { #model-for-input }
+
+이 모델을 다음처럼 입력으로 사용하면:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}
+
+...`description` 필드는 **필수가 아닙니다**. `None`이라는 기본값이 있기 때문입니다.
+
+### 문서에서의 입력 모델 { #input-model-in-docs }
+
+문서에서 `description` 필드에 **빨간 별표**가 없고, 필수로 표시되지 않는 것을 확인할 수 있습니다:
+
+
+
+
+
+
+
-
+
FastAPI 프레임워크, 고성능, 간편한 학습, 빠른 코드 작성, 준비된 프로덕션
@@ -27,7 +27,7 @@
---
-**문서**: https://fastapi.tiangolo.com
+**문서**: https://fastapi.tiangolo.com
**소스 코드**: https://github.com/fastapi/fastapi
@@ -37,36 +37,41 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
주요 특징으로:
-* **빠름**: (Starlette과 Pydantic 덕분에) **NodeJS** 및 **Go**와 대등할 정도로 매우 높은 성능. [사용 가능한 가장 빠른 파이썬 프레임워크 중 하나](#_11).
-
+* **빠름**: (Starlette과 Pydantic 덕분에) **NodeJS** 및 **Go**와 대등할 정도로 매우 높은 성능. [사용 가능한 가장 빠른 파이썬 프레임워크 중 하나](#performance).
* **빠른 코드 작성**: 약 200%에서 300%까지 기능 개발 속도 증가. *
* **적은 버그**: 사람(개발자)에 의한 에러 약 40% 감소. *
* **직관적**: 훌륭한 편집기 지원. 모든 곳에서 자동완성. 적은 디버깅 시간.
* **쉬움**: 쉽게 사용하고 배우도록 설계. 적은 문서 읽기 시간.
* **짧음**: 코드 중복 최소화. 각 매개변수 선언의 여러 기능. 적은 버그.
* **견고함**: 준비된 프로덕션 용 코드를 얻으십시오. 자동 대화형 문서와 함께.
-* **표준 기반**: API에 대한 (완전히 호환되는) 개방형 표준 기반: OpenAPI (이전에 Swagger로 알려졌던) 및 JSON 스키마.
+* **표준 기반**: API에 대한 (완전히 호환되는) 개방형 표준 기반: OpenAPI (이전에 Swagger로 알려졌던) 및 JSON Schema.
* 내부 개발팀의 프로덕션 애플리케이션을 빌드한 테스트에 근거한 측정
-## 골드 스폰서
+## 스폰서 { #sponsors }
-{% if sponsors %}
+### 키스톤 스폰서 { #keystone-sponsor }
+
+{% for sponsor in sponsors.keystone -%}
+
+{% endfor -%}
+
+### 골드 및 실버 스폰서 { #gold-and-silver-sponsors }
+
{% for sponsor in sponsors.gold -%}
{% endfor -%}
{%- for sponsor in sponsors.silver -%}
{% endfor %}
-{% endif %}
-다른 스폰서
+다른 스폰서
-## 의견들
+## 의견들 { #opinions }
"_[...] 저는 요즘 **FastAPI**를 많이 사용하고 있습니다. [...] 사실 우리 팀의 **마이크로소프트 ML 서비스** 전부를 바꿀 계획입니다. 그중 일부는 핵심 **Windows**와 몇몇의 **Office** 제품들이 통합되고 있습니다._"
@@ -94,7 +99,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
"_솔직히, 당신이 만든 것은 매우 견고하고 세련되어 보입니다. 여러 면에서 **Hug**가 이렇게 되었으면 합니다 - 그걸 만든 누군가를 보는 것은 많은 영감을 줍니다._"
-
+
-* 웹 부분을 위한 Starlette.
-* 데이터 부분을 위한 Pydantic.
+## **Typer**, CLI를 위한 FastAPI { #typer-the-fastapi-of-clis }
-## 설치
+
-async def 사용하기...uvicorn main:app --reload 명령에 관하여...fastapi dev main.py 명령에 관하여...HTTPX - `TestClient`를 사용하려면 필요.
-* jinja2 - 기본 템플릿 설정을 사용하려면 필요.
-* python-multipart - `request.form()`과 함께 "parsing"의 지원을 원하면 필요.
-* itsdangerous - `SessionMiddleware` 지원을 위해 필요.
-* pyyaml - Starlette의 `SchemaGenerator` 지원을 위해 필요 (FastAPI와 쓸때는 필요 없을 것입니다).
-* graphene - `GraphQLApp` 지원을 위해 필요.
+* httpx - `TestClient`를 사용하려면 필요.
+* jinja2 - 기본 템플릿 설정을 사용하려면 필요.
+* python-multipart - `request.form()`과 함께 form "parsing" 지원을 원하면 필요.
-FastAPI / Starlette이 사용하는:
+FastAPI가 사용하는:
-* uvicorn - 애플리케이션을 로드하고 제공하는 서버.
-* orjson - `ORJSONResponse`을 사용하려면 필요.
-* ujson - `UJSONResponse`를 사용하려면 필요.
+* uvicorn - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다.
+* `fastapi-cli[standard]` - `fastapi` 명령을 제공하기 위한 것입니다.
+ * 여기에는 FastAPI 애플리케이션을 FastAPI Cloud에 배포할 수 있게 해주는 `fastapi-cloud-cli`가 포함됩니다.
+
+### `standard` 의존성 없이 { #without-standard-dependencies }
+
+`standard` 선택적 의존성을 포함하고 싶지 않다면, `pip install "fastapi[standard]"` 대신 `pip install fastapi`로 설치할 수 있습니다.
-`pip install fastapi[all]`를 통해 이 모두를 설치 할 수 있습니다.
+### `fastapi-cloud-cli` 없이 { #without-fastapi-cloud-cli }
+
+표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
+
+### 추가 선택적 의존성 { #additional-optional-dependencies }
+
+추가로 설치하고 싶을 수 있는 의존성도 있습니다.
+
+추가 선택적 Pydantic 의존성:
+
+* pydantic-settings - 설정 관리를 위한 것입니다.
+* pydantic-extra-types - Pydantic에서 사용할 추가 타입을 위한 것입니다.
+
+추가 선택적 FastAPI 의존성:
+
+* orjson - `ORJSONResponse`를 사용하려면 필요.
+* ujson - `UJSONResponse`를 사용하려면 필요.
-## 라이센스
+## 라이센스 { #license }
이 프로젝트는 MIT 라이센스 조약에 따라 라이센스가 부여됩니다.
diff --git a/docs/ko/docs/learn/index.md b/docs/ko/docs/learn/index.md
index 7ac3a99b6..0b4d14ff4 100644
--- a/docs/ko/docs/learn/index.md
+++ b/docs/ko/docs/learn/index.md
@@ -1,5 +1,5 @@
-# 배우기
+# 배우기 { #learn }
-여기 **FastAPI**를 배우기 위한 입문 자료와 자습서가 있습니다.
+여기 **FastAPI**를 배우기 위한 입문 섹션과 자습서가 있습니다.
-여러분은 FastAPI를 배우기 위해 **책**, **강의**, **공식 자료** 그리고 추천받은 방법을 고려할 수 있습니다. 😎
+여러분은 이것을 FastAPI를 배우기 위한 **책**, **강의**, **공식**이자 권장되는 방법으로 생각할 수 있습니다. 😎
diff --git a/docs/ko/docs/openapi-webhooks.md b/docs/ko/docs/openapi-webhooks.md
deleted file mode 100644
index 96339aa96..000000000
--- a/docs/ko/docs/openapi-webhooks.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# 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
index dd11fca70..73ea67d3e 100644
--- a/docs/ko/docs/project-generation.md
+++ b/docs/ko/docs/project-generation.md
@@ -1,4 +1,4 @@
-# Full Stack FastAPI 템플릿
+# Full Stack FastAPI 템플릿 { #full-stack-fastapi-template }
템플릿은 일반적으로 특정 설정과 함께 제공되지만, 유연하고 커스터마이징이 가능하게 디자인 되었습니다. 이 특성들은 여러분이 프로젝트의 요구사항에 맞춰 수정, 적용을 할 수 있게 해주고, 템플릿이 완벽한 시작점이 되게 해줍니다. 🏁
@@ -6,23 +6,23 @@
GitHub 저장소: Full Stack FastAPI 템플릿
-## Full Stack FastAPI 템플릿 - 기술 스택과 기능들
+## Full Stack FastAPI 템플릿 - 기술 스택과 기능들 { #full-stack-fastapi-template-technology-stack-and-features }
-- ⚡ [**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): 프론트엔드 컴포넌트.
+- ⚡ Python 백엔드 API를 위한 [**FastAPI**](https://fastapi.tiangolo.com/ko).
+ - 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM).
+ - 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://docs.pydantic.dev).
+ - 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org).
+- 🚀 프론트엔드를 위한 [React](https://react.dev).
+ - 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용.
+ - 🎨 프론트엔드 컴포넌트를 위한 [Tailwind CSS](https://tailwindcss.com) 및 [shadcn/ui](https://ui.shadcn.com).
- 🤖 자동으로 생성된 프론트엔드 클라이언트.
- - 🧪 E2E 테스트를 위한 [Playwright](https://playwright.dev).
+ - 🧪 End-to-End 테스트를 위한 [Playwright](https://playwright.dev).
- 🦇 다크 모드 지원.
-- 🐋 [Docker Compose](https://www.docker.com): 개발 환경과 프로덕션(운영).
+- 🐋 개발 환경과 프로덕션(운영)을 위한 [Docker Compose](https://www.docker.com).
- 🔒 기본으로 지원되는 안전한 비밀번호 해싱.
-- 🔑 JWT 토큰 인증.
+- 🔑 JWT (JSON Web Token) 인증.
- 📫 이메일 기반 비밀번호 복구.
-- ✅ [Pytest]를 이용한 테스트(https://pytest.org).
-- 📞 [Traefik](https://traefik.io): 리버스 프록시 / 로드 밸런서.
+- ✅ [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 18d4b341e..dc264df80 100644
--- a/docs/ko/docs/python-types.md
+++ b/docs/ko/docs/python-types.md
@@ -1,313 +1,466 @@
-# 파이썬 타입 소개
+# 파이썬 타입 소개 { #python-types-intro }
-파이썬은 선택적으로 "타입 힌트(type hints)"를 지원합니다.
+파이썬은 선택적으로 "타입 힌트(type hints)"(“type annotations”라고도 함)를 지원합니다.
-이러한 **타입 힌트**들은 변수의 타입을 선언할 수 있게 해주는 특수한 구문입니다.
+이러한 **"타입 힌트"** 또는 애너테이션은 변수의 타입을 선언할 수 있게 해주는 특수한 구문입니다.
-변수의 타입을 지정하면 에디터와 툴이 더 많은 도움을 줄 수 있게 됩니다.
+변수의 타입을 선언하면 에디터와 도구가 더 나은 지원을 제공할 수 있습니다.
-이 문서는 파이썬 타입 힌트에 대한 **빠른 자습서 / 내용환기** 수준의 문서입니다. 여기서는 **FastAPI**를 쓰기 위한 최소한의 내용만을 다룹니다.
+이 문서는 파이썬 타입 힌트에 대한 **빠른 자습서 / 내용 환기**입니다. **FastAPI**와 함께 사용하기 위해 필요한 최소한만 다룹니다... 실제로는 아주 조금만 있으면 됩니다.
-**FastAPI**는 타입 힌트에 기반을 두고 있으며, 이는 많은 장점과 이익이 있습니다.
+**FastAPI**는 모두 이러한 타입 힌트에 기반을 두고 있으며, 이는 많은 장점과 이점을 제공합니다.
-비록 **FastAPI**를 쓰지 않는다고 하더라도, 조금이라도 알아두면 도움이 될 것입니다.
+하지만 **FastAPI**를 전혀 사용하지 않더라도, 타입 힌트를 조금만 배워도 도움이 됩니다.
/// note | 참고
-파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요.
+파이썬에 능숙하고 타입 힌트에 대해 이미 모두 알고 있다면, 다음 장으로 건너뛰세요.
///
-## 동기 부여
+## 동기 부여 { #motivation }
-간단한 예제부터 시작해봅시다:
+간단한 예제로 시작해봅시다:
-{* ../../docs_src/python_types/tutorial001.py *}
+{* ../../docs_src/python_types/tutorial001_py39.py *}
-
-이 프로그램을 실행한 결과값:
+이 프로그램을 호출하면 다음이 출력됩니다:
```
John Doe
```
-함수는 아래와 같이 실행됩니다:
+이 함수는 다음을 수행합니다:
* `first_name`과 `last_name`를 받습니다.
-* `title()`로 각 첫 문자를 대문자로 변환시킵니다.
-* 두 단어를 중간에 공백을 두고 연결합니다.
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+* `title()`로 각각의 첫 글자를 대문자로 변환합니다.
+* 가운데에 공백을 두고 연결합니다.
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
-### 코드 수정
+### 수정하기 { #edit-it }
-이건 매우 간단한 프로그램입니다.
+매우 간단한 프로그램입니다.
-그런데 처음부터 작성한다고 생각을 해봅시다.
+하지만 이제, 이것을 처음부터 작성한다고 상상해봅시다.
-여러분은 매개변수를 준비했고, 함수를 정의하기 시작했을 겁니다.
+어느 시점엔 함수를 정의하기 시작했고, 매개변수도 준비해두었을 겁니다...
-이때 "첫 글자를 대문자로 바꾸는 함수"를 호출해야 합니다.
+그런데 "첫 글자를 대문자로 변환하는 그 메서드"를 호출해야 합니다.
-`upper`였나? 아니면 `uppercase`? `first_uppercase`? `capitalize`?
+`upper`였나요? `uppercase`였나요? `first_uppercase`? `capitalize`?
-그때 개발자들의 오랜 친구, 에디터 자동완성을 시도해봅니다.
+그 다음, 개발자들의 오랜 친구인 에디터 자동완성을 시도합니다.
-당신은 `first_name`를 입력한 뒤 점(`.`)을 입력하고 자동완성을 켜기 위해서 `Ctrl+Space`를 눌렀습니다.
+함수의 첫 번째 매개변수인 `first_name`을 입력하고, 점(`.`)을 찍은 다음, 완성을 트리거하기 위해 `Ctrl+Space`를 누릅니다.
-하지만 슬프게도 아무런 도움이 되지 않습니다:
+하지만, 슬프게도 쓸만한 게 아무것도 없습니다:
-### 타입 추가하기
+### 타입 추가하기 { #add-types }
이전 버전에서 한 줄만 수정해봅시다.
-저희는 이 함수의 매개변수 부분:
+함수의 매개변수인 정확히 이 부분을:
```Python
first_name, last_name
```
-을 아래와 같이 바꿀 겁니다:
+에서:
```Python
first_name: str, last_name: str
```
-이게 다입니다.
+로 바꾸겠습니다.
-이게 "타입 힌트"입니다:
+이게 다입니다.
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+이것들이 "타입 힌트"입니다:
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
-타입힌트는 다음과 같이 기본 값을 선언하는 것과는 다릅니다:
+이것은 다음처럼 기본값을 선언하는 것과는 다릅니다:
```Python
first_name="john", last_name="doe"
```
-이는 다른 것입니다.
+다른 것입니다.
-등호(`=`) 대신 콜론(`:`)을 쓰고 있습니다.
+등호(`=`)가 아니라 콜론(`:`)을 사용합니다.
-일반적으로 타입힌트를 추가한다고 해서 특별하게 어떤 일이 일어나지도 않습니다.
+그리고 보통 타입 힌트를 추가해도, 타입 힌트 없이 일어나는 일과 비교해 특별히 달라지는 것은 없습니다.
-그렇지만 이제, 다시 함수를 만드는 도중이라고 생각해봅시다. 다만 이번엔 타입 힌트가 있습니다.
+하지만 이제, 타입 힌트를 포함해 그 함수를 다시 만드는 중이라고 상상해봅시다.
-같은 상황에서 `Ctrl+Space`로 자동완성을 작동시키면,
+같은 지점에서 `Ctrl+Space`로 자동완성을 트리거하면 다음이 보입니다:
-아래와 같이 "그렇지!"하는 옵션이 나올때까지 스크롤을 내려서 볼 수 있습니다:
+그러면 스크롤하며 옵션을 보다가, "기억나는" 것을 찾을 수 있습니다:
-## 더 큰 동기부여
-
-아래 함수를 보면, 이미 타입 힌트가 적용되어 있는 걸 볼 수 있습니다:
+## 더 큰 동기부여 { #more-motivation }
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+이 함수를 확인해보세요. 이미 타입 힌트가 있습니다:
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
-편집기가 변수의 타입을 알고 있기 때문에, 자동완성 뿐 아니라 에러도 확인할 수 있습니다:
+에디터가 변수의 타입을 알고 있기 때문에, 자동완성만 되는 게 아니라 오류 검사도 할 수 있습니다:
-이제 고쳐야하는 걸 알기 때문에, `age`를 `str(age)`과 같이 문자열로 바꾸게 됩니다:
-
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+이제 고쳐야 한다는 것을 알고, `age`를 `str(age)`로 문자열로 바꿉니다:
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
-## 타입 선언
+## 타입 선언 { #declaring-types }
-방금 함수의 매개변수로써 타입 힌트를 선언하는 주요 장소를 보았습니다.
+방금 타입 힌트를 선언하는 주요 위치를 보았습니다. 함수 매개변수입니다.
-이 위치는 여러분이 **FastAPI**와 함께 이를 사용하는 주요 장소입니다.
+이것은 **FastAPI**와 함께 사용할 때도 주요 위치입니다.
-### Simple 타입
+### Simple 타입 { #simple-types }
`str`뿐 아니라 모든 파이썬 표준 타입을 선언할 수 있습니다.
-예를 들면:
+예를 들어 다음을 사용할 수 있습니다:
* `int`
* `float`
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
+### 타입 매개변수가 있는 Generic(제네릭) 타입 { #generic-types-with-type-parameters }
-### 타입 매개변수를 활용한 Generic(제네릭) 타입
+`dict`, `list`, `set`, `tuple`처럼 다른 값을 담을 수 있는 데이터 구조가 있습니다. 그리고 내부 값에도 각자의 타입이 있을 수 있습니다.
-`dict`, `list`, `set`, `tuple`과 같은 값을 저장할 수 있는 데이터 구조가 있고, 내부의 값은 각자의 타입을 가질 수도 있습니다.
+이렇게 내부 타입을 가지는 타입을 "**generic**" 타입이라고 부릅니다. 그리고 내부 타입까지 포함해 선언할 수도 있습니다.
-타입과 내부 타입을 선언하기 위해서는 파이썬 표준 모듈인 `typing`을 이용해야 합니다.
+이런 타입과 내부 타입을 선언하려면 표준 파이썬 모듈 `typing`을 사용할 수 있습니다. 이 모듈은 이러한 타입 힌트를 지원하기 위해 존재합니다.
-구체적으로는 아래 타입 힌트를 지원합니다.
+#### 더 최신 버전의 Python { #newer-versions-of-python }
-#### `List`
+`typing`을 사용하는 문법은 Python 3.6부터 최신 버전까지, Python 3.9, Python 3.10 등을 포함한 모든 버전과 **호환**됩니다.
-예를 들면, `str`의 `list`인 변수를 정의해봅시다.
+파이썬이 발전함에 따라 **더 최신 버전**에서는 이러한 타입 애너테이션 지원이 개선되며, 많은 경우 타입 애너테이션을 선언하기 위해 `typing` 모듈을 import해서 사용할 필요조차 없게 됩니다.
-`typing`에서 `List`(대문자 `L`)를 import 합니다.
+프로젝트에서 더 최신 버전의 파이썬을 선택할 수 있다면, 그 추가적인 단순함을 활용할 수 있습니다.
-{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+이 문서 전체에는 각 파이썬 버전과 호환되는 예제가 있습니다(차이가 있을 때).
+예를 들어 "**Python 3.6+**"는 Python 3.6 이상(3.7, 3.8, 3.9, 3.10 등 포함)과 호환된다는 뜻입니다. 그리고 "**Python 3.9+**"는 Python 3.9 이상(3.10 등 포함)과 호환된다는 뜻입니다.
-콜론(`:`) 문법을 이용하여 변수를 선언합니다.
+**최신 버전의 Python**을 사용할 수 있다면, 최신 버전용 예제를 사용하세요. 예를 들어 "**Python 3.10+**"처럼, 가장 **좋고 가장 단순한 문법**을 갖게 됩니다.
-타입으로는 `List`를 넣어줍니다.
+#### List { #list }
-이때 배열은 내부 타입을 포함하는 타입이기 때문에 대괄호 안에 넣어줍니다.
+예를 들어, `str`의 `list`인 변수를 정의해봅시다.
-{* ../../docs_src/python_types/tutorial006.py hl[4] *}
+같은 콜론(`:`) 문법으로 변수를 선언합니다.
+타입으로 `list`를 넣습니다.
-/// tip | 팁
+`list`는 내부 타입을 포함하는 타입이므로, 그 타입들을 대괄호 안에 넣습니다:
+
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
+
+/// info | 정보
-대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다.
+대괄호 안의 내부 타입은 "type parameters"라고 부릅니다.
-이번 예제에서는 `str`이 `List`에 들어간 타입 매개변수 입니다.
+이 경우 `str`이 `list`에 전달된 타입 매개변수입니다.
///
-이는 "`items`은 `list`인데, 배열에 들어있는 아이템 각각은 `str`이다"라는 뜻입니다.
+이는 "변수 `items`는 `list`이고, 이 `list`의 각 아이템은 `str`이다"라는 뜻입니다.
-이렇게 함으로써, 에디터는 배열에 들어있는 아이템을 처리할때도 도움을 줄 수 있게 됩니다:
+이렇게 하면, 에디터는 리스트의 아이템을 처리하는 동안에도 지원을 제공할 수 있습니다:
-타입이 없으면 이건 거의 불가능이나 다름 없습니다.
+타입이 없으면, 이는 거의 불가능합니다.
+
+변수 `item`이 리스트 `items`의 요소 중 하나라는 점에 주목하세요.
+
+그리고 에디터는 여전히 이것이 `str`임을 알고, 그에 대한 지원을 제공합니다.
+
+#### Tuple과 Set { #tuple-and-set }
+
+`tuple`과 `set`도 동일하게 선언할 수 있습니다:
+
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
+
+이는 다음을 의미합니다:
+
+* 변수 `items_t`는 3개의 아이템을 가진 `tuple`이며, `int`, 또 다른 `int`, 그리고 `str`입니다.
+* 변수 `items_s`는 `set`이며, 각 아이템의 타입은 `bytes`입니다.
+
+#### Dict { #dict }
+
+`dict`를 정의하려면, 쉼표로 구분된 2개의 타입 매개변수를 전달합니다.
+
+첫 번째 타입 매개변수는 `dict`의 키를 위한 것입니다.
+
+두 번째 타입 매개변수는 `dict`의 값을 위한 것입니다:
+
+{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *}
+
+이는 다음을 의미합니다:
-변수 `item`은 `items`의 개별 요소라는 사실을 알아두세요.
+* 변수 `prices`는 `dict`입니다:
+ * 이 `dict`의 키는 `str` 타입입니다(예: 각 아이템의 이름).
+ * 이 `dict`의 값은 `float` 타입입니다(예: 각 아이템의 가격).
-그리고 에디터는 계속 `str`라는 사실을 알고 도와줍니다.
+#### Union { #union }
-#### `Tuple`과 `Set`
+변수가 **여러 타입 중 어떤 것이든** 될 수 있다고 선언할 수 있습니다. 예를 들어 `int` 또는 `str`입니다.
-`tuple`과 `set`도 동일하게 선언할 수 있습니다.
+Python 3.6 이상(3.10 포함)에서는 `typing`의 `Union` 타입을 사용하고, 대괄호 안에 허용할 수 있는 타입들을 넣을 수 있습니다.
-{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+Python 3.10에는 가능한 타입들을 세로 막대(`|`)로 구분해 넣을 수 있는 **새 문법**도 있습니다.
+//// tab | Python 3.10+
-이 뜻은 아래와 같습니다:
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
+```
-* 변수 `items_t`는, 차례대로 `int`, `int`, `str`인 `tuple`이다.
-* 변수 `items_s`는, 각 아이템이 `bytes`인 `set`이다.
+////
-#### `Dict`
+두 경우 모두 이는 `item`이 `int` 또는 `str`일 수 있다는 뜻입니다.
-`dict`를 선언하려면 컴마로 구분된 2개의 파라미터가 필요합니다.
+#### `None`일 수도 있음 { #possibly-none }
-첫 번째 매개변수는 `dict`의 키(key)이고,
+값이 `str` 같은 타입일 수도 있지만, `None`일 수도 있다고 선언할 수 있습니다.
-두 번째 매개변수는 `dict`의 값(value)입니다.
+Python 3.6 이상(3.10 포함)에서는 `typing` 모듈에서 `Optional`을 import해서 사용하여 선언할 수 있습니다.
-{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+```Python hl_lines="1 4"
+{!../../docs_src/python_types/tutorial009_py39.py!}
+```
+
+그냥 `str` 대신 `Optional[str]`을 사용하면, 값이 항상 `str`이라고 가정하고 있지만 실제로는 `None`일 수도 있는 상황에서 에디터가 오류를 감지하도록 도와줍니다.
+`Optional[Something]`은 사실 `Union[Something, None]`의 축약이며, 서로 동등합니다.
-이 뜻은 아래와 같습니다:
+또한 이는 Python 3.10에서 `Something | None`을 사용할 수 있다는 의미이기도 합니다:
-* 변수 `prices`는 `dict`이다:
- * `dict`의 키(key)는 `str`타입이다. (각 아이템의 이름(name))
- * `dict`의 값(value)는 `float`타입이다. (각 아이템의 가격(price))
+//// tab | Python 3.10+
-#### `Optional`
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
-`str`과 같이 타입을 선언할 때 `Optional`을 쓸 수도 있는데, "선택적(Optional)"이기때문에 `None`도 될 수 있습니다:
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
-`Optional[str]`을 `str` 대신 쓰게 되면, 특정 값이 실제로는 `None`이 될 수도 있는데 항상 `str`이라고 가정하는 상황에서 에디터가 에러를 찾게 도와줄 수 있습니다.
+////
+
+//// tab | Python 3.9+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
+```
+
+////
+
+#### `Union` 또는 `Optional` 사용하기 { #using-union-or-optional }
+
+Python 3.10 미만 버전을 사용한다면, 아주 **주관적인** 관점에서의 팁입니다:
+
+* 🚨 `Optional[SomeType]` 사용을 피하세요
+* 대신 ✨ **`Union[SomeType, None]`을 사용하세요** ✨.
+
+둘은 동등하고 내부적으로는 같은 것이지만, `Optional`이라는 단어가 값이 선택 사항인 것처럼 보일 수 있기 때문에 `Optional` 대신 `Union`을 권장합니다. 실제 의미는 값이 선택 사항이라는 뜻이 아니라, "값이 `None`일 수 있다"는 뜻이기 때문입니다. 선택 사항이 아니고 여전히 필수인 경우에도요.
+
+`Union[SomeType, None]`이 의미를 더 명확하게 드러낸다고 생각합니다.
+
+이건 단지 단어와 이름의 문제입니다. 하지만 그런 단어들이 여러분과 팀원이 코드에 대해 생각하는 방식에 영향을 줄 수 있습니다.
+
+예로, 이 함수를 봅시다:
-#### Generic(제네릭) 타입
+{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *}
-이 타입은 대괄호 안에 매개변수를 가지며, 종류는:
+매개변수 `name`은 `Optional[str]`로 정의되어 있지만, **선택 사항이 아닙니다**. 매개변수 없이 함수를 호출할 수 없습니다:
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
+```Python
+say_hi() # Oh, no, this throws an error! 😱
+```
+
+기본값이 없기 때문에 `name` 매개변수는 **여전히 필수입니다**(*optional*이 아님). 그럼에도 `name`은 값으로 `None`을 허용합니다:
+
+```Python
+say_hi(name=None) # This works, None is valid 🎉
+```
+
+좋은 소식은 Python 3.10을 사용하면, 타입의 유니온을 정의하기 위해 간단히 `|`를 사용할 수 있어서 이런 걱정을 할 필요가 없다는 점입니다:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+그러면 `Optional`이나 `Union` 같은 이름에 대해 걱정할 필요도 없습니다. 😎
+
+#### Generic(제네릭) 타입 { #generic-types }
+
+대괄호 안에 타입 매개변수를 받는 이러한 타입들은 **Generic types** 또는 **Generics**라고 부릅니다. 예를 들면:
+
+//// tab | Python 3.10+
+
+대괄호와 내부 타입을 사용해, 동일한 내장 타입들을 제네릭으로 사용할 수 있습니다:
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+그리고 이전 파이썬 버전과 마찬가지로 `typing` 모듈의 다음도 사용할 수 있습니다:
+
+* `Union`
* `Optional`
-* ...등등
+* ...그 밖의 것들.
-위와 같은 타입은 **Generic(제네릭) 타입** 혹은 **Generics(제네릭스)**라고 불립니다.
+Python 3.10에서는 제네릭 `Union`과 `Optional`을 사용하는 대안으로, 타입 유니온을 선언하기 위해 세로 막대(`|`)를 사용할 수 있는데, 훨씬 더 좋고 단순합니다.
-### 타입으로서의 클래스
+////
-변수의 타입으로 클래스를 선언할 수도 있습니다.
+//// tab | Python 3.9+
+
+대괄호와 내부 타입을 사용해, 동일한 내장 타입들을 제네릭으로 사용할 수 있습니다:
-이름(name)을 가진 `Person` 클래스가 있다고 해봅시다.
+* `list`
+* `tuple`
+* `set`
+* `dict`
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+그리고 `typing` 모듈의 제네릭들:
+* `Union`
+* `Optional`
+* ...그 밖의 것들.
+
+////
+
+### 타입으로서의 클래스 { #classes-as-types }
+
+변수의 타입으로 클래스를 선언할 수도 있습니다.
-그렇게 하면 변수를 `Person`이라고 선언할 수 있게 됩니다.
+이름을 가진 `Person` 클래스가 있다고 해봅시다:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
+그러면 `Person` 타입의 변수를 선언할 수 있습니다:
-그리고 역시나 모든 에디터 도움을 받게 되겠죠.
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
+
+그리고 다시, 에디터의 모든 지원을 받을 수 있습니다:
-## Pydantic 모델
+이는 "`one_person`은 `Person` 클래스의 **인스턴스**"라는 뜻입니다.
+
+"`one_person`은 `Person`이라는 **클래스**다"라는 뜻이 아닙니다.
-Pydantic은 데이터 검증(Validation)을 위한 파이썬 라이브러리입니다.
+## Pydantic 모델 { #pydantic-models }
-당신은 속성들을 포함한 클래스 형태로 "모양(shape)"을 선언할 수 있습니다.
+Pydantic은 데이터 검증을 수행하는 파이썬 라이브러리입니다.
-그리고 각 속성은 타입을 가지고 있습니다.
+속성을 가진 클래스 형태로 데이터의 "모양(shape)"을 선언합니다.
-이 클래스를 활용하여서 값을 가지고 있는 인스턴스를 만들게 되면, 필요한 경우에는 적당한 타입으로 변환까지 시키기도 하여 데이터가 포함된 객체를 반환합니다.
+그리고 각 속성은 타입을 가집니다.
-그리고 결과 객체에 대해서는 에디터의 도움을 받을 수 있게 됩니다.
+그 다음 그 클래스의 인스턴스를 몇 가지 값으로 생성하면, 값들을 검증하고, (그런 경우라면) 적절한 타입으로 변환한 뒤, 모든 데이터를 가진 객체를 제공합니다.
-Pydantic 공식 문서 예시:
+그리고 그 결과 객체에 대해 에디터의 모든 지원을 받을 수 있습니다.
-{* ../../docs_src/python_types/tutorial011.py *}
+Pydantic 공식 문서의 예시:
+{* ../../docs_src/python_types/tutorial011_py310.py *}
/// info | 정보
-Pydantic<에 대해 더 배우고 싶다면 공식 문서를 참고하세요.
+Pydantic에 대해 더 알아보려면 문서를 확인하세요.
///
-**FastAPI**는 모두 Pydantic을 기반으로 되어 있습니다.
+**FastAPI**는 모두 Pydantic에 기반을 두고 있습니다.
+
+이 모든 것은 [자습서 - 사용자 안내서](tutorial/index.md){.internal-link target=_blank}에서 실제로 많이 보게 될 것입니다.
+
+/// tip | 팁
+
+Pydantic은 기본값 없이 `Optional` 또는 `Union[Something, None]`을 사용할 때 특별한 동작이 있습니다. 이에 대해서는 Pydantic 문서의 Required Optional fields에서 더 읽을 수 있습니다.
+
+///
+
+## 메타데이터 애너테이션이 있는 타입 힌트 { #type-hints-with-metadata-annotations }
+
+파이썬에는 `Annotated`를 사용해 이러한 타입 힌트에 **추가 메타데이터**를 넣을 수 있는 기능도 있습니다.
+
+Python 3.9부터 `Annotated`는 표준 라이브러리의 일부이므로, `typing`에서 import할 수 있습니다.
-이 모든 것이 실제로 어떻게 사용되는지에 대해서는 [자습서 - 사용자 안내서](tutorial/index.md){.internal-link target=_blank} 에서 더 많이 확인하실 수 있습니다.
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
+
+파이썬 자체는 이 `Annotated`로 아무것도 하지 않습니다. 그리고 에디터와 다른 도구들에게는 타입이 여전히 `str`입니다.
+
+하지만 `Annotated`의 이 공간을 사용해, 애플리케이션이 어떻게 동작하길 원하는지에 대한 추가 메타데이터를 **FastAPI**에 제공할 수 있습니다.
+
+기억해야 할 중요한 점은 `Annotated`에 전달하는 **첫 번째 *타입 매개변수***가 **실제 타입**이라는 것입니다. 나머지는 다른 도구를 위한 메타데이터일 뿐입니다.
+
+지금은 `Annotated`가 존재하며, 표준 파이썬이라는 것만 알면 됩니다. 😎
+
+나중에 이것이 얼마나 **강력**할 수 있는지 보게 될 것입니다.
+
+/// tip | 팁
+
+이것이 **표준 파이썬**이라는 사실은, 에디터에서 가능한 **최고의 개발자 경험**을 계속 얻을 수 있다는 뜻이기도 합니다. 사용하는 도구로 코드를 분석하고 리팩터링하는 등에서도요. ✨
+
+또한 코드가 많은 다른 파이썬 도구 및 라이브러리와 매우 호환된다는 뜻이기도 합니다. 🚀
+
+///
-## **FastAPI**에서의 타입 힌트
+## **FastAPI**에서의 타입 힌트 { #type-hints-in-fastapi }
-**FastAPI**는 여러 부분에서 타입 힌트의 장점을 취하고 있습니다.
+**FastAPI**는 이러한 타입 힌트를 활용해 여러 가지를 합니다.
-**FastAPI**에서 타입 힌트와 함께 매개변수를 선언하면 장점은:
+**FastAPI**에서는 타입 힌트로 매개변수를 선언하면 다음을 얻습니다:
* **에디터 도움**.
* **타입 확인**.
-...그리고 **FastAPI**는 같은 정의를 아래에도 적용합니다:
+...그리고 **FastAPI**는 같은 선언을 다음에도 사용합니다:
-* **요구사항 정의**: 요청 경로 매개변수, 쿼리 매개변수, 헤더, 바디, 의존성 등.
-* **데이터 변환**: 요청에서 요구한 타입으로.
-* **데이터 검증**: 각 요청마다:
- * 데이터가 유효하지 않은 경우에는 **자동으로 에러**를 발생합니다.
-* OpenAPI를 활용한 **API 문서화**:
- * 자동으로 상호작용하는 유저 인터페이스에 쓰이게 됩니다.
+* **요구사항 정의**: 요청 경로 매개변수, 쿼리 매개변수, 헤더, 바디, 의존성 등에서.
+* **데이터 변환**: 요청에서 필요한 타입으로.
+* **데이터 검증**: 각 요청에서:
+ * 데이터가 유효하지 않을 때 클라이언트에 반환되는 **자동 오류**를 생성합니다.
+* OpenAPI를 사용해 API를 **문서화**:
+ * 자동 상호작용 문서 UI에서 사용됩니다.
-위 내용이 다소 추상적일 수도 있지만, 걱정마세요. [자습서 - 사용자 안내서](tutorial/index.md){.internal-link target=_blank}에서 전부 확인 가능합니다.
+이 모든 것이 다소 추상적으로 들릴 수도 있습니다. 걱정하지 마세요. [자습서 - 사용자 안내서](tutorial/index.md){.internal-link target=_blank}에서 실제로 확인하게 될 것입니다.
-가장 중요한 건, 표준 파이썬 타입을 한 곳에서(클래스를 더하거나, 데코레이터 사용하는 대신) 사용함으로써 **FastAPI**가 당신을 위해 많은 일을 해준다는 사실이죠.
+가장 중요한 점은 표준 파이썬 타입을 한 곳에서 사용함으로써(더 많은 클래스, 데코레이터 등을 추가하는 대신) **FastAPI**가 여러분을 위해 많은 일을 해준다는 사실입니다.
/// info | 정보
-만약 모든 자습서를 다 보았음에도 타입에 대해서 더 보고자 방문한 경우에는 `mypy`에서 제공하는 "cheat sheet"이 좋은 자료가 될 겁니다.
+자습서를 모두 끝내고 타입에 대해 더 알아보기 위해 다시 돌아왔다면, 좋은 자료로 `mypy`의 "cheat sheet"가 있습니다.
///
diff --git a/docs/ko/docs/resources/index.md b/docs/ko/docs/resources/index.md
index e804dd4d5..477b93a58 100644
--- a/docs/ko/docs/resources/index.md
+++ b/docs/ko/docs/resources/index.md
@@ -1,3 +1,3 @@
-# 리소스
+# 리소스 { #resources }
-추가 리소스, 외부 링크, 기사 등. ✈️
+추가 리소스, 외부 링크 등. ✈️
diff --git a/docs/ko/docs/security/index.md b/docs/ko/docs/security/index.md
deleted file mode 100644
index 5a6c733f0..000000000
--- a/docs/ko/docs/security/index.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# 고급 보안
-
-## 추가 기능
-
-[자습서 - 사용자 가이드: 보안](../../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 a2c4abbd9..9e868f2fa 100644
--- a/docs/ko/docs/tutorial/background-tasks.md
+++ b/docs/ko/docs/tutorial/background-tasks.md
@@ -1,84 +1,86 @@
-# 백그라운드 작업
+# 백그라운드 작업 { #background-tasks }
-FastAPI에서는 응답을 반환한 후에 실행할 백그라운드 작업을 정의할 수 있습니다.
+FastAPI에서는 응답을 반환한 *후에* 실행할 백그라운드 작업을 정의할 수 있습니다.
-백그라운드 작업은 클라이언트가 응답을 받기 위해 작업이 완료될 때까지 기다릴 필요가 없기 때문에 요청 후에 발생해야하는 작업에 매우 유용합니다.
+백그라운드 작업은 요청 후에 발생해야 하지만, 클라이언트가 응답을 받기 전에 작업이 완료될 때까지 기다릴 필요가 없는 작업에 유용합니다.
-이러한 작업에는 다음이 포함됩니다.
+예를 들면 다음과 같습니다.
-* 작업을 수행한 후 전송되는 이메일 알림
- * 이메일 서버에 연결하고 이메일을 전송하는 것은 (몇 초 정도) "느린" 경향이 있으므로, 응답은 즉시 반환하고 이메일 알림은 백그라운드에서 전송하는 게 가능합니다.
+* 작업을 수행한 후 전송되는 이메일 알림:
+ * 이메일 서버에 연결하고 이메일을 전송하는 것은 (몇 초 정도) "느린" 경향이 있으므로, 응답은 즉시 반환하고 이메일 알림은 백그라운드에서 전송할 수 있습니다.
* 데이터 처리:
- * 예를 들어 처리에 오랜 시간이 걸리는 데이터를 받았을 때 "Accepted" (HTTP 202)을 반환하고, 백그라운드에서 데이터를 처리할 수 있습니다.
+ * 예를 들어 처리에 오랜 시간이 걸리는 프로세스를 거쳐야 하는 파일을 받았다면, "Accepted"(HTTP 202) 응답을 반환하고 백그라운드에서 파일을 처리할 수 있습니다.
-## `백그라운드 작업` 사용
+## `BackgroundTasks` 사용 { #using-backgroundtasks }
-먼저 아래와 같이 `BackgroundTasks`를 임포트하고, `BackgroundTasks`를 _경로 작동 함수_ 에서 매개변수로 가져오고 정의합니다.
+먼저 `BackgroundTasks`를 임포트하고, `BackgroundTasks` 타입 선언으로 *경로 처리 함수*에 매개변수를 정의합니다:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
-**FastAPI** 는 `BackgroundTasks` 개체를 생성하고, 매개 변수로 전달합니다.
+**FastAPI**가 `BackgroundTasks` 타입의 객체를 생성하고 해당 매개변수로 전달합니다.
-## 작업 함수 생성
+## 작업 함수 생성 { #create-a-task-function }
-백그라운드 작업으로 실행할 함수를 정의합니다.
+백그라운드 작업으로 실행할 함수를 생성합니다.
-이것은 단순히 매개변수를 받을 수 있는 표준 함수일 뿐입니다.
+이는 매개변수를 받을 수 있는 표준 함수일 뿐입니다.
-**FastAPI**는 이것이 `async def` 함수이든, 일반 `def` 함수이든 내부적으로 이를 올바르게 처리합니다.
+`async def` 함수일 수도, 일반 `def` 함수일 수도 있으며, **FastAPI**가 이를 올바르게 처리하는 방법을 알고 있습니다.
-이 경우, 아래 작업은 파일에 쓰는 함수입니다. (이메일 보내기 시물레이션)
+이 경우 작업 함수는 파일에 쓰기를 수행합니다(이메일 전송을 시뮬레이션).
-그리고 이 작업은 `async`와 `await`를 사용하지 않으므로 일반 `def` 함수로 선언합니다.
+그리고 쓰기 작업은 `async`와 `await`를 사용하지 않으므로, 일반 `def`로 함수를 정의합니다:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
-## 백그라운드 작업 추가
+## 백그라운드 작업 추가 { #add-the-background-task }
-_경로 작동 함수_ 내에서 작업 함수를 `.add_task()` 함수 통해 _백그라운드 작업_ 개체에 전달합니다.
+*경로 처리 함수* 내부에서 `.add_task()` 메서드로 작업 함수를 *백그라운드 작업* 객체에 전달합니다:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
-`.add_task()` 함수는 다음과 같은 인자를 받습니다 :
+`.add_task()`는 다음 인자를 받습니다:
-- 백그라운드에서 실행되는 작업 함수 (`write_notification`).
-- 작업 함수에 순서대로 전달되어야 하는 일련의 인자 (`email`).
-- 작업 함수에 전달되어야하는 모든 키워드 인자 (`message="some notification"`).
+* 백그라운드에서 실행될 작업 함수(`write_notification`).
+* 작업 함수에 순서대로 전달되어야 하는 인자 시퀀스(`email`).
+* 작업 함수에 전달되어야 하는 키워드 인자(`message="some notification"`).
-## 의존성 주입
+## 의존성 주입 { #dependency-injection }
-`BackgroundTasks`를 의존성 주입 시스템과 함께 사용하면 _경로 작동 함수_, 종속성, 하위 종속성 등 여러 수준에서 BackgroundTasks 유형의 매개변수를 선언할 수 있습니다.
+`BackgroundTasks`는 의존성 주입 시스템에서도 동작하며, *경로 처리 함수*, 의존성(dependable), 하위 의존성 등 여러 수준에서 `BackgroundTasks` 타입의 매개변수를 선언할 수 있습니다.
-**FastAPI**는 각 경우에 수행할 작업과 동일한 개체를 내부적으로 재사용하기에, 모든 백그라운드 작업이 함께 병합되고 나중에 백그라운드에서 실행됩니다.
+**FastAPI**는 각 경우에 무엇을 해야 하는지와 동일한 객체를 어떻게 재사용해야 하는지를 알고 있으므로, 모든 백그라운드 작업이 함께 병합되어 이후 백그라운드에서 실행됩니다:
-{* ../../docs_src/background_tasks/tutorial002.py hl[13,15,22,25] *}
-이 예제에서는 응답이 반환된 후에 `log.txt` 파일에 메시지가 기록됩니다.
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
-요청에 쿼리가 있는 경우 백그라운드 작업의 로그에 기록됩니다.
-그리고 _경로 작동 함수_ 에서 생성된 또 다른 백그라운드 작업은 경로 매개 변수를 활용하여 사용하여 메시지를 작성합니다.
+이 예제에서는 응답이 전송된 *후에* 메시지가 `log.txt` 파일에 작성됩니다.
-## 기술적 세부사항
+요청에 쿼리가 있었다면, 백그라운드 작업으로 로그에 작성됩니다.
-`BackgroundTasks` 클래스는 `starlette.background`에서 직접 가져옵니다.
+그 다음 *경로 처리 함수*에서 생성된 또 다른 백그라운드 작업이 `email` 경로 매개변수를 사용해 메시지를 작성합니다.
-`BackgroundTasks` 클래스는 FastAPI에서 직접 임포트하거나 포함하기 때문에 실수로 `BackgroundTask` (끝에 `s`가 없음)을 임포트하더라도 starlette.background에서 `BackgroundTask`를 가져오는 것을 방지할 수 있습니다.
+## 기술적 세부사항 { #technical-details }
-(`BackgroundTask`가 아닌) `BackgroundTasks`를 사용하면, _경로 작동 함수_ 매개변수로 사용할 수 있게 되고 나머지는 **FastAPI**가 대신 처리하도록 할 수 있습니다. 이것은 `Request` 객체를 직접 사용하는 것과 같은 방식입니다.
+`BackgroundTasks` 클래스는 `starlette.background`에서 직접 가져옵니다.
-FastAPI에서 `BackgroundTask`를 단독으로 사용하는 것은 여전히 가능합니다. 하지만 객체를 코드에서 생성하고, 이 객체를 포함하는 Starlette `Response`를 반환해야 합니다.
+FastAPI에 직접 임포트/포함되어 있으므로 `fastapi`에서 임포트할 수 있고, 실수로 `starlette.background`에서 대안인 `BackgroundTask`(끝에 `s`가 없음)를 임포트하는 것을 피할 수 있습니다.
-`Starlette의 공식 문서`에서 백그라운드 작업에 대한 자세한 내용을 확인할 수 있습니다.
+`BackgroundTask`가 아닌 `BackgroundTasks`만 사용하면, 이를 *경로 처리 함수*의 매개변수로 사용할 수 있고 나머지는 **FastAPI**가 `Request` 객체를 직접 사용할 때처럼 대신 처리해 줍니다.
-## 경고
+FastAPI에서 `BackgroundTask`만 단독으로 사용하는 것도 가능하지만, 코드에서 객체를 생성하고 이를 포함하는 Starlette `Response`를 반환해야 합니다.
-만약 무거운 백그라운드 작업을 수행해야하고 동일한 프로세스에서 실행할 필요가 없는 경우 (예: 메모리, 변수 등을 공유할 필요가 없음) `Celery`와 같은 큰 도구를 사용하면 도움이 될 수 있습니다.
+더 자세한 내용은 Starlette의 Background Tasks 공식 문서에서 확인할 수 있습니다.
-RabbitMQ 또는 Redis와 같은 메시지/작업 큐 시스템 보다 복잡한 구성이 필요한 경향이 있지만, 여러 작업 프로세스를 특히 여러 서버의 백그라운드에서 실행할 수 있습니다.
+## 주의사항 { #caveat }
-그러나 동일한 FastAPI 앱에서 변수 및 개체에 접근해야햐는 작은 백그라운드 수행이 필요한 경우 (예 : 알림 이메일 보내기) 간단하게 `BackgroundTasks`를 사용해보세요.
+무거운 백그라운드 계산을 수행해야 하고, 반드시 동일한 프로세스에서 실행할 필요가 없다면(예: 메모리, 변수 등을 공유할 필요가 없음) Celery 같은 더 큰 도구를 사용하는 것이 도움이 될 수 있습니다.
-## 요약
+이들은 RabbitMQ나 Redis 같은 메시지/작업 큐 관리자 등 더 복잡한 설정을 필요로 하는 경향이 있지만, 여러 프로세스에서, 특히 여러 서버에서 백그라운드 작업을 실행할 수 있습니다.
-백그라운드 작업을 추가하기 위해 _경로 작동 함수_ 에 매개변수로 `BackgroundTasks`를 가져오고 사용합니다.
+하지만 동일한 **FastAPI** 앱의 변수와 객체에 접근해야 하거나(또는 이메일 알림 전송처럼) 작은 백그라운드 작업을 수행해야 한다면, `BackgroundTasks`를 간단히 사용하면 됩니다.
+
+## 요약 { #recap }
+
+*경로 처리 함수*와 의존성에서 매개변수로 `BackgroundTasks`를 임포트해 사용하여 백그라운드 작업을 추가합니다.
diff --git a/docs/ko/docs/tutorial/bigger-applications.md b/docs/ko/docs/tutorial/bigger-applications.md
new file mode 100644
index 000000000..cfc3900d4
--- /dev/null
+++ b/docs/ko/docs/tutorial/bigger-applications.md
@@ -0,0 +1,504 @@
+# 더 큰 애플리케이션 - 여러 파일 { #bigger-applications-multiple-files }
+
+애플리케이션이나 웹 API를 만들 때, 모든 것을 하나의 파일에 담을 수 있는 경우는 드뭅니다.
+
+**FastAPI**는 모든 유연성을 유지하면서도 애플리케이션을 구조화할 수 있게 해주는 편리한 도구를 제공합니다.
+
+/// info | 정보
+
+Flask를 사용해 보셨다면, 이는 Flask의 Blueprints에 해당하는 개념입니다.
+
+///
+
+## 예시 파일 구조 { #an-example-file-structure }
+
+다음과 같은 파일 구조가 있다고 해봅시다:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+│ ├── dependencies.py
+│ └── routers
+│ │ ├── __init__.py
+│ │ ├── items.py
+│ │ └── users.py
+│ └── internal
+│ ├── __init__.py
+│ └── admin.py
+```
+
+/// tip | 팁
+
+`__init__.py` 파일이 여러 개 있습니다: 각 디렉터리 또는 하위 디렉터리에 하나씩 있습니다.
+
+이 파일들이 한 파일의 코드를 다른 파일로 import할 수 있게 해줍니다.
+
+예를 들어 `app/main.py`에는 다음과 같은 줄이 있을 수 있습니다:
+
+```
+from app.routers import items
+```
+
+///
+
+* `app` 디렉터리에는 모든 것이 들어 있습니다. 그리고 비어 있는 파일 `app/__init__.py`가 있어 "Python package"(“Python modules”의 모음)인 `app`이 됩니다.
+* `app/main.py` 파일이 있습니다. Python package(`__init__.py` 파일이 있는 디렉터리) 안에 있으므로, 이 package의 "module"입니다: `app.main`.
+* `app/dependencies.py` 파일도 있습니다. `app/main.py`와 마찬가지로 "module"입니다: `app.dependencies`.
+* `app/routers/` 하위 디렉터리가 있고, 여기에 또 `__init__.py` 파일이 있으므로 "Python subpackage"입니다: `app.routers`.
+* `app/routers/items.py` 파일은 `app/routers/` package 안에 있으므로, submodule입니다: `app.routers.items`.
+* `app/routers/users.py`도 동일하게 또 다른 submodule입니다: `app.routers.users`.
+* `app/internal/` 하위 디렉터리도 있고 여기에 `__init__.py`가 있으므로 또 다른 "Python subpackage"입니다: `app.internal`.
+* 그리고 `app/internal/admin.py` 파일은 또 다른 submodule입니다: `app.internal.admin`.
+
+
+
+같은 파일 구조에 주석을 추가하면 다음과 같습니다:
+
+```bash
+.
+├── app # "app" is a Python package
+│ ├── __init__.py # this file makes "app" a "Python package"
+│ ├── main.py # "main" module, e.g. import app.main
+│ ├── dependencies.py # "dependencies" module, e.g. import app.dependencies
+│ └── routers # "routers" is a "Python subpackage"
+│ │ ├── __init__.py # makes "routers" a "Python subpackage"
+│ │ ├── items.py # "items" submodule, e.g. import app.routers.items
+│ │ └── users.py # "users" submodule, e.g. import app.routers.users
+│ └── internal # "internal" is a "Python subpackage"
+│ ├── __init__.py # makes "internal" a "Python subpackage"
+│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
+```
+
+## `APIRouter` { #apirouter }
+
+사용자만 처리하는 전용 파일이 `/app/routers/users.py`의 submodule이라고 해봅시다.
+
+코드를 정리하기 위해 사용자와 관련된 *path operations*를 나머지 코드와 분리해 두고 싶을 것입니다.
+
+하지만 이것은 여전히 같은 **FastAPI** 애플리케이션/웹 API의 일부입니다(같은 "Python Package"의 일부입니다).
+
+`APIRouter`를 사용해 해당 모듈의 *path operations*를 만들 수 있습니다.
+
+### `APIRouter` import하기 { #import-apirouter }
+
+`FastAPI` 클래스와 동일한 방식으로 import하고 "instance"를 생성합니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
+
+### `APIRouter`로 *path operations* 만들기 { #path-operations-with-apirouter }
+
+그 다음 이를 사용해 *path operations*를 선언합니다.
+
+`FastAPI` 클래스를 사용할 때와 동일한 방식으로 사용합니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
+
+`APIRouter`는 "미니 `FastAPI`" 클래스라고 생각할 수 있습니다.
+
+동일한 옵션들이 모두 지원됩니다.
+
+동일한 `parameters`, `responses`, `dependencies`, `tags` 등등.
+
+/// tip | 팁
+
+이 예시에서는 변수 이름이 `router`이지만, 원하는 이름으로 지어도 됩니다.
+
+///
+
+이제 이 `APIRouter`를 메인 `FastAPI` 앱에 포함(include)할 것이지만, 먼저 dependencies와 다른 `APIRouter` 하나를 확인해 보겠습니다.
+
+## Dependencies { #dependencies }
+
+애플리케이션의 여러 위치에서 사용되는 dependencies가 일부 필요하다는 것을 알 수 있습니다.
+
+그래서 이를 별도의 `dependencies` 모듈(`app/dependencies.py`)에 둡니다.
+
+이제 간단한 dependency를 사용해 커스텀 `X-Token` 헤더를 읽어 보겠습니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
+
+/// tip | 팁
+
+이 예시를 단순화하기 위해 임의로 만든 헤더를 사용하고 있습니다.
+
+하지만 실제 상황에서는 통합된 [Security 유틸리티](security/index.md){.internal-link target=_blank}를 사용하는 것이 더 좋은 결과를 얻을 수 있습니다.
+
+///
+
+## `APIRouter`가 있는 또 다른 모듈 { #another-module-with-apirouter }
+
+애플리케이션의 "items"를 처리하는 전용 endpoint들도 `app/routers/items.py` 모듈에 있다고 해봅시다.
+
+여기에는 다음에 대한 *path operations*가 있습니다:
+
+* `/items/`
+* `/items/{item_id}`
+
+구조는 `app/routers/users.py`와 완전히 동일합니다.
+
+하지만 우리는 조금 더 똑똑하게, 코드를 약간 단순화하고 싶습니다.
+
+이 모듈의 모든 *path operations*에는 다음이 동일하게 적용됩니다:
+
+* 경로 `prefix`: `/items`.
+* `tags`: (태그 하나: `items`).
+* 추가 `responses`.
+* `dependencies`: 모두 우리가 만든 `X-Token` dependency가 필요합니다.
+
+따라서 각 *path operation*마다 매번 모두 추가하는 대신, `APIRouter`에 한 번에 추가할 수 있습니다.
+
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
+
+각 *path operation*의 경로는 다음처럼 `/`로 시작해야 하므로:
+
+```Python hl_lines="1"
+@router.get("/{item_id}")
+async def read_item(item_id: str):
+ ...
+```
+
+...prefix에는 마지막 `/`가 포함되면 안 됩니다.
+
+따라서 이 경우 prefix는 `/items`입니다.
+
+또한 이 router에 포함된 모든 *path operations*에 적용될 `tags` 목록과 추가 `responses`도 넣을 수 있습니다.
+
+그리고 router의 모든 *path operations*에 추가될 `dependencies` 목록도 추가할 수 있으며, 해당 경로들로 들어오는 각 요청마다 실행/해결됩니다.
+
+/// tip | 팁
+
+[*path operation decorator의 dependencies*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}와 마찬가지로, *path operation function*에 어떤 값도 전달되지 않습니다.
+
+///
+
+최종적으로 item 경로는 다음과 같습니다:
+
+* `/items/`
+* `/items/{item_id}`
+
+...의도한 그대로입니다.
+
+* 단일 문자열 `"items"`를 포함하는 태그 목록으로 표시됩니다.
+ * 이 "tags"는 자동 대화형 문서 시스템(OpenAPI 사용)에 특히 유용합니다.
+* 모두 미리 정의된 `responses`를 포함합니다.
+* 이 모든 *path operations*는 실행되기 전에 `dependencies` 목록이 평가/실행됩니다.
+ * 특정 *path operation*에 dependencies를 추가로 선언하면 **그것들도 실행됩니다**.
+ * router dependencies가 먼저 실행되고, 그 다음에 [decorator의 `dependencies`](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, 그리고 일반 파라미터 dependencies가 실행됩니다.
+ * [`scopes`가 있는 `Security` dependencies](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}도 추가할 수 있습니다.
+
+/// tip | 팁
+
+`APIRouter`에 `dependencies`를 두는 것은 예를 들어 전체 *path operations* 그룹에 인증을 요구할 때 사용할 수 있습니다. 각 경로 처리에 개별적으로 dependencies를 추가하지 않아도 됩니다.
+
+///
+
+/// check | 확인
+
+`prefix`, `tags`, `responses`, `dependencies` 파라미터는 (다른 많은 경우와 마찬가지로) 코드 중복을 피하도록 도와주는 **FastAPI**의 기능입니다.
+
+///
+
+### dependencies import하기 { #import-the-dependencies }
+
+이 코드는 모듈 `app.routers.items`, 파일 `app/routers/items.py`에 있습니다.
+
+그리고 dependency 함수는 모듈 `app.dependencies`, 파일 `app/dependencies.py`에서 가져와야 합니다.
+
+그래서 dependencies에 대해 `..`를 사용하는 상대 import를 사용합니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
+
+#### 상대 import가 동작하는 방식 { #how-relative-imports-work }
+
+/// tip | 팁
+
+import가 동작하는 방식을 완벽히 알고 있다면, 아래 다음 섹션으로 넘어가세요.
+
+///
+
+다음과 같이 점 하나 `.`를 쓰면:
+
+```Python
+from .dependencies import get_token_header
+```
+
+의미는 다음과 같습니다:
+
+* 이 모듈(파일 `app/routers/items.py`)이 속한 같은 package(디렉터리 `app/routers/`)에서 시작해서...
+* `dependencies` 모듈(가상의 파일 `app/routers/dependencies.py`)을 찾고...
+* 그 안에서 함수 `get_token_header`를 import합니다.
+
+하지만 그 파일은 존재하지 않습니다. dependencies는 `app/dependencies.py` 파일에 있습니다.
+
+우리 앱/파일 구조를 다시 떠올려 보세요:
+
+
+
+---
+
+다음처럼 점 두 개 `..`를 쓰면:
+
+```Python
+from ..dependencies import get_token_header
+```
+
+의미는 다음과 같습니다:
+
+* 이 모듈(파일 `app/routers/items.py`)이 속한 같은 package(디렉터리 `app/routers/`)에서 시작해서...
+* 상위 package(디렉터리 `app/`)로 올라가고...
+* 그 안에서 `dependencies` 모듈(파일 `app/dependencies.py`)을 찾고...
+* 그 안에서 함수 `get_token_header`를 import합니다.
+
+이렇게 하면 제대로 동작합니다! 🎉
+
+---
+
+같은 방식으로 점 세 개 `...`를 사용했다면:
+
+```Python
+from ...dependencies import get_token_header
+```
+
+의미는 다음과 같습니다:
+
+* 이 모듈(파일 `app/routers/items.py`)이 속한 같은 package(디렉터리 `app/routers/`)에서 시작해서...
+* 상위 package(디렉터리 `app/`)로 올라가고...
+* 그 package의 상위로 또 올라가는데(상위 package가 없습니다, `app`이 최상위입니다 😱)...
+* 그 안에서 `dependencies` 모듈(파일 `app/dependencies.py`)을 찾고...
+* 그 안에서 함수 `get_token_header`를 import합니다.
+
+이는 `app/` 위쪽의 어떤 package(자신의 `__init__.py` 파일 등을 가진)에 대한 참조가 됩니다. 하지만 우리는 그런 것이 없습니다. 그래서 이 예시에서는 에러가 발생합니다. 🚨
+
+이제 어떻게 동작하는지 알았으니, 앱이 얼마나 복잡하든 상대 import를 사용할 수 있습니다. 🤓
+
+### 커스텀 `tags`, `responses`, `dependencies` 추가하기 { #add-some-custom-tags-responses-and-dependencies }
+
+`APIRouter`에 이미 prefix `/items`와 `tags=["items"]`를 추가했기 때문에 각 *path operation*에 이를 추가하지 않습니다.
+
+하지만 특정 *path operation*에만 적용될 _추가_ `tags`를 더할 수도 있고, 그 *path operation* 전용의 추가 `responses`도 넣을 수 있습니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
+
+/// tip | 팁
+
+이 마지막 경로 처리는 `["items", "custom"]` 태그 조합을 갖게 됩니다.
+
+그리고 문서에는 `404`용 응답과 `403`용 응답, 두 가지 모두가 표시됩니다.
+
+///
+
+## 메인 `FastAPI` { #the-main-fastapi }
+
+이제 `app/main.py` 모듈을 봅시다.
+
+여기에서 `FastAPI` 클래스를 import하고 사용합니다.
+
+이 파일은 모든 것을 하나로 엮는 애플리케이션의 메인 파일이 될 것입니다.
+
+그리고 대부분의 로직이 각자의 특정 모듈로 분리되어 있으므로, 메인 파일은 꽤 단순해집니다.
+
+### `FastAPI` import하기 { #import-fastapi }
+
+평소처럼 `FastAPI` 클래스를 import하고 생성합니다.
+
+또한 각 `APIRouter`의 dependencies와 결합될 [global dependencies](dependencies/global-dependencies.md){.internal-link target=_blank}도 선언할 수 있습니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
+
+### `APIRouter` import하기 { #import-the-apirouter }
+
+이제 `APIRouter`가 있는 다른 submodule들을 import합니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *}
+
+`app/routers/users.py`와 `app/routers/items.py` 파일은 같은 Python package `app`에 속한 submodule들이므로, 점 하나 `.`를 사용해 "상대 import"로 가져올 수 있습니다.
+
+### import가 동작하는 방식 { #how-the-importing-works }
+
+다음 구문은:
+
+```Python
+from .routers import items, users
+```
+
+의미는 다음과 같습니다:
+
+* 이 모듈(파일 `app/main.py`)이 속한 같은 package(디렉터리 `app/`)에서 시작해서...
+* subpackage `routers`(디렉터리 `app/routers/`)를 찾고...
+* 그 안에서 submodule `items`(파일 `app/routers/items.py`)와 `users`(파일 `app/routers/users.py`)를 import합니다...
+
+`items` 모듈에는 `router` 변수(`items.router`)가 있습니다. 이는 `app/routers/items.py` 파일에서 만든 것과 동일하며 `APIRouter` 객체입니다.
+
+그리고 `users` 모듈도 같은 방식입니다.
+
+다음처럼 import할 수도 있습니다:
+
+```Python
+from app.routers import items, users
+```
+
+/// info | 정보
+
+첫 번째 버전은 "상대 import"입니다:
+
+```Python
+from .routers import items, users
+```
+
+두 번째 버전은 "절대 import"입니다:
+
+```Python
+from app.routers import items, users
+```
+
+Python Packages와 Modules에 대해 더 알아보려면 Modules에 대한 Python 공식 문서를 읽어보세요.
+
+///
+
+### 이름 충돌 피하기 { #avoid-name-collisions }
+
+submodule `items`를 직접 import하고, 그 안의 `router` 변수만 import하지는 않습니다.
+
+이는 submodule `users`에도 `router`라는 이름의 변수가 있기 때문입니다.
+
+만약 다음처럼 순서대로 import했다면:
+
+```Python
+from .routers.items import router
+from .routers.users import router
+```
+
+`users`의 `router`가 `items`의 `router`를 덮어써서 동시에 사용할 수 없게 됩니다.
+
+따라서 같은 파일에서 둘 다 사용할 수 있도록 submodule들을 직접 import합니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *}
+
+### `users`와 `items`용 `APIRouter` 포함하기 { #include-the-apirouters-for-users-and-items }
+
+이제 submodule `users`와 `items`의 `router`를 포함해 봅시다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[10:11] title["app/main.py"] *}
+
+/// info | 정보
+
+`users.router`는 `app/routers/users.py` 파일 안의 `APIRouter`를 담고 있습니다.
+
+`items.router`는 `app/routers/items.py` 파일 안의 `APIRouter`를 담고 있습니다.
+
+///
+
+`app.include_router()`로 각 `APIRouter`를 메인 `FastAPI` 애플리케이션에 추가할 수 있습니다.
+
+그 router의 모든 route가 애플리케이션의 일부로 포함됩니다.
+
+/// note Technical Details | 기술 세부사항
+
+내부적으로는 `APIRouter`에 선언된 각 *path operation*마다 *path operation*을 실제로 생성합니다.
+
+즉, 내부적으로는 모든 것이 동일한 하나의 앱인 것처럼 동작합니다.
+
+///
+
+/// check | 확인
+
+router를 포함(include)할 때 성능을 걱정할 필요는 없습니다.
+
+이 작업은 마이크로초 단위이며 시작 시에만 발생합니다.
+
+따라서 성능에 영향을 주지 않습니다. ⚡
+
+///
+
+### 커스텀 `prefix`, `tags`, `responses`, `dependencies`로 `APIRouter` 포함하기 { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies }
+
+이제 조직에서 `app/internal/admin.py` 파일을 받았다고 가정해 봅시다.
+
+여기에는 조직에서 여러 프로젝트 간에 공유하는 관리자용 *path operations*가 있는 `APIRouter`가 들어 있습니다.
+
+이 예시에서는 매우 단순하게 만들겠습니다. 하지만 조직 내 다른 프로젝트와 공유되기 때문에, 이를 수정할 수 없어 `prefix`, `dependencies`, `tags` 등을 `APIRouter`에 직접 추가할 수 없다고 해봅시다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *}
+
+하지만 `APIRouter`를 포함할 때 커스텀 `prefix`를 지정해 모든 *path operations*가 `/admin`으로 시작하게 하고, 이 프로젝트에서 이미 가진 `dependencies`로 보호하고, `tags`와 `responses`도 포함하고 싶습니다.
+
+원래 `APIRouter`를 수정하지 않고도 `app.include_router()`에 파라미터를 전달해서 이를 선언할 수 있습니다:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[14:17] title["app/main.py"] *}
+
+이렇게 하면 원래 `APIRouter`는 수정되지 않으므로, 조직 내 다른 프로젝트에서도 동일한 `app/internal/admin.py` 파일을 계속 공유할 수 있습니다.
+
+결과적으로 우리 앱에서 `admin` 모듈의 각 *path operations*는 다음을 갖게 됩니다:
+
+* prefix `/admin`.
+* tag `admin`.
+* dependency `get_token_header`.
+* 응답 `418`. 🍵
+
+하지만 이는 우리 앱에서 그 `APIRouter`에만 영향을 주며, 이를 사용하는 다른 코드에는 영향을 주지 않습니다.
+
+따라서 다른 프로젝트들은 같은 `APIRouter`를 다른 인증 방식으로 사용할 수도 있습니다.
+
+### *path operation* 포함하기 { #include-a-path-operation }
+
+*path operations*를 `FastAPI` 앱에 직접 추가할 수도 있습니다.
+
+여기서는 가능하다는 것을 보여주기 위해... 그냥 해봅니다 🤷:
+
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[21:23] title["app/main.py"] *}
+
+그리고 `app.include_router()`로 추가한 다른 모든 *path operations*와 함께 올바르게 동작합니다.
+
+/// info | 정보
+
+**참고**: 이는 매우 기술적인 세부사항이라 아마 **그냥 건너뛰어도 됩니다**.
+
+---
+
+`APIRouter`는 "mount"되는 것이 아니며, 애플리케이션의 나머지 부분과 격리되어 있지 않습니다.
+
+이는 OpenAPI 스키마와 사용자 인터페이스에 그들의 *path operations*를 포함시키고 싶기 때문입니다.
+
+나머지와 독립적으로 격리해 "mount"할 수 없으므로, *path operations*는 직접 포함되는 것이 아니라 "clone"(재생성)됩니다.
+
+///
+
+## 자동 API 문서 확인하기 { #check-the-automatic-api-docs }
+
+이제 앱을 실행하세요:
+
+
+
+## 같은 router를 다른 `prefix`로 여러 번 포함하기 { #include-the-same-router-multiple-times-with-different-prefix }
+
+`.include_router()`를 사용해 *같은* router를 서로 다른 prefix로 여러 번 포함할 수도 있습니다.
+
+예를 들어 `/api/v1`과 `/api/latest`처럼 서로 다른 prefix로 동일한 API를 노출할 때 유용할 수 있습니다.
+
+이는 고급 사용 방식이라 실제로 필요하지 않을 수도 있지만, 필요할 때를 위해 제공됩니다.
+
+## `APIRouter`에 다른 `APIRouter` 포함하기 { #include-an-apirouter-in-another }
+
+`APIRouter`를 `FastAPI` 애플리케이션에 포함할 수 있는 것과 같은 방식으로, 다음을 사용해 `APIRouter`를 다른 `APIRouter`에 포함할 수 있습니다:
+
+```Python
+router.include_router(other_router)
+```
+
+`FastAPI` 앱에 `router`를 포함하기 전에 수행해야 하며, 그래야 `other_router`의 *path operations*도 함께 포함됩니다.
diff --git a/docs/ko/docs/tutorial/body-fields.md b/docs/ko/docs/tutorial/body-fields.md
index 4708e7099..c98734ab3 100644
--- a/docs/ko/docs/tutorial/body-fields.md
+++ b/docs/ko/docs/tutorial/body-fields.md
@@ -1,8 +1,8 @@
-# 본문 - 필드
+# 본문 - 필드 { #body-fields }
-`Query`, `Path`와 `Body`를 사용해 *경로 작동 함수* 매개변수 내에서 추가적인 검증이나 메타데이터를 선언한 것처럼 Pydantic의 `Field`를 사용하여 모델 내에서 검증과 메타데이터를 선언할 수 있습니다.
+`Query`, `Path`와 `Body`를 사용해 *경로 처리 함수* 매개변수 내에서 추가적인 검증이나 메타데이터를 선언한 것처럼 Pydantic의 `Field`를 사용하여 모델 내에서 검증과 메타데이터를 선언할 수 있습니다.
-## `Field` 임포트
+## `Field` 임포트 { #import-field }
먼저 이를 임포트해야 합니다:
@@ -14,7 +14,7 @@
///
-## 모델 어트리뷰트 선언
+## 모델 어트리뷰트 선언 { #declare-model-attributes }
그 다음 모델 어트리뷰트와 함께 `Field`를 사용할 수 있습니다:
@@ -22,7 +22,7 @@
`Field`는 `Query`, `Path`와 `Body`와 같은 방식으로 동작하며, 모두 같은 매개변수들 등을 가집니다.
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
실제로 `Query`, `Path`등, 여러분이 앞으로 볼 다른 것들은 공통 클래스인 `Param` 클래스의 서브클래스 객체를 만드는데, 그 자체로 Pydantic의 `FieldInfo` 클래스의 서브클래스입니다.
@@ -36,11 +36,11 @@
/// tip | 팁
-주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 작동 함수*의 매개변수와 같은 구조를 가진다는 점 입니다.
+주목할 점은 타입, 기본 값 및 `Field`로 이루어진 각 모델 어트리뷰트가 `Path`, `Query`와 `Body`대신 `Field`를 사용하는 *경로 처리 함수*의 매개변수와 같은 구조를 가진다는 점 입니다.
///
-## 별도 정보 추가
+## 별도 정보 추가 { #add-extra-information }
`Field`, `Query`, `Body`, 그 외 안에 별도 정보를 선언할 수 있습니다. 이는 생성된 JSON 스키마에 포함됩니다.
@@ -53,7 +53,7 @@
///
-## 요약
+## 요약 { #recap }
모델 어트리뷰트를 위한 추가 검증과 메타데이터 선언하기 위해 Pydantic의 `Field` 를 사용할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/body-multiple-params.md b/docs/ko/docs/tutorial/body-multiple-params.md
index edf892dfa..701351e63 100644
--- a/docs/ko/docs/tutorial/body-multiple-params.md
+++ b/docs/ko/docs/tutorial/body-multiple-params.md
@@ -1,26 +1,24 @@
-# 본문 - 다중 매개변수
+# 본문 - 다중 매개변수 { #body-multiple-parameters }
-지금부터 `Path`와 `Query`를 어떻게 사용하는지 확인하겠습니다.
+이제 `Path`와 `Query`를 어떻게 사용하는지 확인했으니, 요청 본문 선언에 대한 더 고급 사용법을 살펴보겠습니다.
-요청 본문 선언에 대한 심화 사용법을 알아보겠습니다.
+## `Path`, `Query` 및 본문 매개변수 혼합 { #mix-path-query-and-body-parameters }
-## `Path`, `Query` 및 본문 매개변수 혼합
+먼저, 물론 `Path`, `Query` 및 요청 본문 매개변수 선언을 자유롭게 혼합해서 사용할 수 있고, **FastAPI**는 어떤 동작을 할지 압니다.
-당연하게 `Path`, `Query` 및 요청 본문 매개변수 선언을 자유롭게 혼합해서 사용할 수 있고, **FastAPI**는 어떤 동작을 할지 압니다.
+또한 기본 값을 `None`으로 설정해 본문 매개변수를 선택사항으로 선언할 수 있습니다:
-또한, 기본 값을 `None`으로 설정해 본문 매개변수를 선택사항으로 선언할 수 있습니다.
-
-{* ../../docs_src/body_multiple_params/tutorial001.py hl[19:21] *}
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
/// note | 참고
-이 경우에는 본문으로 부터 가져온 ` item`은 기본값이 `None`이기 때문에, 선택사항이라는 점을 유의해야 합니다.
+이 경우에는 본문에서 가져올 `item`이 선택사항이라는 점을 유의하세요. 기본값이 `None`이기 때문입니다.
///
-## 다중 본문 매개변수
+## 다중 본문 매개변수 { #multiple-body-parameters }
-이전 예제에서 보듯이, *경로 작동*은 아래와 같이 `Item` 속성을 가진 JSON 본문을 예상합니다:
+이전 예제에서, *경로 처리*는 아래처럼 `Item`의 속성을 가진 JSON 본문을 예상합니다:
```JSON
{
@@ -33,11 +31,12 @@
하지만, 다중 본문 매개변수 역시 선언할 수 있습니다. 예. `item`과 `user`:
-{* ../../docs_src/body_multiple_params/tutorial002.py hl[22] *}
+{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
+
-이 경우에, **FastAPI**는 이 함수 안에 한 개 이상의 본문 매개변수(Pydantic 모델인 두 매개변수)가 있다고 알 것입니다.
+이 경우에, **FastAPI**는 이 함수에 본문 매개변수가 1개보다 많다는 것을 알아챌 것입니다(두 매개변수가 Pydantic 모델입니다).
-그래서, 본문의 매개변수 이름을 키(필드 명)로 사용할 수 있고, 다음과 같은 본문을 예측합니다:
+그래서, 본문에서 매개변수 이름을 키(필드 이름)로 사용하고, 다음과 같은 본문을 예상합니다:
```JSON
{
@@ -56,29 +55,28 @@
/// note | 참고
-이전과 같이 `item`이 선언 되었더라도, 본문 내의 `item` 키가 있을 것이라고 예측합니다.
+`item`이 이전과 같은 방식으로 선언되었더라도, 이제는 본문에서 `item` 키 안에 있을 것으로 예상된다는 점을 유의하세요.
///
-FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를 특별한 내용으로 받도록 할 것입니다.
+**FastAPI**는 요청에서 자동으로 변환을 수행하여, 매개변수 `item`이 해당하는 내용을 받고 `user`도 마찬가지로 받도록 합니다.
-복합 데이터의 검증을 수행하고 OpenAPI 스키마 및 자동 문서를 문서화합니다.
+복합 데이터의 검증을 수행하고, OpenAPI 스키마 및 자동 문서에도 그에 맞게 문서화합니다.
-## 본문 내의 단일 값
+## 본문 내의 단일 값 { #singular-values-in-body }
-쿼리 및 경로 매개변수에 대한 추가 데이터를 정의하는 `Query`와 `Path`와 같이, **FastAPI**는 동등한 `Body`를 제공합니다.
+쿼리 및 경로 매개변수에 대한 추가 데이터를 정의하는 `Query`와 `Path`가 있는 것과 같은 방식으로, **FastAPI**는 동등한 `Body`를 제공합니다.
-예를 들어 이전의 모델을 확장하면, `item`과 `user`와 동일한 본문에 또 다른 `importance`라는 키를 갖도록 할 수있습니다.
+예를 들어 이전 모델을 확장해서, `item`과 `user` 외에도 같은 본문에 `importance`라는 다른 키를 두고 싶을 수 있습니다.
-단일 값을 그대로 선언한다면, **FastAPI**는 쿼리 매개변수로 가정할 것입니다.
+단일 값이므로 그대로 선언하면, **FastAPI**는 이를 쿼리 매개변수라고 가정할 것입니다.
-하지만, **FastAPI**의 `Body`를 사용해 다른 본문 키로 처리하도록 제어할 수 있습니다:
+하지만 `Body`를 사용하여 다른 본문 키로 처리하도록 **FastAPI**에 지시할 수 있습니다:
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
-{* ../../docs_src/body_multiple_params/tutorial003.py hl[23] *}
-
-이 경우에는 **FastAPI**는 본문을 이와 같이 예측할 것입니다:
+이 경우에는 **FastAPI**가 다음과 같은 본문을 예상할 것입니다:
```JSON
{
@@ -96,58 +94,55 @@ FastAPI는 요청을 자동으로 변환해, 매개변수의 `item`과 `user`를
}
```
-다시 말해, 데이터 타입, 검증, 문서 등을 변환합니다.
+다시 말해, 데이터 타입을 변환하고, 검증하고, 문서화하는 등의 작업을 수행합니다.
-## 다중 본문 매개변수와 쿼리
+## 다중 본문 매개변수와 쿼리 { #multiple-body-params-and-query }
-당연히, 필요할 때마다 추가적인 쿼리 매개변수를 선언할 수 있고, 이는 본문 매개변수에 추가됩니다.
+물론, 필요할 때마다 어떤 본문 매개변수에 추가로 쿼리 매개변수도 선언할 수 있습니다.
-기본적으로 단일 값은 쿼리 매개변수로 해석되므로, 명시적으로 `Query`를 추가할 필요가 없고, 아래처럼 할 수 있습니다:
+기본적으로 단일 값은 쿼리 매개변수로 해석되므로, 명시적으로 `Query`를 추가할 필요 없이 이렇게 하면 됩니다:
-{* ../../docs_src/body_multiple_params/tutorial004.py hl[27] *}
+```Python
+q: Union[str, None] = None
+```
-이렇게:
+또는 Python 3.10 이상에서는:
```Python
-q: Optional[str] = None
+q: str | None = None
```
-/// info | 정보
+예를 들어:
-`Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들처럼 동일한 추가 검증과 메타데이터 매개변수를 갖고 있습니다.
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-///
-## 단일 본문 매개변수 삽입하기
+/// info | 정보
+
+`Body` 또한 `Query`, `Path` 그리고 이후에 볼 다른 것들과 마찬가지로 동일한 추가 검증과 메타데이터 매개변수를 모두 갖고 있습니다.
-Pydantic 모델 `Item`의 `item`을 본문 매개변수로 오직 한개만 갖고있다고 하겠습니다.
+///
-기본적으로 **FastAPI**는 직접 본문으로 예측할 것입니다.
+## 단일 본문 매개변수 삽입하기 { #embed-a-single-body-parameter }
-하지만, 만약 모델 내용에 `item `키를 가진 JSON으로 예측하길 원한다면, 추가적인 본문 매개변수를 선언한 것처럼 `Body`의 특별한 매개변수인 `embed`를 사용할 수 있습니다:
+Pydantic 모델 `Item`에서 가져온 단일 `item` 본문 매개변수만 있다고 하겠습니다.
-{* ../../docs_src/body_multiple_params/tutorial005.py hl[17] *}
+기본적으로 **FastAPI**는 그 본문을 직접 예상합니다.
-아래 처럼:
+하지만 추가 본문 매개변수를 선언할 때처럼, `item` 키를 가지고 그 안에 모델 내용이 들어 있는 JSON을 예상하게 하려면, `Body`의 특별한 매개변수 `embed`를 사용할 수 있습니다:
```Python
-item: Item = Body(..., embed=True)
+item: Item = Body(embed=True)
```
-이 경우에 **FastAPI**는 본문을 아래 대신에:
+다음과 같이요:
-```JSON hl_lines="2"
-{
- "name": "Foo",
- "description": "The pretender",
- "price": 42.0,
- "tax": 3.2
-}
-```
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
-아래 처럼 예측할 것 입니다:
-```JSON
+이 경우 **FastAPI**는 다음과 같은 본문을 예상합니다:
+
+```JSON hl_lines="2"
{
"item": {
"name": "Foo",
@@ -158,12 +153,23 @@ item: Item = Body(..., embed=True)
}
```
-## 정리
+다음 대신에:
+
+```JSON
+{
+ "name": "Foo",
+ "description": "The pretender",
+ "price": 42.0,
+ "tax": 3.2
+}
+```
+
+## 정리 { #recap }
-요청이 단 한개의 본문을 가지고 있더라도, *경로 작동 함수*로 다중 본문 매개변수를 추가할 수 있습니다.
+요청은 본문을 하나만 가질 수 있지만, *경로 처리 함수*에 다중 본문 매개변수를 추가할 수 있습니다.
-하지만, **FastAPI**는 이를 처리하고, 함수에 올바른 데이터를 제공하며, *경로 작동*으로 올바른 스키마를 검증하고 문서화 합니다.
+하지만 **FastAPI**는 이를 처리하고, 함수에 올바른 데이터를 제공하며, *경로 처리*에서 올바른 스키마를 검증하고 문서화합니다.
-또한, 단일 값을 본문의 일부로 받도록 선언할 수 있습니다.
+또한 단일 값을 본문의 일부로 받도록 선언할 수 있습니다.
-그리고 **FastAPI**는 단 한개의 매개변수가 선언 되더라도, 본문 내의 키로 삽입 시킬 수 있습니다.
+그리고 단 하나의 매개변수만 선언되어 있더라도, **FastAPI**에 본문을 키 안에 삽입하도록 지시할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/body-nested-models.md b/docs/ko/docs/tutorial/body-nested-models.md
index ebd7b3ba6..4a8c1afc1 100644
--- a/docs/ko/docs/tutorial/body-nested-models.md
+++ b/docs/ko/docs/tutorial/body-nested-models.md
@@ -1,35 +1,26 @@
-# 본문 - 중첩 모델
+# 본문 - 중첩 모델 { #body-nested-models }
-**FastAPI**를 이용하면 (Pydantic 덕분에) 단독으로 깊이 중첩된 모델을 정의, 검증, 문서화하며 사용할 수 있습니다.
-## 리스트 필드
+**FastAPI**를 사용하면 (Pydantic 덕분에) 임의로 깊게 중첩된 모델을 정의, 검증, 문서화하고 사용할 수 있습니다.
-어트리뷰트를 서브타입으로 정의할 수 있습니다. 예를 들어 파이썬 `list`는:
-
-{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
-
-이는 `tags`를 항목 리스트로 만듭니다. 각 항목의 타입을 선언하지 않더라도요.
+## 리스트 필드 { #list-fields }
-## 타입 매개변수가 있는 리스트 필드
-
-하지만 파이썬은 내부의 타입이나 "타입 매개변수"를 선언할 수 있는 특정 방법이 있습니다:
+어트리뷰트를 서브타입으로 정의할 수 있습니다. 예를 들어 파이썬 `list`는:
-### typing의 `List` 임포트
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
-먼저, 파이썬 표준 `typing` 모듈에서 `List`를 임포트합니다:
+이는 `tags`를 리스트로 만들지만, 리스트 요소의 타입을 선언하지는 않습니다.
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
+## 타입 매개변수가 있는 리스트 필드 { #list-fields-with-type-parameter }
-### 타입 매개변수로 `List` 선언
+하지만 파이썬에는 내부 타입, 즉 "타입 매개변수"를 사용해 리스트를 선언하는 특정한 방법이 있습니다:
-`list`, `dict`, `tuple`과 같은 타입 매개변수(내부 타입)를 갖는 타입을 선언하려면:
+### 타입 매개변수로 `list` 선언 { #declare-a-list-with-a-type-parameter }
-* `typing` 모듈에서 임포트
-* 대괄호를 사용하여 "타입 매개변수"로 내부 타입 전달: `[` 및 `]`
+`list`, `dict`, `tuple`처럼 타입 매개변수(내부 타입)를 갖는 타입을 선언하려면,
+대괄호 `[` 및 `]`를 사용해 내부 타입(들)을 "타입 매개변수"로 전달하세요.
```Python
-from typing import List
-
-my_list: List[str]
+my_list: list[str]
```
이 모든 것은 타입 선언을 위한 표준 파이썬 문법입니다.
@@ -38,45 +29,45 @@ my_list: List[str]
마찬가지로 예제에서 `tags`를 구체적으로 "문자열의 리스트"로 만들 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## 집합 타입
+## 집합 타입 { #set-types }
-그런데 생각해보니 태그는 반복되면 안 되고, 고유한(Unique) 문자열이어야 할 것 같습니다.
+그런데 생각해보니 태그는 반복되면 안 되고, 아마 고유한 문자열이어야 할 것입니다.
-그리고 파이썬은 집합을 위한 특별한 데이터 타입 `set`이 있습니다.
+그리고 파이썬에는 고유한 항목들의 집합을 위한 특별한 데이터 타입 `set`이 있습니다.
-그렇다면 `Set`을 임포트 하고 `tags`를 `str`의 `set`으로 선언할 수 있습니다:
+그렇다면 `tags`를 문자열의 집합으로 선언할 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
-덕분에 중복 데이터가 있는 요청을 수신하더라도 고유한 항목들의 집합으로 변환됩니다.
+이렇게 하면 중복 데이터가 있는 요청을 받더라도 고유한 항목들의 집합으로 변환됩니다.
-그리고 해당 데이터를 출력 할 때마다 소스에 중복이 있더라도 고유한 항목들의 집합으로 출력됩니다.
+그리고 해당 데이터를 출력할 때마다, 소스에 중복이 있더라도 고유한 항목들의 집합으로 출력됩니다.
또한 그에 따라 주석이 생기고 문서화됩니다.
-## 중첩 모델
+## 중첩 모델 { #nested-models }
Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
-그런데 해당 타입 자체로 또다른 Pydantic 모델의 타입이 될 수 있습니다.
+그런데 그 타입 자체가 또 다른 Pydantic 모델일 수 있습니다.
-그러므로 특정한 어트리뷰트의 이름, 타입, 검증을 사용하여 깊게 중첩된 JSON "객체"를 선언할 수 있습니다.
+따라서 특정한 어트리뷰트 이름, 타입, 검증을 사용하여 깊게 중첩된 JSON "객체"를 선언할 수 있습니다.
-모든 것이 단독으로 중첩됩니다.
+모든 것이 임의의 깊이로 중첩됩니다.
-### 서브모델 정의
+### 서브모델 정의 { #define-a-submodel }
-예를 들어, `Image` 모델을 선언할 수 있습니다:
+예를 들어, `Image` 모델을 정의할 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### 서브모듈을 타입으로 사용
+### 서브모델을 타입으로 사용 { #use-the-submodel-as-a-type }
-그리고 어트리뷰트의 타입으로 사용할 수 있습니다:
+그리고 이를 어트리뷰트의 타입으로 사용할 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
이는 **FastAPI**가 다음과 유사한 본문을 기대한다는 것을 의미합니다:
@@ -94,32 +85,32 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
}
```
-다시 한번, **FastAPI**를 사용하여 해당 선언을 함으로써 얻는 것은:
+다시 한번, **FastAPI**로 그 선언만 해도 얻는 것은:
* 중첩 모델도 편집기 지원(자동완성 등)
* 데이터 변환
* 데이터 검증
* 자동 문서화
-## 특별한 타입과 검증
+## 특별한 타입과 검증 { #special-types-and-validation }
-`str`, `int`, `float` 등과 같은 단일 타입과는 별개로, `str`을 상속하는 더 복잡한 단일 타입을 사용할 수 있습니다.
+`str`, `int`, `float` 등과 같은 일반적인 단일 타입과는 별개로, `str`을 상속하는 더 복잡한 단일 타입을 사용할 수 있습니다.
-모든 옵션을 보려면, Pydantic's exotic types 문서를 확인하세요. 다음 장에서 몇가지 예제를 볼 수 있습니다.
+사용할 수 있는 모든 옵션을 보려면 Pydantic의 Type Overview를 확인하세요. 다음 장에서 몇 가지 예제를 볼 수 있습니다.
-예를 들어 `Image` 모델 안에 `url` 필드를 `str` 대신 Pydantic의 `HttpUrl`로 선언할 수 있습니다:
+예를 들어 `Image` 모델에는 `url` 필드가 있으므로, 이를 `str` 대신 Pydantic의 `HttpUrl` 인스턴스로 선언할 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
-이 문자열이 유효한 URL인지 검사하고 JSON 스키마/OpenAPI로 문서화 됩니다.
+이 문자열은 유효한 URL인지 검사되며, JSON Schema / OpenAPI에도 그에 맞게 문서화됩니다.
-## 서브모델 리스트를 갖는 어트리뷰트
+## 서브모델 리스트를 갖는 어트리뷰트 { #attributes-with-lists-of-submodels }
`list`, `set` 등의 서브타입으로 Pydantic 모델을 사용할 수도 있습니다:
-{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
-아래와 같은 JSON 본문으로 예상(변환, 검증, 문서화 등을)합니다:
+아래와 같은 JSON 본문을 예상(변환, 검증, 문서화 등)합니다:
```JSON hl_lines="11"
{
@@ -147,84 +138,84 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
/// info | 정보
-`images` 키가 어떻게 이미지 객체 리스트를 갖는지 주목하세요.
+`images` 키가 이제 이미지 객체 리스트를 갖는지 주목하세요.
///
-## 깊게 중첩된 모델
+## 깊게 중첩된 모델 { #deeply-nested-models }
-단독으로 깊게 중첩된 모델을 정의할 수 있습니다:
+임의로 깊게 중첩된 모델을 정의할 수 있습니다:
-{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *}
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
/// info | 정보
-`Offer`가 선택사항 `Image` 리스트를 차례로 갖는 `Item` 리스트를 어떻게 가지고 있는지 주목하세요
+`Offer`가 `Item`의 리스트를 가지고, 그 `Item`이 다시 선택 사항인 `Image` 리스트를 갖는지 주목하세요
///
-## 순수 리스트의 본문
+## 순수 리스트의 본문 { #bodies-of-pure-lists }
-예상되는 JSON 본문의 최상위 값이 JSON `array`(파이썬 `list`)면, Pydantic 모델에서와 마찬가지로 함수의 매개변수에서 타입을 선언할 수 있습니다:
+예상되는 JSON 본문의 최상위 값이 JSON `array`(파이썬 `list`)라면, Pydantic 모델에서와 마찬가지로 함수의 매개변수에서 타입을 선언할 수 있습니다:
```Python
-images: List[Image]
+images: list[Image]
```
이를 아래처럼:
-{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## 어디서나 편집기 지원
+## 어디서나 편집기 지원 { #editor-support-everywhere }
-그리고 어디서나 편집기 지원을 받을수 있습니다.
+그리고 어디서나 편집기 지원을 받을 수 있습니다.
리스트 내부 항목의 경우에도:
-Pydantic 모델 대신에 `dict`를 직접 사용하여 작업할 경우, 이러한 편집기 지원을 받을수 없습니다.
+Pydantic 모델 대신 `dict`로 직접 작업한다면 이런 종류의 편집기 지원을 받을 수 없습니다.
-하지만 수신한 딕셔너리가 자동으로 변환되고 출력도 자동으로 JSON으로 변환되므로 걱정할 필요는 없습니다.
+하지만 그 부분에 대해서도 걱정할 필요는 없습니다. 들어오는 dict는 자동으로 변환되고, 출력도 자동으로 JSON으로 변환됩니다.
-## 단독 `dict`의 본문
+## 임의의 `dict` 본문 { #bodies-of-arbitrary-dicts }
-일부 타입의 키와 다른 타입의 값을 사용하여 `dict`로 본문을 선언할 수 있습니다.
+또한 키는 어떤 타입이고 값은 다른 타입인 `dict`로 본문을 선언할 수 있습니다.
-(Pydantic을 사용한 경우처럼) 유효한 필드/어트리뷰트 이름이 무엇인지 알 필요가 없습니다.
+이렇게 하면 (Pydantic 모델을 사용하는 경우처럼) 유효한 필드/어트리뷰트 이름이 무엇인지 미리 알 필요가 없습니다.
-아직 모르는 키를 받으려는 경우 유용합니다.
+아직 모르는 키를 받으려는 경우에 유용합니다.
---
-다른 유용한 경우는 다른 타입의 키를 가질 때입니다. 예. `int`.
+또 다른 유용한 경우는 다른 타입(예: `int`)의 키를 갖고 싶을 때입니다.
여기서 그 경우를 볼 것입니다.
-이 경우, `float` 값을 가진 `int` 키가 있는 모든 `dict`를 받아들입니다:
+이 경우, `int` 키와 `float` 값을 가진 한 어떤 `dict`든 받아들입니다:
-{* ../../docs_src/body_nested_models/tutorial009.py hl[15] *}
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
/// tip | 팁
-JSON은 오직 `str`형 키만 지원한다는 것을 염두에 두세요.
+JSON은 키로 `str`만 지원한다는 것을 염두에 두세요.
-하지만 Pydantic은 자동 데이터 변환이 있습니다.
+하지만 Pydantic은 자동 데이터 변환 기능이 있습니다.
-즉, API 클라이언트가 문자열을 키로 보내더라도 해당 문자열이 순수한 정수를 포함하는한 Pydantic은 이를 변환하고 검증합니다.
+즉, API 클라이언트는 키로 문자열만 보낼 수 있더라도, 해당 문자열이 순수한 정수를 포함하기만 하면 Pydantic이 이를 변환하고 검증합니다.
-그러므로 `weights`로 받은 `dict`는 실제로 `int` 키와 `float` 값을 가집니다.
+그리고 `weights`로 받는 `dict`는 실제로 `int` 키와 `float` 값을 갖게 됩니다.
///
-## 요약
+## 요약 { #recap }
-**FastAPI**를 사용하면 Pydantic 모델이 제공하는 최대 유연성을 확보하면서 코드를 간단하고 짧게, 그리고 우아하게 유지할 수 있습니다.
+**FastAPI**를 사용하면 Pydantic 모델이 제공하는 최대 유연성을 확보하면서 코드를 간단하고 짧고 우아하게 유지할 수 있습니다.
-물론 아래의 이점도 있습니다:
+하지만 아래의 모든 이점도 있습니다:
-* 편집기 지원 (자동완성이 어디서나!)
-* 데이터 변환 (일명 파싱/직렬화)
+* 편집기 지원(어디서나 자동완성!)
+* 데이터 변환(일명 파싱/직렬화)
* 데이터 검증
* 스키마 문서화
* 자동 문서
diff --git a/docs/ko/docs/tutorial/body-updates.md b/docs/ko/docs/tutorial/body-updates.md
new file mode 100644
index 000000000..3719e1ffa
--- /dev/null
+++ b/docs/ko/docs/tutorial/body-updates.md
@@ -0,0 +1,100 @@
+# Body - 업데이트 { #body-updates }
+
+## `PUT`으로 교체 업데이트하기 { #update-replacing-with-put }
+
+항목을 업데이트하려면 HTTP `PUT` 작업을 사용할 수 있습니다.
+
+`jsonable_encoder`를 사용해 입력 데이터를 JSON으로 저장할 수 있는 데이터로 변환할 수 있습니다(예: NoSQL 데이터베이스 사용 시). 예를 들어 `datetime`을 `str`로 변환하는 경우입니다.
+
+{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
+
+`PUT`은 기존 데이터를 **대체**해야 하는 데이터를 받는 데 사용합니다.
+
+### 대체 시 주의사항 { #warning-about-replacing }
+
+즉, `PUT`으로 항목 `bar`를 업데이트하면서 다음과 같은 body를 보낸다면:
+
+```Python
+{
+ "name": "Barz",
+ "price": 3,
+ "description": None,
+}
+```
+
+이미 저장된 속성 `"tax": 20.2`가 포함되어 있지 않기 때문에, 입력 모델은 `"tax": 10.5`라는 기본값을 사용하게 됩니다.
+
+그리고 데이터는 그 “새로운” `tax` 값 `10.5`로 저장됩니다.
+
+## `PATCH`로 부분 업데이트하기 { #partial-updates-with-patch }
+
+HTTP `PATCH` 작업을 사용해 데이터를 *부분적으로* 업데이트할 수도 있습니다.
+
+이는 업데이트하려는 데이터만 보내고, 나머지는 그대로 두는 것을 의미합니다.
+
+/// note | 참고
+
+`PATCH`는 `PUT`보다 덜 일반적으로 사용되고 덜 알려져 있습니다.
+
+그리고 많은 팀이 부분 업데이트에도 `PUT`만 사용합니다.
+
+여러분은 원하는 방식으로 **자유롭게** 사용할 수 있으며, **FastAPI**는 어떤 제한도 강제하지 않습니다.
+
+다만 이 가이드는 의도된 사용 방식이 대략 어떻게 되는지를 보여줍니다.
+
+///
+
+### Pydantic의 `exclude_unset` 파라미터 사용하기 { #using-pydantics-exclude-unset-parameter }
+
+부분 업데이트를 받으려면 Pydantic 모델의 `.model_dump()`에서 `exclude_unset` 파라미터를 사용하는 것이 매우 유용합니다.
+
+예: `item.model_dump(exclude_unset=True)`.
+
+이는 `item` 모델을 만들 때 실제로 설정된 데이터만 포함하는 `dict`를 생성하고, 기본값은 제외합니다.
+
+그 다음 이를 사용해 (요청에서 전송되어) 설정된 데이터만 포함하고 기본값은 생략한 `dict`를 만들 수 있습니다:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
+
+### Pydantic의 `update` 파라미터 사용하기 { #using-pydantics-update-parameter }
+
+이제 `.model_copy()`를 사용해 기존 모델의 복사본을 만들고, 업데이트할 데이터가 들어있는 `dict`를 `update` 파라미터로 전달할 수 있습니다.
+
+예: `stored_item_model.model_copy(update=update_data)`:
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
+
+### 부분 업데이트 요약 { #partial-updates-recap }
+
+정리하면, 부분 업데이트를 적용하려면 다음을 수행합니다:
+
+* (선택 사항) `PUT` 대신 `PATCH`를 사용합니다.
+* 저장된 데이터를 조회합니다.
+* 그 데이터를 Pydantic 모델에 넣습니다.
+* 입력 모델에서 기본값이 제외된 `dict`를 생성합니다(`exclude_unset` 사용).
+ * 이렇게 하면 모델의 기본값으로 이미 저장된 값을 덮어쓰지 않고, 사용자가 실제로 설정한 값만 업데이트할 수 있습니다.
+* 저장된 모델의 복사본을 만들고, 받은 부분 업데이트로 해당 속성들을 갱신합니다(`update` 파라미터 사용).
+* 복사한 모델을 DB에 저장할 수 있는 형태로 변환합니다(예: `jsonable_encoder` 사용).
+ * 이는 모델의 `.model_dump()` 메서드를 다시 사용하는 것과 비슷하지만, JSON으로 변환 가능한 데이터 타입으로 값이 확실히 변환되도록 보장합니다(예: `datetime` → `str`).
+* 데이터를 DB에 저장합니다.
+* 업데이트된 모델을 반환합니다.
+
+{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
+
+/// tip | 팁
+
+동일한 기법을 HTTP `PUT` 작업에서도 실제로 사용할 수 있습니다.
+
+하지만 여기의 예시는 이런 사용 사례를 위해 만들어진 `PATCH`를 사용합니다.
+
+///
+
+/// note | 참고
+
+입력 모델은 여전히 검증된다는 점에 유의하세요.
+
+따라서 모든 속성을 생략할 수 있는 부분 업데이트를 받으려면, 모든 속성이 optional로 표시된(기본값을 가지거나 `None`을 기본값으로 가지는) 모델이 필요합니다.
+
+**업데이트**를 위한 “모든 값이 optional인” 모델과, **생성**을 위한 “필수 값이 있는” 모델을 구분하려면 [추가 모델](extra-models.md){.internal-link target=_blank}에 설명된 아이디어를 사용할 수 있습니다.
+
+///
diff --git a/docs/ko/docs/tutorial/body.md b/docs/ko/docs/tutorial/body.md
index b3914fa4b..1e66c60c2 100644
--- a/docs/ko/docs/tutorial/body.md
+++ b/docs/ko/docs/tutorial/body.md
@@ -1,10 +1,10 @@
-# 요청 본문
+# 요청 본문 { #request-body }
클라이언트(브라우저라고 해봅시다)로부터 여러분의 API로 데이터를 보내야 할 때, **요청 본문**으로 보냅니다.
**요청** 본문은 클라이언트에서 API로 보내지는 데이터입니다. **응답** 본문은 API가 클라이언트로 보내는 데이터입니다.
-여러분의 API는 대부분의 경우 **응답** 본문을 보내야 합니다. 하지만 클라이언트는 **요청** 본문을 매 번 보낼 필요가 없습니다.
+여러분의 API는 대부분의 경우 **응답** 본문을 보내야 합니다. 하지만 클라이언트는 항상 **요청 본문**을 보낼 필요는 없고, 때로는 (쿼리 매개변수와 함께) 어떤 경로만 요청하고 본문은 보내지 않을 수도 있습니다.
**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 Pydantic 모델을 사용합니다.
@@ -18,13 +18,13 @@
///
-## Pydantic의 `BaseModel` 임포트
+## Pydantic의 `BaseModel` 임포트 { #import-pydantics-basemodel }
먼저 `pydantic`에서 `BaseModel`를 임포트해야 합니다:
{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## 여러분의 데이터 모델 만들기
+## 여러분의 데이터 모델 만들기 { #create-your-data-model }
`BaseModel`를 상속받은 클래스로 여러분의 데이터 모델을 선언합니다.
@@ -32,6 +32,7 @@
{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
+
쿼리 매개변수를 선언할 때와 같이, 모델 어트리뷰트가 기본 값을 가지고 있어도 이는 필수가 아닙니다. 그외에는 필수입니다. 그저 `None`을 사용하여 선택적으로 만들 수 있습니다.
예를 들면, 위의 이 모델은 JSON "`object`" (혹은 파이썬 `dict`)을 다음과 같이 선언합니다:
@@ -39,7 +40,7 @@
```JSON
{
"name": "Foo",
- "description": "선택적인 설명란",
+ "description": "An optional description",
"price": 45.2,
"tax": 3.5
}
@@ -54,15 +55,15 @@
}
```
-## 매개변수로서 선언하기
+## 매개변수로서 선언하기 { #declare-it-as-a-parameter }
-여러분의 *경로 작동*에 추가하기 위해, 경로 매개변수 그리고 쿼리 매개변수에서 선언했던 것과 같은 방식으로 선언하면 됩니다.
+여러분의 *경로 처리*에 추가하기 위해, 경로 매개변수 그리고 쿼리 매개변수에서 선언했던 것과 같은 방식으로 선언하면 됩니다.
{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
...그리고 만들어낸 모델인 `Item`으로 타입을 선언합니다.
-## 결과
+## 결과 { #results }
위에서의 단순한 파이썬 타입 선언으로, **FastAPI**는 다음과 같이 동작합니다:
@@ -72,20 +73,20 @@
* 만약 데이터가 유효하지 않다면, 정확히 어떤 것이 그리고 어디에서 데이터가 잘 못 되었는지 지시하는 친절하고 명료한 에러를 반환할 것입니다.
* 매개변수 `item`에 포함된 수신 데이터를 제공합니다.
* 함수 내에서 매개변수를 `Item` 타입으로 선언했기 때문에, 모든 어트리뷰트와 그에 대한 타입에 대한 편집기 지원(완성 등)을 또한 받을 수 있습니다.
-* 여러분의 모델을 위한 JSON 스키마 정의를 생성합니다. 여러분의 프로젝트에 적합하다면 여러분이 사용하고 싶은 곳 어디에서나 사용할 수 있습니다.
-* 이러한 스키마는, 생성된 OpenAPI 스키마 일부가 될 것이며, 자동 문서화 UI에 사용됩니다.
+* 여러분의 모델을 위한 JSON Schema 정의를 생성합니다. 여러분의 프로젝트에 적합하다면 여러분이 사용하고 싶은 곳 어디에서나 사용할 수 있습니다.
+* 이러한 스키마는, 생성된 OpenAPI 스키마 일부가 될 것이며, 자동 문서화 UIs에 사용됩니다.
-## 자동 문서화
+## 자동 문서화 { #automatic-docs }
모델의 JSON 스키마는 생성된 OpenAPI 스키마에 포함되며 대화형 API 문서에 표시됩니다:
-이를 필요로 하는 각각의 *경로 작동*내부의 API 문서에도 사용됩니다:
+이를 필요로 하는 각각의 *경로 처리* 내부의 API 문서에도 사용됩니다:
-## 편집기 지원
+## 편집기 지원 { #editor-support }
편집기에서, 함수 내에서 타입 힌트와 완성을 어디서나 (만약 Pydantic model 대신에 `dict`을 받을 경우 나타나지 않을 수 있습니다) 받을 수 있습니다:
@@ -97,13 +98,13 @@
단순한 우연이 아닙니다. 프레임워크 전체가 이러한 디자인을 중심으로 설계되었습니다.
-그 어떤 실행 전에, 모든 편집기에서 작동할 수 있도록 보장하기 위해 설계 단계에서 혹독하게 테스트되었습니다.
+그 어떤 구현 전에, 모든 편집기에서 작동할 수 있도록 보장하기 위해 설계 단계에서 혹독하게 테스트되었습니다.
이를 지원하기 위해 Pydantic 자체에서 몇몇 변경점이 있었습니다.
이전 스크린샷은 Visual Studio Code를 찍은 것입니다.
-하지만 똑같은 편집기 지원을 PyCharm에서 받을 수 있거나, 대부분의 다른 편집기에서도 받을 수 있습니다:
+하지만 똑같은 편집기 지원을 PyCharm와 대부분의 다른 파이썬 편집기에서도 받을 수 있습니다:
@@ -113,21 +114,21 @@
다음 사항을 포함해 Pydantic 모델에 대한 편집기 지원을 향상시킵니다:
-* 자동 완성
-* 타입 확인
-* 리팩토링
-* 검색
-* 점검
+* auto-completion
+* type checks
+* refactoring
+* searching
+* inspections
///
-## 모델 사용하기
+## 모델 사용하기 { #use-the-model }
함수 안에서 모델 객체의 모든 어트리뷰트에 직접 접근 가능합니다:
-{* ../../docs_src/body/tutorial002_py310.py hl[19] *}
+{* ../../docs_src/body/tutorial002_py310.py *}
-## 요청 본문 + 경로 매개변수
+## 요청 본문 + 경로 매개변수 { #request-body-path-parameters }
경로 매개변수와 요청 본문을 동시에 선언할 수 있습니다.
@@ -135,7 +136,8 @@
{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-## 요청 본문 + 경로 + 쿼리 매개변수
+
+## 요청 본문 + 경로 + 쿼리 매개변수 { #request-body-path-query-parameters }
**본문**, **경로** 그리고 **쿼리** 매개변수 모두 동시에 선언할 수도 있습니다.
@@ -153,10 +155,12 @@
FastAPI는 `q`의 값이 필요없음을 알게 될 것입니다. 기본 값이 `= None`이기 때문입니다.
-`Union[str, None]`에 있는 `Union`은 FastAPI에 의해 사용된 것이 아니지만, 편집기로 하여금 더 나은 지원과 에러 탐지를 지원할 것입니다.
+Python 3.10+의 `str | None` 또는 Python 3.9+의 `Union[str, None]`에 있는 `Union`은 FastAPI가 `q` 값이 필수가 아님을 판단하기 위해 사용하지 않습니다. 기본 값이 `= None`이기 때문에 필수가 아님을 알게 됩니다.
+
+하지만 타입 어노테이션을 추가하면 편집기가 더 나은 지원을 제공하고 오류를 감지할 수 있습니다.
///
-## Pydantic없이
+## Pydantic없이 { #without-pydantic }
-만약 Pydantic 모델을 사용하고 싶지 않다면, **Body** 매개변수를 사용할 수도 있습니다. [Body - 다중 매개변수: 본문에 있는 유일한 값](body-multiple-params.md#_2){.internal-link target=_blank} 문서를 확인하세요.
+만약 Pydantic 모델을 사용하고 싶지 않다면, **Body** 매개변수를 사용할 수도 있습니다. [Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank} 문서를 확인하세요.
diff --git a/docs/ko/docs/tutorial/cookie-param-models.md b/docs/ko/docs/tutorial/cookie-param-models.md
index e7eef0b1d..00238d1b7 100644
--- a/docs/ko/docs/tutorial/cookie-param-models.md
+++ b/docs/ko/docs/tutorial/cookie-param-models.md
@@ -1,8 +1,8 @@
-# 쿠키 매개변수 모델
+# 쿠키 매개변수 모델 { #cookie-parameter-models }
관련있는 **쿠키**들의 그룹이 있는 경우, **Pydantic 모델**을 생성하여 선언할 수 있습니다. 🍪
-이를 통해 **여러 위치**에서 **모델을 재사용** 할 수 있고 모든 매개변수에 대한 유효성 검사 및 메타데이터를 한 번에 선언할 수도 있습니다. 😍
+이를 통해 **여러 위치**에서 **모델을 재사용** 할 수 있고 모든 매개변수에 대한 유효성 검사 및 메타데이터를 한 번에 선언할 수도 있습니다. 😎
/// note | 참고
@@ -16,7 +16,7 @@
///
-## Pydantic 모델을 사용한 쿠키
+## Pydantic 모델을 사용한 쿠키 { #cookies-with-a-pydantic-model }
**Pydantic 모델**에 필요한 **쿠키** 매개변수를 선언한 다음, 해당 매개변수를 `Cookie`로 선언합니다:
@@ -24,7 +24,7 @@
**FastAPI**는 요청에서 받은 **쿠키**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
-## 문서 확인하기
+## 문서 확인하기 { #check-the-docs }
문서 UI `/docs`에서 정의한 쿠키를 볼 수 있습니다:
@@ -36,27 +36,27 @@
명심하세요, 내부적으로 **브라우저는 쿠키를 특별한 방식으로 처리**하기 때문에 **자바스크립트**가 쉽게 쿠키를 건드릴 수 **없습니다**.
-`/docs`에서 **API 문서 UI**로 이동하면 *경로 작업*에 대한 쿠키의 **문서**를 볼 수 있습니다.
+`/docs`에서 **API 문서 UI**로 이동하면 *경로 처리*에 대한 쿠키의 **문서**를 볼 수 있습니다.
하지만 아무리 **데이터를 입력**하고 "실행(Execute)"을 클릭해도, 문서 UI는 **자바스크립트**로 작동하기 때문에 쿠키는 전송되지 않고, 아무 값도 쓰지 않은 것처럼 **오류** 메시지를 보게 됩니다.
///
-## 추가 쿠키 금지하기
+## 추가 쿠키 금지하기 { #forbid-extra-cookies }
일부 특별한 사용 사례(흔하지는 않겠지만)에서는 수신하려는 쿠키를 **제한**할 수 있습니다.
-이제 API는 자신의 쿠키 동의를 제어할 수 있는 권한을 갖게 되었습니다. 🤪🍪
+이제 API는 자신의 cookie consent를 제어할 수 있는 권한을 갖게 되었습니다. 🤪🍪
Pydantic의 모델 구성을 사용하여 추가(`extra`) 필드를 금지(`forbid`)할 수 있습니다:
-{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
클라이언트가 **추가 쿠키**를 보내려고 시도하면, **오류** 응답을 받게 됩니다.
-API가 거부하는데도 동의를 얻기 위해 애쓰는 불쌍한 쿠키 배너(팝업)들. 🍪
+동의를 얻기 위해 애쓰는 불쌍한 쿠키 배너(팝업)들, API가 거부하는데도. 🍪
-예를 들어, 클라이언트가 `good-list-please` 값으로 `santa_tracker` 쿠키를 보내려고 하면 클라이언트는 `santa_tracker` 쿠키가 허용되지 않는다는 **오류** 응답을 받게 됩니다:
+예를 들어, 클라이언트가 `good-list-please` 값으로 `santa_tracker` 쿠키를 보내려고 하면 클라이언트는 `santa_tracker` 쿠키가 허용되지 않는다는 **오류** 응답을 받게 됩니다:
```json
{
@@ -71,6 +71,6 @@ Pydantic의 모델 구성을 사용하여 추가(`extra`) 필드를 금지(`forb
}
```
-## 요약
+## 요약 { #summary }
-**Pydantic 모델**을 사용하여 **FastAPI**에서 **쿠키**를 선언할 수 있습니다. 😍
+**Pydantic 모델**을 사용하여 **FastAPI**에서 **쿠키**를 선언할 수 있습니다. 😎
diff --git a/docs/ko/docs/tutorial/cookie-params.md b/docs/ko/docs/tutorial/cookie-params.md
index fba756d49..0591a5e96 100644
--- a/docs/ko/docs/tutorial/cookie-params.md
+++ b/docs/ko/docs/tutorial/cookie-params.md
@@ -1,14 +1,14 @@
-# 쿠키 매개변수
+# 쿠키 매개변수 { #cookie-parameters }
쿠키 매개변수를 `Query`와 `Path` 매개변수들과 같은 방식으로 정의할 수 있습니다.
-## `Cookie` 임포트
+## `Cookie` 임포트 { #import-cookie }
먼저 `Cookie`를 임포트합니다:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## `Cookie` 매개변수 선언
+## `Cookie` 매개변수 선언 { #declare-cookie-parameters }
그런 다음, `Path`와 `Query`처럼 동일한 구조를 사용하는 쿠키 매개변수를 선언합니다.
@@ -20,7 +20,7 @@
`Cookie`는 `Path` 및 `Query`의 "자매"클래스입니다. 이 역시 동일한 공통 `Param` 클래스를 상속합니다.
-`Query`, `Path`, `Cookie` 그리고 다른 것들은 `fastapi`에서 임포트 할 때, 실제로는 특별한 클래스를 반환하는 함수임을 기억하세요.
+하지만 `fastapi`에서 `Query`, `Path`, `Cookie` 그리고 다른 것들을 임포트할 때, 실제로는 특별한 클래스를 반환하는 함수임을 기억하세요.
///
@@ -30,6 +30,16 @@
///
-## 요약
+/// info | 정보
+
+**브라우저는 쿠키를** 내부적으로 특별한 방식으로 처리하기 때문에, **JavaScript**가 쉽게 쿠키를 다루도록 허용하지 않는다는 점을 염두에 두세요.
+
+`/docs`의 **API docs UI**로 이동하면 *경로 처리*에 대한 쿠키 **문서**를 확인할 수 있습니다.
+
+하지만 **데이터를 채우고** "Execute"를 클릭하더라도, docs UI는 **JavaScript**로 동작하기 때문에 쿠키가 전송되지 않고, 아무 값도 입력하지 않은 것처럼 **오류** 메시지를 보게 될 것입니다.
+
+///
+
+## 요약 { #recap }
-`Cookie`는 `Query`, `Path`와 동일한 패턴을 사용하여 선언합니다.
+`Query`와 `Path`에서 사용하는 것과 동일한 공통 패턴으로, `Cookie`를 사용해 쿠키를 선언합니다.
diff --git a/docs/ko/docs/tutorial/cors.md b/docs/ko/docs/tutorial/cors.md
index 1ef5a7480..0f3948a3d 100644
--- a/docs/ko/docs/tutorial/cors.md
+++ b/docs/ko/docs/tutorial/cors.md
@@ -1,10 +1,10 @@
-# 교차 출처 리소스 공유
+# CORS (교차-출처 리소스 공유) { #cors-cross-origin-resource-sharing }
-CORS 또는 "교차-출처 리소스 공유"란, 브라우저에서 동작하는 프론트엔드가 자바스크립트로 코드로 백엔드와 통신하고, 백엔드는 해당 프론트엔드와 다른 "출처"에 존재하는 상황을 의미합니다.
+CORS 또는 "Cross-Origin Resource Sharing"란, 브라우저에서 실행되는 프론트엔드에 백엔드와 통신하는 JavaScript 코드가 있고, 백엔드가 프론트엔드와 다른 "출처(origin)"에 있는 상황을 의미합니다.
-## 출처
+## 출처 { #origin }
-출처란 프로토콜(`http` , `https`), 도메인(`myapp.com`, `localhost`, `localhost.tiangolo.com` ), 그리고 포트(`80`, `443`, `8080` )의 조합을 의미합니다.
+출처란 프로토콜(`http`, `https`), 도메인(`myapp.com`, `localhost`, `localhost.tiangolo.com`), 그리고 포트(`80`, `443`, `8080`)의 조합을 의미합니다.
따라서, 아래는 모두 상이한 출처입니다:
@@ -12,74 +12,78 @@
* `https://localhost`
* `http://localhost:8080`
-모두 `localhost` 에 있지만, 서로 다른 프로토콜과 포트를 사용하고 있으므로 다른 "출처"입니다.
+모두 `localhost`에 있더라도, 서로 다른 프로토콜이나 포트를 사용하므로 서로 다른 "출처"입니다.
-## 단계
+## 단계 { #steps }
-브라우저 내 `http://localhost:8080`에서 동작하는 프론트엔드가 있고, 자바스크립트는 `http://localhost`를 통해 백엔드와 통신한다고 가정해봅시다(포트를 명시하지 않는 경우, 브라우저는 `80` 을 기본 포트로 간주합니다).
+그러면 브라우저에서 `http://localhost:8080`으로 실행되는 프론트엔드가 있고, 그 JavaScript가 `http://localhost`에서 실행되는 백엔드와 통신하려고 한다고 해봅시다(포트를 명시하지 않았기 때문에, 브라우저는 기본 포트 `80`을 가정합니다).
-그러면 브라우저는 백엔드에 HTTP `OPTIONS` 요청을 보내고, 백엔드에서 이 다른 출처(`http://localhost:8080`)와의 통신을 허가하는 적절한 헤더를 보내면, 브라우저는 프론트엔드의 자바스크립트가 백엔드에 요청을 보낼 수 있도록 합니다.
+그러면 브라우저는 `:80`-백엔드에 HTTP `OPTIONS` 요청을 보내고, 백엔드가 이 다른 출처(`http://localhost:8080`)로부터의 통신을 허가하는 적절한 헤더를 보내면, `:8080`-브라우저는 프론트엔드의 JavaScript가 `:80`-백엔드에 요청을 보낼 수 있도록 합니다.
-이를 위해, 백엔드는 "허용된 출처(allowed origins)" 목록을 가지고 있어야만 합니다.
+이를 위해, `:80`-백엔드는 "허용된 출처(allowed origins)" 목록을 가지고 있어야 합니다.
-이 경우, 프론트엔드가 제대로 동작하기 위해 `http://localhost:8080`을 목록에 포함해야 합니다.
+이 경우, `:8080`-프론트엔드가 올바르게 동작하려면 목록에 `http://localhost:8080`이 포함되어야 합니다.
-## 와일드카드
+## 와일드카드 { #wildcards }
-모든 출처를 허용하기 위해 목록을 `"*"` ("와일드카드")로 선언하는 것도 가능합니다.
+또한 목록을 `"*"`("와일드카드")로 선언해 모두 허용된다고 말할 수도 있습니다.
-하지만 이것은 특정한 유형의 통신만을 허용하며, 쿠키 및 액세스 토큰과 사용되는 인증 헤더(Authoriztion header) 등이 포함된 경우와 같이 자격 증명(credentials)이 포함된 통신은 허용되지 않습니다.
+하지만 그러면 자격 증명(credentials)이 포함된 모든 것을 제외하고 특정 유형의 통신만 허용하게 됩니다. 예: 쿠키, Bearer Token에 사용되는 것과 같은 Authorization 헤더 등.
-따라서 모든 작업을 의도한대로 실행하기 위해, 허용되는 출처를 명시적으로 지정하는 것이 좋습니다.
+따라서 모든 것이 올바르게 동작하게 하려면, 허용된 출처를 명시적으로 지정하는 것이 더 좋습니다.
-## `CORSMiddleware` 사용
+## `CORSMiddleware` 사용 { #use-corsmiddleware }
-`CORSMiddleware` 을 사용하여 **FastAPI** 응용 프로그램의 교차 출처 리소스 공유 환경을 설정할 수 있습니다.
+`CORSMiddleware`를 사용하여 **FastAPI** 애플리케이션에서 이를 설정할 수 있습니다.
-* `CORSMiddleware` 임포트.
-* 허용되는 출처(문자열 형식)의 리스트 생성.
-* FastAPI 응용 프로그램에 "미들웨어(middleware)"로 추가.
+* `CORSMiddleware`를 임포트합니다.
+* 허용된 출처(문자열)의 리스트를 생성합니다.
+* **FastAPI** 애플리케이션에 "미들웨어(middleware)"로 추가합니다.
-백엔드에서 다음의 사항을 허용할지에 대해 설정할 수도 있습니다:
+또한 백엔드가 다음을 허용할지 여부도 지정할 수 있습니다:
-* 자격증명 (인증 헤더, 쿠키 등).
-* 특정한 HTTP 메소드(`POST`, `PUT`) 또는 와일드카드 `"*"` 를 사용한 모든 HTTP 메소드.
-* 특정한 HTTP 헤더 또는 와일드카드 `"*"` 를 사용한 모든 HTTP 헤더.
+* 자격 증명(Authorization 헤더, 쿠키 등).
+* 특정 HTTP 메서드(`POST`, `PUT`) 또는 와일드카드 `"*"`를 사용한 모든 메서드.
+* 특정 HTTP 헤더 또는 와일드카드 `"*"`를 사용한 모든 헤더.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
-`CORSMiddleware` 에서 사용하는 기본 매개변수는 제한적이므로, 브라우저가 교차-도메인 상황에서 특정한 출처, 메소드, 헤더 등을 사용할 수 있도록 하려면 이들을 명시적으로 허용해야 합니다.
-다음의 인자들이 지원됩니다:
+`CORSMiddleware` 구현에서 사용하는 기본 매개변수는 기본적으로 제한적이므로, 브라우저가 Cross-Domain 컨텍스트에서 특정 출처, 메서드 또는 헤더를 사용할 수 있도록 하려면 이를 명시적으로 활성화해야 합니다.
-* `allow_origins` - 교차-출처 요청을 보낼 수 있는 출처의 리스트입니다. 예) `['https://example.org', 'https://www.example.org']`. 모든 출처를 허용하기 위해 `['*']` 를 사용할 수 있습니다.
-* `allow_origin_regex` - 교차-출처 요청을 보낼 수 있는 출처를 정규표현식 문자열로 나타냅니다. `'https://.*\.example\.org'`.
-* `allow_methods` - 교차-출처 요청을 허용하는 HTTP 메소드의 리스트입니다. 기본값은 `['GET']` 입니다. `['*']` 을 사용하여 모든 표준 메소드들을 허용할 수 있습니다.
-* `allow_headers` - 교차-출처를 지원하는 HTTP 요청 헤더의 리스트입니다. 기본값은 `[]` 입니다. 모든 헤더들을 허용하기 위해 `['*']` 를 사용할 수 있습니다. `Accept`, `Accept-Language`, `Content-Language` 그리고 `Content-Type` 헤더는 CORS 요청시 언제나 허용됩니다.
-* `allow_credentials` - 교차-출처 요청시 쿠키 지원 여부를 설정합니다. 기본값은 `False` 입니다. 또한 해당 항목을 허용할 경우 `allow_origins` 는 `['*']` 로 설정할 수 없으며, 출처를 반드시 특정해야 합니다.
-* `expose_headers` - 브라우저에 접근할 수 있어야 하는 모든 응답 헤더를 가리킵니다. 기본값은 `[]` 입니다.
-* `max_age` - 브라우저가 CORS 응답을 캐시에 저장하는 최대 시간을 초 단위로 설정합니다. 기본값은 `600` 입니다.
+다음 인자들이 지원됩니다:
-미들웨어는 두가지 특정한 종류의 HTTP 요청에 응답합니다...
+* `allow_origins` - 교차-출처 요청을 보낼 수 있도록 허용해야 하는 출처의 리스트입니다. 예: `['https://example.org', 'https://www.example.org']`. 모든 출처를 허용하려면 `['*']`를 사용할 수 있습니다.
+* `allow_origin_regex` - 교차-출처 요청을 보낼 수 있도록 허용해야 하는 출처와 매칭할 정규표현식 문자열입니다. 예: `'https://.*\.example\.org'`.
+* `allow_methods` - 교차-출처 요청에 허용되어야 하는 HTTP 메서드의 리스트입니다. 기본값은 `['GET']`입니다. 모든 표준 메서드를 허용하려면 `['*']`를 사용할 수 있습니다.
+* `allow_headers` - 교차-출처 요청에 대해 지원되어야 하는 HTTP 요청 헤더의 리스트입니다. 기본값은 `[]`입니다. 모든 헤더를 허용하려면 `['*']`를 사용할 수 있습니다. `Accept`, `Accept-Language`, `Content-Language`, `Content-Type` 헤더는 단순 CORS 요청에 대해 항상 허용됩니다.
+* `allow_credentials` - 교차-출처 요청에 대해 쿠키를 지원해야 함을 나타냅니다. 기본값은 `False`입니다.
-### CORS 사전 요청
+ `allow_credentials`가 `True`로 설정된 경우 `allow_origins`, `allow_methods`, `allow_headers` 중 어느 것도 `['*']`로 설정할 수 없습니다. 모두 명시적으로 지정되어야 합니다.
-`Origin` 및 `Access-Control-Request-Method` 헤더와 함께 전송하는 모든 `OPTIONS` 요청입니다.
+* `expose_headers` - 브라우저에서 접근 가능해야 하는 모든 응답 헤더를 나타냅니다. 기본값은 `[]`입니다.
+* `max_age` - 브라우저가 CORS 응답을 캐시하는 최대 시간을 초 단위로 설정합니다. 기본값은 `600`입니다.
-이 경우 미들웨어는 들어오는 요청을 가로채 적절한 CORS 헤더와, 정보 제공을 위한 `200` 또는 `400` 응답으로 응답합니다.
+미들웨어는 두 가지 특정한 종류의 HTTP 요청에 응답합니다...
-### 단순한 요청
+### CORS 사전 요청 { #cors-preflight-requests }
-`Origin` 헤더를 가진 모든 요청. 이 경우 미들웨어는 요청을 정상적으로 전달하지만, 적절한 CORS 헤더를 응답에 포함시킵니다.
+`Origin` 및 `Access-Control-Request-Method` 헤더가 있는 모든 `OPTIONS` 요청입니다.
-## 더 많은 정보
+이 경우 미들웨어는 들어오는 요청을 가로채 적절한 CORS 헤더와 함께, 정보 제공 목적으로 `200` 또는 `400` 응답을 반환합니다.
-CORS에 대한 더 많은 정보를 알고싶다면, Mozilla CORS 문서를 참고하기 바랍니다.
+### 단순한 요청 { #simple-requests }
-/// note | 기술적 세부 사항
+`Origin` 헤더가 있는 모든 요청입니다. 이 경우 미들웨어는 요청을 정상적으로 통과시키지만, 응답에 적절한 CORS 헤더를 포함합니다.
-`from starlette.middleware.cors import CORSMiddleware` 역시 사용할 수 있습니다.
+## 더 많은 정보 { #more-info }
-**FastAPI**는 개발자인 당신의 편의를 위해 `fastapi.middleware` 에서 몇가지의 미들웨어를 제공합니다. 하지만 대부분의 미들웨어가 Stralette으로부터 직접 제공됩니다.
+CORS에 대한 더 많은 정보는 Mozilla CORS 문서를 참고하세요.
+
+/// note | 기술 세부사항
+
+`from starlette.middleware.cors import CORSMiddleware`도 사용할 수 있습니다.
+
+**FastAPI**는 개발자인 여러분의 편의를 위해 `fastapi.middleware`에 여러 미들웨어를 제공합니다. 하지만 사용 가능한 미들웨어 대부분은 Starlette에서 직접 제공됩니다.
///
diff --git a/docs/ko/docs/tutorial/debugging.md b/docs/ko/docs/tutorial/debugging.md
index e42f1ba88..ca20acff6 100644
--- a/docs/ko/docs/tutorial/debugging.md
+++ b/docs/ko/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# 디버깅
+# 디버깅 { #debugging }
예를 들면 Visual Studio Code 또는 PyCharm을 사용하여 편집기에서 디버거를 연결할 수 있습니다.
-## `uvicorn` 호출
+## `uvicorn` 호출 { #call-uvicorn }
-FastAPI 애플리케이션에서 `uvicorn`을 직접 임포트하여 실행합니다
+FastAPI 애플리케이션에서 `uvicorn`을 직접 임포트하여 실행합니다:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### `__name__ == "__main__"` 에 대하여
+### `__name__ == "__main__"` 에 대하여 { #about-name-main }
`__name__ == "__main__"`의 주요 목적은 다음과 같이 파일이 호출될 때 실행되는 일부 코드를 갖는 것입니다.
@@ -26,7 +26,7 @@ $ python myapp.py
from myapp import app
```
-#### 추가 세부사항
+#### 추가 세부사항 { #more-details }
파일 이름이 `myapp.py`라고 가정해 보겠습니다.
@@ -62,7 +62,7 @@ from myapp import app
# Some more code
```
-이 경우 `myapp.py` 내부의 자동 변수에는 값이 `"__main__"`인 변수 `__name__`이 없습니다.
+이 경우 `myapp.py` 내부의 자동 변수 `__name__`에는 값이 `"__main__"`이 들어가지 않습니다.
따라서 다음 행
@@ -74,11 +74,11 @@ from myapp import app
/// info | 정보
-자세한 내용은 공식 Python 문서를 확인하세요
+자세한 내용은 공식 Python 문서를 확인하세요.
///
-## 디버거로 코드 실행
+## 디버거로 코드 실행 { #run-your-code-with-your-debugger }
코드에서 직접 Uvicorn 서버를 실행하고 있기 때문에 디버거에서 직접 Python 프로그램(FastAPI 애플리케이션)을 호출할 수 있습니다.
@@ -101,7 +101,7 @@ from myapp import app
Pycharm을 사용하는 경우 다음을 수행할 수 있습니다
-* "Run" 메뉴를 엽니다
+* "Run" 메뉴를 엽니다.
* "Debug..." 옵션을 선택합니다.
* 그러면 상황에 맞는 메뉴가 나타납니다.
* 디버그할 파일을 선택합니다(이 경우 `main.py`).
diff --git a/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md
index 3e5cdcc8c..68bba669a 100644
--- a/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/ko/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -1,30 +1,30 @@
-# 의존성으로서의 클래스
+# 의존성으로서의 클래스 { #classes-as-dependencies }
-**의존성 주입** 시스템에 대해 자세히 살펴보기 전에 이전 예제를 업그레이드 해보겠습니다.
+**의존성 주입** 시스템에 대해 더 깊이 살펴보기 전에, 이전 예제를 업그레이드해 보겠습니다.
-## 이전 예제의 `딕셔너리`
+## 이전 예제의 `dict` { #a-dict-from-the-previous-example }
-이전 예제에서, 우리는 의존성(의존 가능한) 함수에서 `딕셔너리`객체를 반환하고 있었습니다:
+이전 예제에서는 의존성("dependable")에서 `dict`를 반환하고 있었습니다:
-{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}
-우리는 *경로 작동 함수*의 매개변수 `commons`에서 `딕셔너리` 객체를 얻습니다.
+하지만 그러면 *경로 처리 함수*의 매개변수 `commons`에서 `dict`를 받게 됩니다.
-그리고 우리는 에디터들이 `딕셔너리` 객체의 키나 밸류의 자료형을 알 수 없기 때문에 자동 완성과 같은 기능을 제공해 줄 수 없다는 것을 알고 있습니다.
+그리고 에디터는 `dict`의 키와 값 타입을 알 수 없기 때문에 `dict`에 대해서는 (완성 기능 같은) 많은 지원을 제공할 수 없다는 것을 알고 있습니다.
-더 나은 방법이 있을 것 같습니다...
+더 나은 방법이 있습니다...
-## 의존성으로 사용 가능한 것
+## 의존성이 되기 위한 조건 { #what-makes-a-dependency }
-지금까지 함수로 선언된 의존성을 봐왔습니다.
+지금까지는 함수로 선언된 의존성을 봤습니다.
-아마도 더 일반적이기는 하겠지만 의존성을 선언하는 유일한 방법은 아닙니다.
+하지만 그것만이 의존성을 선언하는 유일한 방법은 아닙니다(아마도 더 일반적이긴 하겠지만요).
-핵심 요소는 의존성이 "호출 가능"해야 한다는 것입니다
+핵심 요소는 의존성이 "호출 가능(callable)"해야 한다는 것입니다.
-파이썬에서의 "**호출 가능**"은 파이썬이 함수처럼 "호출"할 수 있는 모든 것입니다.
+파이썬에서 "**호출 가능(callable)**"이란 파이썬이 함수처럼 "호출"할 수 있는 모든 것입니다.
-따라서, 만약 당신이 `something`(함수가 아닐 수도 있음) 객체를 가지고 있고,
+따라서 `something`(함수가 _아닐_ 수도 있습니다)이라는 객체가 있고, 다음처럼 "호출"(실행)할 수 있다면:
```Python
something()
@@ -36,11 +36,11 @@ something()
something(some_argument, some_keyword_argument="foo")
```
-상기와 같은 방식으로 "호출(실행)" 할 수 있다면 "호출 가능"이 됩니다.
+그것은 "호출 가능(callable)"입니다.
-## 의존성으로서의 클래스
+## 의존성으로서의 클래스 { #classes-as-dependencies_1 }
-파이썬 클래스의 인스턴스를 생성하기 위해 사용하는 것과 동일한 문법을 사용한다는 걸 알 수 있습니다.
+파이썬 클래스의 인스턴스를 만들 때도 같은 문법을 사용한다는 것을 알 수 있을 겁니다.
예를 들어:
@@ -53,125 +53,236 @@ class Cat:
fluffy = Cat(name="Mr Fluffy")
```
-이 경우에 `fluffy`는 클래스 `Cat`의 인스턴스입니다. 그리고 우리는 `fluffy`를 만들기 위해서 `Cat`을 "호출"했습니다.
+이 경우 `fluffy`는 클래스 `Cat`의 인스턴스입니다.
-따라서, 파이썬 클래스는 **호출 가능**합니다.
+그리고 `fluffy`를 만들기 위해 `Cat`을 "호출"하고 있습니다.
-그래서 **FastAPI**에서는 파이썬 클래스를 의존성으로 사용할 수 있습니다.
+따라서 파이썬 클래스도 **호출 가능(callable)**합니다.
-FastAPI가 실질적으로 확인하는 것은 "호출 가능성"(함수, 클래스 또는 다른 모든 것)과 정의된 매개변수들입니다.
+그러면 **FastAPI**에서는 파이썬 클래스를 의존성으로 사용할 수 있습니다.
-"호출 가능"한 것을 의존성으로서 **FastAPI**에 전달하면, 그 "호출 가능"한 것의 매개변수들을 분석한 후 이를 *경로 작동 함수*를 위한 매개변수와 동일한 방식으로 처리합니다. 하위-의존성 또한 같은 방식으로 처리합니다.
+FastAPI가 실제로 확인하는 것은 그것이 "호출 가능(callable)"(함수, 클래스, 또는 다른 무엇이든)한지와 정의된 매개변수들입니다.
-매개변수가 없는 "호출 가능"한 것 역시 매개변수가 없는 *경로 작동 함수*와 동일한 방식으로 적용됩니다.
+**FastAPI**에서 "호출 가능(callable)"한 것을 의존성으로 넘기면, 그 "호출 가능(callable)"한 것의 매개변수들을 분석하고 *경로 처리 함수*의 매개변수와 동일한 방식으로 처리합니다. 하위 의존성도 포함해서요.
-그래서, 우리는 위 예제에서의 `common_paramenters` 의존성을 클래스 `CommonQueryParams`로 바꿀 수 있습니다.
+이것은 매개변수가 전혀 없는 callable에도 적용됩니다. 매개변수가 없는 *경로 처리 함수*에 적용되는 것과 동일합니다.
-{* ../../docs_src/dependencies/tutorial002.py hl[11:15] *}
+그러면 위의 의존성("dependable") `common_parameters`를 클래스 `CommonQueryParams`로 바꿀 수 있습니다:
-클래스의 인스턴스를 생성하는 데 사용되는 `__init__` 메서드에 주목하기 바랍니다:
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[11:15] *}
-{* ../../docs_src/dependencies/tutorial002.py hl[12] *}
+클래스의 인스턴스를 만들 때 사용하는 `__init__` 메서드에 주목하세요:
-...이전 `common_parameters`와 동일한 매개변수를 가집니다:
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}
-{* ../../docs_src/dependencies/tutorial001.py hl[9] *}
+...이전의 `common_parameters`와 동일한 매개변수를 가지고 있습니다:
-이 매개변수들은 **FastAPI**가 의존성을 "해결"하기 위해 사용할 것입니다
+{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}
-함수와 클래스 두 가지 방식 모두, 아래 요소를 갖습니다:
+이 매개변수들이 **FastAPI**가 의존성을 "해결"하는 데 사용할 것들입니다.
-* `문자열`이면서 선택사항인 쿼리 매개변수 `q`.
-* 기본값이 `0`이면서 `정수형`인 쿼리 매개변수 `skip`
-* 기본값이 `100`이면서 `정수형`인 쿼리 매개변수 `limit`
+두 경우 모두 다음을 갖게 됩니다:
-두 가지 방식 모두, 데이터는 변환, 검증되고 OpenAPI 스키마에 문서화됩니다.
+* `str`인 선택적 쿼리 매개변수 `q`.
+* 기본값이 `0`인 `int` 쿼리 매개변수 `skip`.
+* 기본값이 `100`인 `int` 쿼리 매개변수 `limit`.
-## 사용해봅시다!
+두 경우 모두 데이터는 변환되고, 검증되며, OpenAPI 스키마에 문서화되는 등 여러 처리가 적용됩니다.
-이제 아래의 클래스를 이용해서 의존성을 정의할 수 있습니다.
+## 사용하기 { #use-it }
-{* ../../docs_src/dependencies/tutorial002.py hl[19] *}
+이제 이 클래스를 사용해 의존성을 선언할 수 있습니다.
-**FastAPI**는 `CommonQueryParams` 클래스를 호출합니다. 이것은 해당 클래스의 "인스턴스"를 생성하고 그 인스턴스는 함수의 매개변수 `commons`로 전달됩니다.
+{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}
-## 타입 힌팅 vs `Depends`
+**FastAPI**는 `CommonQueryParams` 클래스를 호출합니다. 그러면 해당 클래스의 "인스턴스"가 생성되고, 그 인스턴스가 함수의 매개변수 `commons`로 전달됩니다.
-위 코드에서 `CommonQueryParams`를 두 번 작성한 방식에 주목하십시오:
+## 타입 어노테이션 vs `Depends` { #type-annotation-vs-depends }
+
+위 코드에서 `CommonQueryParams`를 두 번 작성하는 방식에 주목하세요:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
-마지막 `CommonQueryParams` 변수를 보면:
+////
+
+마지막 `CommonQueryParams`는, 다음에서:
```Python
-... = Depends(CommonQueryParams)
+... Depends(CommonQueryParams)
```
-... **FastAPI**가 실제로 어떤 것이 의존성인지 알기 위해서 사용하는 방법입니다.
-FastAPI는 선언된 매개변수들을 추출할 것이고 실제로 이 변수들을 호출할 것입니다.
+...**FastAPI**가 실제로 무엇이 의존성인지 알기 위해 사용하는 것입니다.
+
+FastAPI는 여기에서 선언된 매개변수들을 추출하고, 실제로 이것을 호출합니다.
---
-이 경우에, 첫번째 `CommonQueryParams` 변수를 보면:
+이 경우 첫 번째 `CommonQueryParams`는 다음에서:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, ...
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons: CommonQueryParams ...
```
-... **FastAPI**는 `CommonQueryParams` 변수에 어떠한 특별한 의미도 부여하지 않습니다. FastAPI는 이 변수를 데이터 변환, 검증 등에 활용하지 않습니다. (활용하려면 `= Depends(CommonQueryParams)`를 사용해야 합니다.)
+////
+
+...**FastAPI**에 특별한 의미가 없습니다. FastAPI는 이를 데이터 변환, 검증 등에 사용하지 않습니다(그런 용도로는 `Depends(CommonQueryParams)`를 사용하고 있기 때문입니다).
+
+실제로는 이렇게만 작성해도 됩니다:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[Any, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
-사실 아래와 같이 작성해도 무관합니다:
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons = Depends(CommonQueryParams)
```
-..전체적인 코드는 아래와 같습니다:
+////
-{* ../../docs_src/dependencies/tutorial003.py hl[19] *}
+...다음과 같이요:
-그러나 자료형을 선언하면 에디터가 매개변수 `commons`로 전달될 것이 무엇인지 알게 되고, 이를 통해 코드 완성, 자료형 확인 등에 도움이 될 수 있으므로 권장됩니다.
+{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}
-
+하지만 타입을 선언하는 것을 권장합니다. 그러면 에디터가 매개변수 `commons`에 무엇이 전달되는지 알 수 있고, 코드 완성, 타입 체크 등에서 도움을 받을 수 있습니다:
-## 코드 단축
+
-그러나 여기 `CommonQueryParams`를 두 번이나 작성하는, 코드 반복이 있다는 것을 알 수 있습니다:
+## 단축 { #shortcut }
+
+하지만 `CommonQueryParams`를 두 번 작성하는 코드 반복이 있다는 것을 볼 수 있습니다:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
-**FastAPI**는 *특히* 의존성이 **FastAPI**가 클래스 자체의 인스턴스를 생성하기 위해 "호출"하는 클래스인 경우, 조금 더 쉬운 방법을 제공합니다.
+////
+
+**FastAPI**는 이런 경우를 위한 단축 방법을 제공합니다. 이때 의존성은 *특히* **FastAPI**가 "호출"해서 클래스 자체의 인스턴스를 만들도록 하는 클래스입니다.
-이러한 특정한 경우에는 아래처럼 사용할 수 있습니다:
+이 특정한 경우에는 다음과 같이 할 수 있습니다:
-이렇게 쓰는 것 대신:
+다음처럼 작성하는 대신:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons: CommonQueryParams = Depends(CommonQueryParams)
```
-...이렇게 쓸 수 있습니다.:
+////
+
+...이렇게 작성합니다:
+
+//// tab | Python 3.9+
+
+```Python
+commons: Annotated[CommonQueryParams, Depends()]
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | 팁
+
+가능하다면 `Annotated` 버전을 사용하는 것을 권장합니다.
+
+///
```Python
commons: CommonQueryParams = Depends()
```
-의존성을 매개변수의 타입으로 선언하는 경우 `Depends(CommonQueryParams)`처럼 클래스 이름 전체를 *다시* 작성하는 대신, 매개변수를 넣지 않은 `Depends()`의 형태로 사용할 수 있습니다.
+////
+
+의존성을 매개변수의 타입으로 선언하고, `Depends(CommonQueryParams)` 안에 클래스 전체를 *다시* 작성하는 대신 매개변수 없이 `Depends()`를 사용합니다.
-아래에 같은 예제가 있습니다:
+그러면 같은 예제는 다음처럼 보일 겁니다:
-{* ../../docs_src/dependencies/tutorial004.py hl[19] *}
+{* ../../docs_src/dependencies/tutorial004_an_py310.py hl[19] *}
-...이렇게 코드를 단축하여도 **FastAPI**는 무엇을 해야하는지 알고 있습니다.
+...그리고 **FastAPI**는 무엇을 해야 하는지 알게 됩니다.
/// tip | 팁
-만약 이것이 도움이 되기보다 더 헷갈리게 만든다면, 잊어버리십시오. 이것이 반드시 필요한 것은 아닙니다.
+도움이 되기보다 더 헷갈린다면, 무시하세요. 이건 *필수*가 아닙니다.
-이것은 단지 손쉬운 방법일 뿐입니다. 왜냐하면 **FastAPI**는 코드 반복을 최소화할 수 있는 방법을 고민하기 때문입니다.
+그저 단축 방법일 뿐입니다. **FastAPI**는 코드 반복을 최소화하도록 도와주는 것을 중요하게 생각하기 때문입니다.
///
diff --git a/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 4a3854cef..39c78c078 100644
--- a/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/ko/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -1,4 +1,4 @@
-# 경로 작동 데코레이터에서의 의존성
+# 경로 작동 데코레이터에서의 의존성 { #dependencies-in-path-operation-decorators }
몇몇 경우에는, *경로 작동 함수* 안에서 의존성의 반환 값이 필요하지 않습니다.
@@ -8,7 +8,7 @@
그런 경우에, `Depends`를 사용하여 *경로 작동 함수*의 매개변수로 선언하는 것보다 *경로 작동 데코레이터*에 `dependencies`의 `list`를 추가할 수 있습니다.
-## *경로 작동 데코레이터*에 `dependencies` 추가하기
+## *경로 작동 데코레이터*에 `dependencies` 추가하기 { #add-dependencies-to-the-path-operation-decorator }
*경로 작동 데코레이터*는 `dependencies`라는 선택적인 인자를 받습니다.
@@ -22,7 +22,7 @@
일부 편집기에서는 사용되지 않는 함수 매개변수를 검사하고 오류로 표시합니다.
-*경로 작동 데코레이터*에서 `dependencies`를 사용하면 편집기/도구 오류를 피하며 실행되도록 할 수 있습니다.
+*경로 작동 데코레이터*에서 이러한 `dependencies`를 사용하면 편집기/도구 오류를 피하면서도 실행되도록 할 수 있습니다.
또한 코드에서 사용되지 않는 매개변수를 보고 불필요하다고 생각할 수 있는 새로운 개발자의 혼란을 방지하는데 도움이 될 수 있습니다.
@@ -36,23 +36,23 @@
///
-## 의존성 오류와 값 반환하기
+## 의존성 오류와 값 반환하기 { #dependencies-errors-and-return-values }
평소에 사용하던대로 같은 의존성 *함수*를 사용할 수 있습니다.
-### 의존성 요구사항
+### 의존성 요구사항 { #dependency-requirements }
(헤더같은) 요청 요구사항이나 하위-의존성을 선언할 수 있습니다:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### 오류 발생시키기
+### 오류 발생시키기 { #raise-exceptions }
-다음 의존성은 기존 의존성과 동일하게 예외를 `raise`를 일으킬 수 있습니다:
+다음 의존성은 기존 의존성과 동일하게 예외를 `raise`할 수 있습니다:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### 값 반환하기
+### 값 반환하기 { #return-values }
값을 반환하거나, 그러지 않을 수 있으며 값은 사용되지 않습니다.
@@ -60,10 +60,10 @@
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## *경로 작동* 모음에 대한 의존성
+## *경로 작동* 모음에 대한 의존성 { #dependencies-for-a-group-of-path-operations }
나중에 여러 파일을 가지고 있을 수 있는 더 큰 애플리케이션을 구조화하는 법([더 큰 애플리케이션 - 여러 파일들](../../tutorial/bigger-applications.md){.internal-link target=_blank})을 읽을 때, *경로 작동* 모음에 대한 단일 `dependencies` 매개변수를 선언하는 법에 대해서 배우게 될 것입니다.
-## 전역 의존성
+## 전역 의존성 { #global-dependencies }
다음으로 각 *경로 작동*에 적용되도록 `FastAPI` 애플리케이션 전체에 의존성을 추가하는 법을 볼 것입니다.
diff --git a/docs/ko/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ko/docs/tutorial/dependencies/dependencies-with-yield.md
index ff174937d..9bf6c0693 100644
--- a/docs/ko/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/ko/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,6 +1,6 @@
-# yield를 사용하는 의존성
+# `yield`를 사용하는 의존성 { #dependencies-with-yield }
-FastAPI는 작업 완료 후 추가 단계를 수행하는 의존성을 지원합니다.
+FastAPI는 작업 완료 후 추가 단계를 수행하는 의존성을 지원합니다.
이를 구현하려면 `return` 대신 `yield`를 사용하고, 추가로 실행할 단계 (코드)를 그 뒤에 작성하세요.
@@ -23,21 +23,21 @@ FastAPI는
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 형식이어야 합니다. |
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 형식이어야 합니다. |
-## 라이선스 식별자
+## 라이선스 식별자 { #license-identifier }
-OpenAPI 3.1.0 및 FastAPI 0.99.0부터 `license_info`에 `identifier`를 URL 대신 설정할 수 있습니다.
+OpenAPI 3.1.0 및 FastAPI 0.99.0부터 `license_info`에 `url` 대신 `identifier`를 설정할 수도 있습니다.
예:
-{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
-## 태그에 대한 메타데이터
+## 태그에 대한 메타데이터 { #metadata-for-tags }
-`openapi_tags` 매개변수를 사용하여 경로 작동을 그룹화하는 데 사용되는 태그에 추가 메타데이터를 추가할 수 있습니다.
+`openapi_tags` 매개변수를 사용하여 경로 처리을 그룹화하는 데 사용되는 여러 태그에 추가 메타데이터를 추가할 수도 있습니다.
-리스트는 각 태그에 대해 하나의 딕셔너리를 포함해야 합니다.
+리스트는 각 태그에 대해 하나의 딕셔너리를 포함합니다.
각 딕셔너리에는 다음이 포함될 수 있습니다:
-* `name` (**필수**): `tags` 매개변수에서 *경로 작동*과 `APIRouter`에 사용된 태그 이름과 동일한 `str`입니다.
-* `description`: 태그에 대한 간단한 설명을 담은 `str`입니다. 마크다운을 사용할 수 있으며 문서 UI에 표시됩니다.
+* `name` (**필수**): *경로 처리* 및 `APIRouter`의 `tags` 매개변수에서 사용하는 태그 이름과 동일한 `str`입니다.
+* `description`: 태그에 대한 간단한 설명을 담은 `str`입니다. 마크다운을 포함할 수 있으며 문서 UI에 표시됩니다.
* `externalDocs`: 외부 문서를 설명하는 `dict`이며:
* `description`: 외부 문서에 대한 간단한 설명을 담은 `str`입니다.
* `url` (**필수**): 외부 문서의 URL을 담은 `str`입니다.
-### 태그에 대한 메타데이터 생성
+### 태그에 대한 메타데이터 생성 { #create-metadata-for-tags }
-`users` 및 `items`에 대한 태그 예시와 함께 메타데이터를 생성하고 이를 `openapi_tags` 매개변수로 전달해 보겠습니다:
+`users` 및 `items`에 대한 태그 예시로 시도해 보겠습니다.
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+태그에 대한 메타데이터를 생성하고 이를 `openapi_tags` 매개변수로 전달하세요:
-설명 안에 마크다운을 사용할 수 있습니다. 예를 들어 "login"은 굵게(**login**) 표시되고, "fancy"는 기울임꼴(_fancy_)로 표시됩니다.
+{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}
-/// tip
+설명 안에 마크다운을 사용할 수 있다는 점에 유의하세요. 예를 들어 "login"은 굵게(**login**) 표시되고, "fancy"는 기울임꼴(_fancy_)로 표시됩니다.
+
+/// tip | 팁
사용 중인 모든 태그에 메타데이터를 추가할 필요는 없습니다.
///
-### 태그 사용
+### 태그 사용 { #use-your-tags }
-`tags` 매개변수를 *경로 작동* 및 `APIRouter`와 함께 사용하여 태그에 할당할 수 있습니다:
+`tags` 매개변수를 *경로 처리* (및 `APIRouter`)와 함께 사용하여 이를 서로 다른 태그에 할당하세요:
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
-/// info
+/// info | 정보
-태그에 대한 자세한 내용은 [경로 작동 구성](path-operation-configuration.md#tags){.internal-link target=_blank}에서 읽어보세요.
+태그에 대한 자세한 내용은 [경로 처리 구성](path-operation-configuration.md#tags){.internal-link target=_blank}에서 읽어보세요.
///
-### 문서 확인
+### 문서 확인 { #check-the-docs }
이제 문서를 확인하면 모든 추가 메타데이터가 표시됩니다:
-### 태그 순서
+### 태그 순서 { #order-of-tags }
-각 태그 메타데이터 딕셔너리의 순서는 문서 UI에 표시되는 순서를 정의합니다.
+각 태그 메타데이터 딕셔너리의 순서는 문서 UI에 표시되는 순서도 정의합니다.
-예를 들어, 알파벳 순서상 `users`는 `items` 뒤에 오지만, 우리는 `users` 메타데이터를 리스트의 첫 번째 딕셔너리로 추가했기 때문에 먼저 표시됩니다.
+예를 들어, 알파벳 순서상 `users`는 `items` 뒤에 오지만, 우리는 해당 메타데이터를 리스트의 첫 번째 딕셔너리로 추가했기 때문에 먼저 표시됩니다.
-## OpenAPI URL
+## OpenAPI URL { #openapi-url }
-OpenAPI 구조는 기본적으로 `/openapi.json`에서 제공됩니다.
+기본적으로 OpenAPI 스키마는 `/openapi.json`에서 제공됩니다.
-`openapi_url` 매개변수를 통해 이를 설정할 수 있습니다.
+하지만 `openapi_url` 매개변수로 이를 설정할 수 있습니다.
-예를 들어, 이를 `/api/v1/openapi.json`에 제공하도록 설정하려면:
+예를 들어, 이를 `/api/v1/openapi.json`에서 제공하도록 설정하려면:
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}
-OpenAPI 구조를 완전히 비활성화하려면 `openapi_url=None`으로 설정할 수 있으며, 이를 사용하여 문서화 사용자 인터페이스도 비활성화됩니다.
+OpenAPI 스키마를 완전히 비활성화하려면 `openapi_url=None`으로 설정할 수 있으며, 이를 사용하여 문서화 사용자 인터페이스도 비활성화됩니다.
-## 문서화 URL
+## 문서화 URL { #docs-urls }
포함된 두 가지 문서화 사용자 인터페이스를 설정할 수 있습니다:
@@ -115,4 +117,4 @@ OpenAPI 구조를 완전히 비활성화하려면 `openapi_url=None`으로 설
예를 들어, Swagger UI를 `/documentation`에서 제공하고 ReDoc을 비활성화하려면:
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/ko/docs/tutorial/middleware.md b/docs/ko/docs/tutorial/middleware.md
index 3cd752a0e..c213c5074 100644
--- a/docs/ko/docs/tutorial/middleware.md
+++ b/docs/ko/docs/tutorial/middleware.md
@@ -1,66 +1,95 @@
-# 미들웨어
+# 미들웨어 { #middleware }
미들웨어를 **FastAPI** 응용 프로그램에 추가할 수 있습니다.
-"미들웨어"는 특정 *경로 작동*에 의해 처리되기 전, 모든 **요청**에 대해서 동작하는 함수입니다. 또한 모든 **응답**이 반환되기 전에도 동일하게 동작합니다.
+"미들웨어"는 특정 *경로 처리*에 의해 처리되기 전, 모든 **요청**에 대해서 동작하는 함수입니다. 또한 모든 **응답**이 반환되기 전에도 동일하게 동작합니다.
-* 미들웨어는 응용 프로그램으로 오는 **요청**를 가져옵니다.
-* **요청** 또는 다른 필요한 코드를 실행 시킬 수 있습니다.
-* **요청**을 응용 프로그램의 *경로 작동*으로 전달하여 처리합니다.
-* 애플리케이션의 *경로 작업*에서 생성한 **응답**를 받습니다.
-* **응답** 또는 다른 필요한 코드를 실행시키는 동작을 할 수 있습니다.
-* **응답**를 반환합니다.
+* 미들웨어는 응용 프로그램으로 오는 각 **요청**을 가져옵니다.
+* 그런 다음 해당 **요청**에 대해 무언가를 하거나 필요한 코드를 실행할 수 있습니다.
+* 그런 다음 **요청**을 나머지 애플리케이션(어떤 *경로 처리*가)을 통해 처리되도록 전달합니다.
+* 그런 다음 애플리케이션(어떤 *경로 처리*가)이 생성한 **응답**을 가져옵니다.
+* 그런 다음 해당 **응답**에 대해 무언가를 하거나 필요한 코드를 실행할 수 있습니다.
+* 그런 다음 **응답**을 반환합니다.
/// note | 기술 세부사항
-만약 `yield`를 사용한 의존성을 가지고 있다면, 미들웨어가 실행되고 난 후에 exit이 실행됩니다.
+`yield`를 사용하는 의존성이 있다면, exit 코드는 미들웨어 *후에* 실행됩니다.
-만약 (나중에 문서에서 다룰) 백그라운드 작업이 있다면, 모든 미들웨어가 실행되고 *난 후에* 실행됩니다.
+백그라운드 작업(뒤에서 보게 될 [Background Tasks](background-tasks.md){.internal-link target=_blank} 섹션에서 다룹니다)이 있다면, 모든 미들웨어 *후에* 실행됩니다.
///
-## 미들웨어 만들기
+## 미들웨어 만들기 { #create-a-middleware }
-미들웨어를 작성하기 위해서 함수 상단에 `@app.middleware("http")` 데코레이터를 사용할 수 있습니다.
+미들웨어를 만들기 위해 함수 상단에 데코레이터 `@app.middleware("http")`를 사용합니다.
-미들웨어 함수는 다음 항목들을 받습니다:
+미들웨어 함수는 다음을 받습니다:
* `request`.
* `request`를 매개변수로 받는 `call_next` 함수.
- * 이 함수는 `request`를 해당하는 *경로 작업*으로 전달합니다.
- * 그런 다음, *경로 작업*에 의해 생성된 `response` 를 반환합니다.
-* `response`를 반환하기 전에 추가로 `response`를 수정할 수 있습니다.
+ * 이 함수는 `request`를 해당하는 *경로 처리*로 전달합니다.
+ * 그런 다음 해당 *경로 처리*가 생성한 `response`를 반환합니다.
+* 그런 다음 반환하기 전에 `response`를 추가로 수정할 수 있습니다.
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip | 팁
-사용자 정의 헤더는 'X-' 접두사를 사용하여 추가할 수 있습니다.
+사용자 정의 독점 헤더는 `X-` 접두사를 사용하여 추가할 수 있다는 점을 기억하세요.
-그러나 만약 클라이언트의 브라우저에서 볼 수 있는 사용자 정의 헤더를 가지고 있다면, 그것들을 CORS 설정([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank})에 Starlette CORS 문서에 명시된 `expose_headers` 매개변수를 이용하여 헤더들을 추가하여야합니다.
+하지만 브라우저에서 클라이언트가 볼 수 있게 하려는 사용자 정의 헤더가 있다면, Starlette의 CORS 문서에 문서화된 `expose_headers` 매개변수를 사용해 CORS 설정([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank})에 추가해야 합니다.
///
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
+
+`from starlette.requests import Request`를 사용할 수도 있습니다.
+
+**FastAPI**는 개발자인 여러분의 편의를 위해 이를 제공합니다. 하지만 이는 Starlette에서 직접 가져온 것입니다.
+
+///
+
+### `response`의 전과 후 { #before-and-after-the-response }
+
+어떤 *경로 처리*가 받기 전에, `request`와 함께 실행될 코드를 추가할 수 있습니다.
+
+또한 `response`가 생성된 후, 반환하기 전에 코드를 추가할 수도 있습니다.
-`from starlette.requests import request`를 사용할 수도 있습니다.
+예를 들어, 요청을 처리하고 응답을 생성하는 데 걸린 시간을 초 단위로 담는 사용자 정의 헤더 `X-Process-Time`을 추가할 수 있습니다:
-**FastAPI**는 개발자에게 편의를 위해 이를 제공합니다. 그러나 Starlette에서 직접 파생되었습니다.
+{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *}
+
+/// tip | 팁
+
+여기서는 이러한 사용 사례에서 더 정확할 수 있기 때문에 `time.time()` 대신 `time.perf_counter()`를 사용합니다. 🤓
///
-### `response`의 전과 후
+## 여러 미들웨어 실행 순서 { #multiple-middleware-execution-order }
+
+`@app.middleware()` 데코레이터 또는 `app.add_middleware()` 메서드를 사용해 여러 미들웨어를 추가하면, 새로 추가된 각 미들웨어가 애플리케이션을 감싸 스택을 형성합니다. 마지막에 추가된 미들웨어가 *가장 바깥쪽*이고, 처음에 추가된 미들웨어가 *가장 안쪽*입니다.
+
+요청 경로에서는 *가장 바깥쪽* 미들웨어가 먼저 실행됩니다.
+
+응답 경로에서는 마지막에 실행됩니다.
+
+예를 들어:
+
+```Python
+app.add_middleware(MiddlewareA)
+app.add_middleware(MiddlewareB)
+```
-*경로 작동*을 받기 전 `request`와 함께 작동할 수 있는 코드를 추가할 수 있습니다.
+이 경우 실행 순서는 다음과 같습니다:
-그리고 `response` 또한 생성된 후 반환되기 전에 코드를 추가 할 수 있습니다.
+* **요청**: MiddlewareB → MiddlewareA → route
-예를 들어, 요청을 수행하고 응답을 생성하는데 까지 걸린 시간 값을 가지고 있는 `X-Process-Time` 같은 사용자 정의 헤더를 추가할 수 있습니다.
+* **응답**: route → MiddlewareA → MiddlewareB
-{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+이러한 스태킹 동작은 미들웨어가 예측 가능하고 제어 가능한 순서로 실행되도록 보장합니다.
-## 다른 미들웨어
+## 다른 미들웨어 { #other-middlewares }
-미들웨어에 대한 더 많은 정보는 [숙련된 사용자 안내서: 향상된 미들웨어](../advanced/middleware.md){.internal-link target=\_blank}에서 확인할 수 있습니다.
+다른 미들웨어에 대한 더 많은 정보는 나중에 [숙련된 사용자 안내서: 향상된 미들웨어](../advanced/middleware.md){.internal-link target=_blank}에서 확인할 수 있습니다.
-다음 부분에서 미들웨어와 함께 CORS를 어떻게 다루는지에 대해 확인할 것입니다.
+다음 섹션에서 미들웨어로 CORS를 처리하는 방법을 보게 될 것입니다.
diff --git a/docs/ko/docs/tutorial/path-operation-configuration.md b/docs/ko/docs/tutorial/path-operation-configuration.md
index 81914182a..b8a87667a 100644
--- a/docs/ko/docs/tutorial/path-operation-configuration.md
+++ b/docs/ko/docs/tutorial/path-operation-configuration.md
@@ -1,97 +1,107 @@
-# 경로 작동 설정
+# 경로 처리 설정 { #path-operation-configuration }
-*경로 작동 데코레이터*를 설정하기 위해서 전달할수 있는 몇 가지 매개변수가 있습니다.
+*경로 처리 데코레이터*를 설정하기 위해 전달할 수 있는 몇 가지 매개변수가 있습니다.
/// warning | 경고
-아래 매개변수들은 *경로 작동 함수*가 아닌 *경로 작동 데코레이터*에 직접 전달된다는 사실을 기억하십시오.
+아래 매개변수들은 *경로 처리 함수*가 아닌 *경로 처리 데코레이터*에 직접 전달된다는 사실을 기억하세요.
///
-## 응답 상태 코드
+## 응답 상태 코드 { #response-status-code }
-*경로 작동*의 응답에 사용될 (HTTP) `status_code`를 정의할수 있습니다.
+*경로 처리*의 응답에 사용될 (HTTP) `status_code`를 정의할 수 있습니다.
-`404`와 같은 `int`형 코드를 직접 전달할수 있습니다.
+`404`와 같은 `int`형 코드를 직접 전달할 수 있습니다.
-하지만 각 코드의 의미를 모른다면, `status`에 있는 단축 상수들을 사용할수 있습니다:
+하지만 각 숫자 코드가 무엇을 의미하는지 기억하지 못한다면, `status`에 있는 단축 상수들을 사용할 수 있습니다:
-{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
+{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
-각 상태 코드들은 응답에 사용되며, OpenAPI 스키마에 추가됩니다.
+해당 상태 코드는 응답에 사용되며, OpenAPI 스키마에 추가됩니다.
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
다음과 같이 임포트하셔도 좋습니다. `from starlette import status`.
-**FastAPI**는 개발자 여러분의 편의를 위해서 `starlette.status`와 동일한 `fastapi.status`를 제공합니다. 하지만 Starlette에서 직접 온 것입니다.
+**FastAPI**는 개발자 여러분의 편의를 위해 `starlette.status`와 동일한 `fastapi.status`를 제공합니다. 하지만 이는 Starlette에서 직접 온 것입니다.
///
-## 태그
+## 태그 { #tags }
-(보통 단일 `str`인) `str`로 구성된 `list`와 함께 매개변수 `tags`를 전달하여, `경로 작동`에 태그를 추가할 수 있습니다:
+(보통 단일 `str`인) `str`로 구성된 `list`와 함께 매개변수 `tags`를 전달하여, *경로 처리*에 태그를 추가할 수 있습니다:
-{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
+{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
전달된 태그들은 OpenAPI의 스키마에 추가되며, 자동 문서 인터페이스에서 사용됩니다:
-## 요약과 기술
+### Enum을 사용한 태그 { #tags-with-enums }
+
+큰 애플리케이션이 있다면, **여러 태그**가 쌓이게 될 수 있고, 관련된 *경로 처리*에 항상 **같은 태그**를 사용하는지 확인하고 싶을 것입니다.
+
+이런 경우에는 태그를 `Enum`에 저장하는 것이 합리적일 수 있습니다.
+
+**FastAPI**는 일반 문자열과 동일한 방식으로 이를 지원합니다:
+
+{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
+
+## 요약과 설명 { #summary-and-description }
`summary`와 `description`을 추가할 수 있습니다:
-{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
+{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
-## 독스트링으로 만든 기술
+## 독스트링으로 만든 설명 { #description-from-docstring }
-설명은 보통 길어지고 여러 줄에 걸쳐있기 때문에, *경로 작동* 기술을 함수 독스트링 에 선언할 수 있습니다, 이를 **FastAPI**가 독스트링으로부터 읽습니다.
+설명은 보통 길어지고 여러 줄에 걸쳐있기 때문에, *경로 처리* 설명을 함수 docstring에 선언할 수 있으며, **FastAPI**는 그곳에서 이를 읽습니다.
-마크다운 문법으로 독스트링을 작성할 수 있습니다, 작성된 마크다운 형식의 독스트링은 (마크다운의 들여쓰기를 고려하여) 올바르게 화면에 출력됩니다.
+독스트링에는 Markdown을 작성할 수 있으며, (독스트링의 들여쓰기를 고려하여) 올바르게 해석되고 표시됩니다.
-{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
+{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
이는 대화형 문서에서 사용됩니다:
-## 응답 기술
+## 응답 설명 { #response-description }
`response_description` 매개변수로 응답에 관한 설명을 명시할 수 있습니다:
-{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
+{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *}
/// info | 정보
-`response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 작동*을 지칭합니다.
+`response_description`은 구체적으로 응답을 지칭하며, `description`은 일반적인 *경로 처리*를 지칭합니다.
///
/// check | 확인
-OpenAPI는 각 *경로 작동*이 응답에 관한 설명을 요구할 것을 명시합니다.
+OpenAPI는 각 *경로 처리*가 응답에 관한 설명을 요구할 것을 명시합니다.
-따라서, 응답에 관한 설명이 없을경우, **FastAPI**가 자동으로 "성공 응답" 중 하나를 생성합니다.
+따라서, 응답에 관한 설명을 제공하지 않으면, **FastAPI**가 "Successful response" 중 하나를 자동으로 생성합니다.
///
-## 단일 *경로 작동* 지원중단
+## *경로 처리* 지원중단하기 { #deprecate-a-path-operation }
-단일 *경로 작동*을 없애지 않고 지원중단을 해야한다면, `deprecated` 매개변수를 전달하면 됩니다.
+*경로 처리*를 제거하지 않고 deprecated로 표시해야 한다면, `deprecated` 매개변수를 전달하면 됩니다:
-{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
+{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
-대화형 문서에 지원중단이라고 표시됩니다.
+대화형 문서에서 지원중단으로 명확하게 표시됩니다:
-지원중단된 경우와 지원중단 되지 않은 경우에 대한 *경로 작동*이 어떻게 보이는 지 확인하십시오.
+지원중단된 *경로 처리*와 지원중단되지 않은 *경로 처리*가 어떻게 보이는지 확인해 보세요:
-## 정리
+## 정리 { #recap }
-*경로 작동 데코레이터*에 매개변수(들)를 전달함으로 *경로 작동*을 설정하고 메타데이터를 추가할수 있습니다.
+*경로 처리 데코레이터*에 매개변수(들)를 전달하여 *경로 처리*를 설정하고 메타데이터를 쉽게 추가할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/path-params-numeric-validations.md b/docs/ko/docs/tutorial/path-params-numeric-validations.md
index f21c9290e..f2c52d4aa 100644
--- a/docs/ko/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/ko/docs/tutorial/path-params-numeric-validations.md
@@ -1,116 +1,153 @@
-# 경로 매개변수와 숫자 검증
+# 경로 매개변수와 숫자 검증 { #path-parameters-and-numeric-validations }
`Query`를 사용하여 쿼리 매개변수에 더 많은 검증과 메타데이터를 선언하는 방법과 동일하게 `Path`를 사용하여 경로 매개변수에 검증과 메타데이터를 같은 타입으로 선언할 수 있습니다.
-## 경로 임포트
+## `Path` 임포트 { #import-path }
-먼저 `fastapi`에서 `Path`를 임포트합니다:
+먼저 `fastapi`에서 `Path`를 임포트하고, `Annotated`도 임포트합니다:
-{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[3] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-## 메타데이터 선언
+/// info | 정보
+
+FastAPI는 0.95.0 버전에서 `Annotated` 지원을 추가했고(그리고 이를 권장하기 시작했습니다).
+
+더 오래된 버전이 있다면 `Annotated`를 사용하려고 할 때 오류가 발생합니다.
+
+`Annotated`를 사용하기 전에 최소 0.95.1까지 [FastAPI 버전 업그레이드](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}를 꼭 하세요.
+
+///
+
+## 메타데이터 선언 { #declare-metadata }
`Query`에 동일한 매개변수를 선언할 수 있습니다.
-예를 들어, `title` 메타데이터 값을 경로 매개변수 `item_id`에 선언하려면 다음과 같이 입력할 수 있습니다:
+예를 들어, 경로 매개변수 `item_id`에 `title` 메타데이터 값을 선언하려면 다음과 같이 입력할 수 있습니다:
-{* ../../docs_src/path_params_numeric_validations/tutorial001.py hl[10] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
/// note | 참고
-경로 매개변수는 경로의 일부여야 하므로 언제나 필수적입니다.
+경로 매개변수는 경로의 일부여야 하므로 언제나 필수입니다. `None`으로 선언하거나 기본값을 지정하더라도 아무 영향이 없으며, 항상 필수입니다.
-즉, `...`로 선언해서 필수임을 나타내는게 좋습니다.
+///
-그럼에도 `None`으로 선언하거나 기본값을 지정할지라도 아무 영향을 끼치지 않으며 언제나 필수입니다.
+## 필요한 대로 매개변수 정렬하기 { #order-the-parameters-as-you-need }
-///
+/// tip | 팁
-## 필요한 경우 매개변수 정렬하기
+`Annotated`를 사용한다면 이것은 아마 그렇게 중요하지 않거나 필요하지 않을 수 있습니다.
+
+///
`str` 형인 쿼리 매개변수 `q`를 필수로 선언하고 싶다고 해봅시다.
-해당 매개변수에 대해 아무런 선언을 할 필요가 없으므로 `Query`를 정말로 써야할 필요는 없습니다.
+해당 매개변수에 대해 아무런 선언을 할 필요가 없으므로 `Query`를 정말로 써야 할 필요는 없습니다.
+
+하지만 `item_id` 경로 매개변수는 여전히 `Path`를 사용해야 합니다. 그리고 어떤 이유로 `Annotated`를 사용하고 싶지 않다고 해봅시다.
-하지만 `item_id` 경로 매개변수는 여전히 `Path`를 사용해야 합니다.
+파이썬은 "기본값"이 있는 값을 "기본값"이 없는 값 앞에 두면 불평합니다.
+
+하지만 순서를 재정렬해서 기본값이 없는 값(쿼리 매개변수 `q`)을 앞에 둘 수 있습니다.
+
+**FastAPI**에서는 중요하지 않습니다. 이름, 타입 그리고 기본값 선언(`Query`, `Path` 등)로 매개변수를 감지하며 순서는 신경 쓰지 않습니다.
+
+따라서 함수를 다음과 같이 선언할 수 있습니다:
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *}
+
+하지만 `Annotated`를 사용하면 이 문제가 없다는 점을 기억하세요. `Query()`나 `Path()`에 함수 매개변수 기본값을 사용하지 않기 때문에, 순서는 중요하지 않습니다.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
+
+## 필요한 대로 매개변수 정렬하기, 트릭 { #order-the-parameters-as-you-need-tricks }
+
+/// tip | 팁
+
+`Annotated`를 사용한다면 이것은 아마 그렇게 중요하지 않거나 필요하지 않을 수 있습니다.
+
+///
-파이썬은 "기본값"이 없는 값 앞에 "기본값"이 있는 값을 입력하면 불평합니다.
+유용할 수 있는 **작은 트릭**이 하나 있지만, 자주 필요하진 않을 겁니다.
-그러나 매개변수들을 재정렬함으로써 기본값(쿼리 매개변수 `q`)이 없는 값을 처음 부분에 위치 할 수 있습니다.
+만약 다음을 원한다면:
-**FastAPI**에서는 중요하지 않습니다. 이름, 타입 그리고 선언구(`Query`, `Path` 등)로 매개변수를 감지하며 순서는 신경 쓰지 않습니다.
+* `Query`나 어떤 기본값 없이 쿼리 매개변수 `q`를 선언하기
+* `Path`를 사용해서 경로 매개변수 `item_id`를 선언하기
+* 이들을 다른 순서로 두기
+* `Annotated`를 사용하지 않기
-따라서 함수를 다음과 같이 선언 할 수 있습니다:
+...이를 위해 파이썬에는 작은 특별한 문법이 있습니다.
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+함수의 첫 번째 매개변수로 `*`를 전달하세요.
-## 필요한 경우 매개변수 정렬하기, 트릭
+파이썬은 `*`으로 아무것도 하지 않지만, 뒤따르는 모든 매개변수는 키워드 인자(키-값 쌍)로 호출되어야 함을 알게 됩니다. 이는 kwargs로도 알려져 있습니다. 기본값이 없더라도 마찬가지입니다.
-`Query`나 아무런 기본값으로도 `q` 경로 매개변수를 선언하고 싶지 않지만 `Path`를 사용하여 경로 매개변수를 `item_id` 다른 순서로 선언하고 싶다면, 파이썬은 이를 위한 작고 특별한 문법이 있습니다.
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
-`*`를 함수의 첫 번째 매개변수로 전달하세요.
+### `Annotated`를 쓰면 더 좋습니다 { #better-with-annotated }
-파이썬은 `*`으로 아무런 행동도 하지 않지만, 따르는 매개변수들은 kwargs로도 알려진 키워드 인자(키-값 쌍)여야 함을 인지합니다. 기본값을 가지고 있지 않더라도 그렇습니다.
+`Annotated`를 사용하면 함수 매개변수 기본값을 사용하지 않기 때문에 이 문제가 발생하지 않으며, 아마 `*`도 사용할 필요가 없다는 점을 기억하세요.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
-## 숫자 검증: 크거나 같음
+## 숫자 검증: 크거나 같음 { #number-validations-greater-than-or-equal }
-`Query`와 `Path`(나중에 볼 다른 것들도)를 사용하여 문자열 뿐만 아니라 숫자의 제약을 선언할 수 있습니다.
+`Query`와 `Path`(그리고 나중에 볼 다른 것들)를 사용하여 숫자 제약을 선언할 수 있습니다.
-여기서 `ge=1`인 경우, `item_id`는 `1`보다 "크거나(`g`reater) 같은(`e`qual)" 정수형 숫자여야 합니다.
+여기서 `ge=1`인 경우, `item_id`는 `1`보다 "`g`reater than or `e`qual"(크거나 같은) 정수형 숫자여야 합니다.
-{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
-## 숫자 검증: 크거나 같음 및 작거나 같음
+## 숫자 검증: 크거나 및 작거나 같음 { #number-validations-greater-than-and-less-than-or-equal }
동일하게 적용됩니다:
-* `gt`: 크거나(`g`reater `t`han)
-* `le`: 작거나 같은(`l`ess than or `e`qual)
+* `gt`: `g`reater `t`han
+* `le`: `l`ess than or `e`qual
-{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
-## 숫자 검증: 부동소수, 크거나 및 작거나
+## 숫자 검증: 부동소수, 크거나 및 작거나 { #number-validations-floats-greater-than-and-less-than }
숫자 검증은 `float` 값에도 동작합니다.
-여기에서 ge뿐만 아니라 gt를 선언 할 수있는 것이 중요해집니다. 예를 들어 필요한 경우, 값이 `1`보다 작더라도 반드시 `0`보다 커야합니다.
+여기에서 gt를, ge뿐만 아니라 선언할 수 있다는 점이 중요해집니다. 예를 들어 값이 `1`보다 작더라도, 반드시 `0`보다 커야 한다고 요구할 수 있습니다.
즉, `0.5`는 유효한 값입니다. 그러나 `0.0` 또는 `0`은 그렇지 않습니다.
lt 역시 마찬가지입니다.
-{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## 요약
+## 요약 { #recap }
`Query`, `Path`(아직 보지 못한 다른 것들도)를 사용하면 [쿼리 매개변수와 문자열 검증](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)
+* `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` 클래스의 서브 클래스입니다.
+`Query`, `Path`, 그리고 나중에 보게 될 다른 클래스들은 공통 `Param` 클래스의 서브클래스입니다.
-그리고 이들 모두는 여태까지 본 추가 검증과 메타데이터의 동일한 모든 매개변수를 공유합니다.
+이들 모두는 여러분이 본 추가 검증과 메타데이터에 대한 동일한 매개변수를 공유합니다.
///
/// note | 기술 세부사항
-`fastapi`에서 `Query`, `Path` 등을 임포트 할 때, 이것들은 실제로 함수입니다.
+`fastapi`에서 `Query`, `Path` 등을 임포트할 때, 이것들은 실제로 함수입니다.
호출되면 동일한 이름의 클래스의 인스턴스를 반환합니다.
즉, 함수인 `Query`를 임포트한 겁니다. 그리고 호출하면 `Query`라는 이름을 가진 클래스의 인스턴스를 반환합니다.
-편집기에서 타입에 대한 오류를 표시하지 않도록 하기 위해 (클래스를 직접 사용하는 대신) 이러한 함수들이 있습니다.
+이 함수들이 있는 이유는(클래스를 직접 사용하는 대신) 편집기에서 타입에 대한 오류를 표시하지 않도록 하기 위해서입니다.
이렇게 하면 오류를 무시하기 위한 사용자 설정을 추가하지 않고도 일반 편집기와 코딩 도구를 사용할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/path-params.md b/docs/ko/docs/tutorial/path-params.md
index b72787e0b..ea5170ecc 100644
--- a/docs/ko/docs/tutorial/path-params.md
+++ b/docs/ko/docs/tutorial/path-params.md
@@ -1,8 +1,8 @@
-# 경로 매개변수
+# 경로 매개변수 { #path-parameters }
파이썬의 포맷 문자열 리터럴에서 사용되는 문법을 이용하여 경로 "매개변수" 또는 "변수"를 선언할 수 있습니다:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
경로 매개변수 `item_id`의 값은 함수의 `item_id` 인자로 전달됩니다.
@@ -12,11 +12,11 @@
{"item_id":"foo"}
```
-## 타입이 있는 매개변수
+## 타입이 있는 경로 매개변수 { #path-parameters-with-types }
파이썬 표준 타입 어노테이션을 사용하여 함수에 있는 경로 매개변수의 타입을 선언할 수 있습니다:
-{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *}
위의 예시에서, `item_id`는 `int`로 선언되었습니다.
@@ -26,7 +26,7 @@
///
-## 데이터 변환
+## 데이터 변환 { #data-conversion }
이 예제를 실행하고 http://127.0.0.1:8000/items/3을 열면, 다음 응답을 볼 수 있습니다:
@@ -42,40 +42,41 @@
///
-## 데이터 검증
+## 데이터 검증 { #data-validation }
-하지만 브라우저에서 http://127.0.0.1:8000/items/foo로 이동하면, HTTP 오류가 잘 뜨는 것을 확인할 수 있습니다:
+하지만 브라우저에서 http://127.0.0.1:8000/items/foo로 이동하면, 다음과 같은 HTTP 오류를 볼 수 있습니다:
```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"
+ }
+ ]
}
```
-경로 매개변수 `item_id`는 `int`가 아닌 `"foo"` 값이기 때문입니다.
+경로 매개변수 `item_id`가 `int`가 아닌 `"foo"` 값을 가졌기 때문입니다.
-`int`가 아닌 `float`을 전달하는 경우에도 동일한 오류가 나타납니다: http://127.0.0.1:8000/items/4.2
+`int` 대신 `float`을 제공하면(예: http://127.0.0.1:8000/items/4.2) 동일한 오류가 나타납니다.
/// check | 확인
즉, 파이썬 타입 선언을 하면 **FastAPI**는 데이터 검증을 합니다.
-오류에는 정확히 어느 지점에서 검증을 통과하지 못했는지 명시됩니다.
+또한 오류에는 검증을 통과하지 못한 지점이 정확히 명시됩니다.
이는 API와 상호 작용하는 코드를 개발하고 디버깅하는 데 매우 유용합니다.
///
-## 문서화
+## 문서화 { #documentation }
그리고 브라우저에서 http://127.0.0.1:8000/docs를 열면, 다음과 같이 자동 대화식 API 문서를 볼 수 있습니다:
@@ -83,23 +84,23 @@
/// check | 확인
-그저 파이썬 타입 선언을 하기만 하면 **FastAPI**는 자동 대화형 API 문서(Swagger UI)를 제공합니다.
+다시 한 번, 동일한 파이썬 타입 선언만으로 **FastAPI**는 자동 대화형 문서(Swagger UI 통합)를 제공합니다.
-경로 매개변수가 정수형으로 명시된 것을 확인할 수 있습니다.
+경로 매개변수가 정수형으로 선언된 것을 확인할 수 있습니다.
///
-## 표준 기반의 이점, 대체 문서
+## 표준 기반의 이점, 대체 문서 { #standards-based-benefits-alternative-documentation }
-그리고 생성된 스키마는 OpenAPI 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
+그리고 생성된 스키마는 OpenAPI 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
-이 덕분에 **FastAPI**는 http://127.0.0.1:8000/redoc로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다:
+이 덕분에 **FastAPI** 자체에서 http://127.0.0.1:8000/redoc로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다:
이와 마찬가지로 다양한 언어에 대한 코드 생성 도구를 포함하여 여러 호환되는 도구가 있습니다.
-## Pydantic
+## Pydantic { #pydantic }
모든 데이터 검증은 Pydantic에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
@@ -107,73 +108,73 @@
이 중 몇 가지는 자습서의 다음 장에 설명되어 있습니다.
-## 순서 문제
+## 순서 문제 { #order-matters }
-*경로 작동*을 만들때 고정 경로를 갖고 있는 상황들을 맞닥뜨릴 수 있습니다.
+*경로 처리*를 만들 때 고정 경로를 갖고 있는 상황들을 맞닥뜨릴 수 있습니다.
`/users/me`처럼, 현재 사용자의 데이터를 가져온다고 합시다.
사용자 ID를 이용해 특정 사용자의 정보를 가져오는 경로 `/users/{user_id}`도 있습니다.
-*경로 작동*은 순차적으로 실행되기 때문에 `/users/{user_id}` 이전에 `/users/me`를 먼저 선언해야 합니다:
+*경로 처리*는 순차적으로 평가되기 때문에 `/users/{user_id}` 이전에 `/users/me`에 대한 경로가 먼저 선언되었는지 확인해야 합니다:
-{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *}
-그렇지 않으면 `/users/{user_id}`는 `/users/me` 요청 또한 매개변수 `user_id`의 값이 `"me"`인 것으로 "생각하게" 됩니다.
+그렇지 않으면 `/users/{user_id}`에 대한 경로가 `/users/me`에도 매칭되어, 매개변수 `user_id`에 `"me"` 값이 들어왔다고 "생각하게" 됩니다.
-## 사전정의 값
+마찬가지로, 경로 처리를 재정의할 수는 없습니다:
-만약 *경로 매개변수*를 받는 *경로 작동*이 있지만, *경로 매개변수*로 가능한 값들을 미리 정의하고 싶다면 파이썬 표준 `Enum`을 사용할 수 있습니다.
+{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
-### `Enum` 클래스 생성
+경로가 먼저 매칭되기 때문에 첫 번째 것이 항상 사용됩니다.
-`Enum`을 임포트하고 `str`과 `Enum`을 상속하는 서브 클래스를 만듭니다.
+## 사전정의 값 { #predefined-values }
-`str`을 상속함으로써 API 문서는 값이 `string` 형이어야 하는 것을 알게 되고 이는 문서에 제대로 표시됩니다.
+만약 *경로 매개변수*를 받는 *경로 처리*가 있지만, 가능한 유효한 *경로 매개변수* 값들을 미리 정의하고 싶다면 파이썬 표준 `Enum`을 사용할 수 있습니다.
-가능한 값들에 해당하는 고정된 값의 클래스 어트리뷰트들을 만듭니다:
+### `Enum` 클래스 생성 { #create-an-enum-class }
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+`Enum`을 임포트하고 `str`과 `Enum`을 상속하는 서브 클래스를 만듭니다.
-/// info | 정보
+`str`을 상속함으로써 API 문서는 값이 `string` 형이어야 하는 것을 알게 되고 이는 문서에 제대로 표시됩니다.
-열거형(또는 enums)은 파이썬 버전 3.4 이후로 사용 가능합니다.
+가능한 값들에 해당하는 고정된 값의 클래스 어트리뷰트들을 만듭니다:
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip | 팁
-혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 기계 학습 모델들의 이름입니다.
+혹시 궁금하다면, "AlexNet", "ResNet", 그리고 "LeNet"은 그저 머신 러닝 모델들의 이름입니다.
///
-### *경로 매개변수* 선언
+### *경로 매개변수* 선언 { #declare-a-path-parameter }
생성한 열거형 클래스(`ModelName`)를 사용하는 타입 어노테이션으로 *경로 매개변수*를 만듭니다:
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
-### 문서 확인
+### 문서 확인 { #check-the-docs }
*경로 매개변수*에 사용할 수 있는 값은 미리 정의되어 있으므로 대화형 문서에서 잘 표시됩니다:
-### 파이썬 *열거형*으로 작업하기
+### 파이썬 *열거형*으로 작업하기 { #working-with-python-enumerations }
*경로 매개변수*의 값은 *열거형 멤버*가 됩니다.
-#### *열거형 멤버* 비교
+#### *열거형 멤버* 비교 { #compare-enumeration-members }
-열거형 `ModelName`의 *열거형 멤버*를 비교할 수 있습니다:
+생성한 열거형 `ModelName`의 *열거형 멤버*와 비교할 수 있습니다:
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
-#### *열거형 값* 가져오기
+#### *열거형 값* 가져오기 { #get-the-enumeration-value }
`model_name.value` 또는 일반적으로 `your_enum_member.value`를 이용하여 실제 값(위 예시의 경우 `str`)을 가져올 수 있습니다:
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip | 팁
@@ -181,15 +182,15 @@
///
-#### *열거형 멤버* 반환
+#### *열거형 멤버* 반환 { #return-enumeration-members }
-*경로 작동*에서 *열거형 멤버*를 반환할 수 있습니다. 이는 중첩 JSON 본문(예: `dict`)내의 값으로도 가능합니다.
+*경로 처리*에서 *enum 멤버*를 반환할 수 있습니다. 이는 JSON 본문(예: `dict`) 내에 중첩된 형태로도 가능합니다.
클라이언트에 반환하기 전에 해당 값(이 경우 문자열)으로 변환됩니다:
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}
-클라이언트는 아래의 JSON 응답을 얻습니다:
+클라이언트는 아래와 같은 JSON 응답을 얻게 됩니다:
```JSON
{
@@ -198,53 +199,53 @@
}
```
-## 경로를 포함하는 경로 매개변수
+## 경로를 포함하는 경로 매개변수 { #path-parameters-containing-paths }
-경로를 포함하는 *경로 작동* `/files/{file_path}`이 있다고 해봅시다.
+경로 `/files/{file_path}`를 가진 *경로 처리*가 있다고 해봅시다.
-그런데 이 경우 `file_path` 자체가 `home/johndoe/myfile.txt`와 같은 경로를 포함해야 합니다.
+하지만 `file_path` 자체가 `home/johndoe/myfile.txt`와 같은 *경로*를 포함해야 합니다.
이때 해당 파일의 URL은 다음처럼 됩니다: `/files/home/johndoe/myfile.txt`.
-### OpenAPI 지원
+### OpenAPI 지원 { #openapi-support }
테스트와 정의가 어려운 시나리오로 이어질 수 있으므로 OpenAPI는 *경로*를 포함하는 *경로 매개변수*를 내부에 선언하는 방법을 지원하지 않습니다.
-그럼에도 Starlette의 내부 도구중 하나를 사용하여 **FastAPI**에서는 이가 가능합니다.
+그럼에도 Starlette의 내부 도구 중 하나를 사용하여 **FastAPI**에서는 이가 가능합니다.
-문서에 매개변수에 경로가 포함되어야 한다는 정보가 명시되지는 않지만 여전히 작동합니다.
+또한 문서가 여전히 동작하긴 하지만, 매개변수에 경로가 포함되어야 한다는 내용을 추가로 문서화하지는 않습니다.
-### 경로 변환기
+### 경로 변환기 { #path-convertor }
-Starlette의 옵션을 직접 이용하여 다음과 같은 URL을 사용함으로써 *path*를 포함하는 *경로 매개변수*를 선언할 수 있습니다:
+Starlette의 옵션을 직접 이용하여 다음과 같은 URL을 사용함으로써 *경로*를 포함하는 *경로 매개변수*를 선언할 수 있습니다:
```
/files/{file_path:path}
```
-이러한 경우 매개변수의 이름은 `file_path`이며, 마지막 부분 `:path`는 매개변수가 *경로*와 일치해야 함을 명시합니다.
+이러한 경우 매개변수의 이름은 `file_path`이며, 마지막 부분 `:path`는 매개변수가 어떤 *경로*와도 매칭되어야 함을 의미합니다.
따라서 다음과 같이 사용할 수 있습니다:
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}
/// tip | 팁
-매개변수가 가져야 하는 값이 `/home/johndoe/myfile.txt`와 같이 슬래시로 시작(`/`)해야 할 수 있습니다.
+매개변수가 선행 슬래시(`/`)가 있는 `/home/johndoe/myfile.txt`를 포함해야 할 수도 있습니다.
-이 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`과 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
+그 경우 URL은: `/files//home/johndoe/myfile.txt`이며 `files`와 `home` 사이에 이중 슬래시(`//`)가 생깁니다.
///
-## 요약
+## 요약 { #recap }
**FastAPI**를 이용하면 짧고 직관적인 표준 파이썬 타입 선언을 사용하여 다음을 얻을 수 있습니다:
* 편집기 지원: 오류 검사, 자동완성 등
-* 데이터 "파싱"
+* 데이터 "parsing"
* 데이터 검증
* API 주석(Annotation)과 자동 문서
-단 한번의 선언만으로 위 사항들을 모두 선언할 수 있습니다.
+그리고 한 번만 선언하면 됩니다.
이는 대체 프레임워크와 비교했을 때 (엄청나게 빠른 성능 외에도) **FastAPI**의 주요한 장점일 것입니다.
diff --git a/docs/ko/docs/tutorial/query-param-models.md b/docs/ko/docs/tutorial/query-param-models.md
index 2ca65a331..d354c56c3 100644
--- a/docs/ko/docs/tutorial/query-param-models.md
+++ b/docs/ko/docs/tutorial/query-param-models.md
@@ -1,48 +1,48 @@
-# 쿼리 매개변수 모델
+# 쿼리 매개변수 모델 { #query-parameter-models }
-연관된 쿼리 **매개변수** 그룹이 있다면 **Pydantic 모델** 을 사용해 선언할 수 있습니다.
+연관된 **쿼리 매개변수** 그룹이 있다면 이를 선언하기 위해 **Pydantic 모델**을 생성할 수 있습니다.
이렇게 하면 **여러 곳**에서 **모델을 재사용**할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎
/// note | 참고
-이 기능은 FastAPI 버전 `0.115.0`부터 제공됩니다. 🤓
+이 기능은 FastAPI 버전 `0.115.0`부터 지원됩니다. 🤓
///
-## 쿼리 매개변수와 Pydantic 모델
+## Pydantic 모델과 쿼리 매개변수 { #query-parameters-with-a-pydantic-model }
-필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 모델을 `Query`로 선언합니다.
+필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 매개변수를 `Query`로 선언합니다:
{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}
-**FastAPI**는 요청의 **쿼리 매개변수**에서 **각 필드**의 데이터를 **추출**해 정의한 Pydantic 모델로 제공합니다.
+**FastAPI**는 요청의 **쿼리 매개변수**에서 **각 필드**의 데이터를 **추출**해 정의한 Pydantic 모델을 제공합니다.
-## 문서 확인하기
+## 문서 확인하기 { #check-the-docs }
-`/docs` 경로의 API 문서에서 매개변수를 확인할 수 있습니다.
+`/docs`의 문서 UI에서 쿼리 매개변수를 확인할 수 있습니다:
-### 쿼리 매개변수 리스트 / 기본값을 사용하는 다중값
+### 쿼리 매개변수 리스트 / 기본값이 있는 다중값 { #query-parameter-list-multiple-values-with-defaults }
-그리고 제공된 값이 없으면 기본 `list` 값을 정의할 수도 있습니다:
+제공된 값이 없으면 기본 `list` 값을 정의할 수도 있습니다:
-{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
-아래로 이동한다면:
+다음으로 이동하면:
```
http://localhost:8000/items/
```
-`q`의 기본값은: `["foo", "bar"]`이며 응답은 다음이 됩니다:
+`q`의 기본값은 `["foo", "bar"]`가 되고, 응답은 다음이 됩니다:
```JSON
{
@@ -204,21 +312,21 @@ http://localhost:8000/items/
}
```
-#### `list` 사용하기
+#### `list`만 사용하기 { #using-just-list }
-`List[str]` 대신 `list`를 직접 사용할 수도 있습니다:
+`list[str]` 대신 `list`를 직접 사용할 수도 있습니다:
-{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
/// note | 참고
-이 경우 FastAPI는 리스트의 내용을 검사하지 않음을 명심하기 바랍니다.
+이 경우 FastAPI는 리스트의 내용을 검사하지 않음을 명심하세요.
-예를 들어, `List[int]`는 리스트 내용이 정수인지 검사(및 문서화)합니다. 하지만 `list` 단독일 경우는 아닙니다.
+예를 들어, `list[int]`는 리스트 내용이 정수인지 검사(및 문서화)합니다. 하지만 `list` 단독일 경우는 아닙니다.
///
-## 더 많은 메타데이터 선언
+## 더 많은 메타데이터 선언 { #declare-more-metadata }
매개변수에 대한 정보를 추가할 수 있습니다.
@@ -226,7 +334,7 @@ http://localhost:8000/items/
/// note | 참고
-도구에 따라 OpenAPI 지원 수준이 다를 수 있음을 명심하기 바랍니다.
+도구에 따라 OpenAPI 지원 수준이 다를 수 있음을 명심하세요.
일부는 아직 선언된 추가 정보를 모두 표시하지 않을 수 있지만, 대부분의 경우 누락된 기능은 이미 개발 계획이 있습니다.
@@ -234,13 +342,13 @@ http://localhost:8000/items/
`title`을 추가할 수 있습니다:
-{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
그리고 `description`도 추가할 수 있습니다:
-{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## 별칭 매개변수
+## 별칭 매개변수 { #alias-parameters }
매개변수가 `item-query`이길 원한다고 가정해 봅시다.
@@ -250,31 +358,99 @@ http://localhost:8000/items/
http://127.0.0.1:8000/items/?item-query=foobaritems
```
-그러나 `item-query`은 유효한 파이썬 변수 이름이 아닙니다.
+그러나 `item-query`는 유효한 파이썬 변수 이름이 아닙니다.
가장 가까운 것은 `item_query`일 겁니다.
-하지만 정확히`item-query`이길 원합니다...
+하지만 정확히 `item-query`이길 원합니다...
이럴 경우 `alias`를 선언할 수 있으며, 해당 별칭은 매개변수 값을 찾는 데 사용됩니다:
-{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## 매개변수 사용하지 않게 하기
+## 매개변수 사용 중단하기 { #deprecating-parameters }
-이제는 더이상 이 매개변수를 마음에 들어하지 않는다고 가정해 봅시다.
+이제는 더 이상 이 매개변수를 마음에 들어하지 않는다고 가정해 봅시다.
-이 매개변수를 사용하는 클라이언트가 있기 때문에 한동안은 남겨둬야 하지만, 사용되지 않는다(deprecated)고 확실하게 문서에서 보여주고 싶습니다.
+이 매개변수를 사용하는 클라이언트가 있기 때문에 한동안은 남겨둬야 하지만, 문서에서 deprecated로 명확하게 보여주고 싶습니다.
그렇다면 `deprecated=True` 매개변수를 `Query`로 전달합니다:
-{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
문서가 아래와 같이 보일겁니다:
-## 요약
+## OpenAPI에서 매개변수 제외 { #exclude-parameters-from-openapi }
+
+생성된 OpenAPI 스키마(따라서 자동 문서화 시스템)에서 쿼리 매개변수를 제외하려면 `Query`의 `include_in_schema` 매개변수를 `False`로 설정하세요:
+
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
+
+## 커스텀 검증 { #custom-validation }
+
+위에 나온 매개변수들로는 할 수 없는 **커스텀 검증**이 필요한 경우가 있을 수 있습니다.
+
+그런 경우에는 일반적인 검증(예: 값이 `str`인지 검증한 뒤) 이후에 적용되는 **커스텀 검증 함수**를 사용할 수 있습니다.
+
+`Annotated` 안에서 Pydantic의 `AfterValidator`를 사용하면 이를 구현할 수 있습니다.
+
+/// tip | 팁
+
+Pydantic에는 `BeforeValidator`와 같은 다른 것들도 있습니다. 🤓
+
+///
+
+예를 들어, 이 커스텀 validator는 ISBN 도서 번호의 경우 아이템 ID가 `isbn-`으로 시작하고, IMDB 영화 URL ID의 경우 `imdb-`로 시작하는지 확인합니다:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
+
+/// info | 정보
+
+이는 Pydantic 2 이상 버전에서 사용할 수 있습니다. 😎
+
+///
+
+/// tip | 팁
+
+데이터베이스나 다른 API 같은 **외부 구성요소**와 통신이 필요한 어떤 종류의 검증이든 해야 한다면, 대신 **FastAPI Dependencies**를 사용해야 합니다. 이에 대해서는 나중에 배우게 됩니다.
+
+이 커스텀 validator는 요청에서 제공된 **같은 데이터만**으로 확인할 수 있는 것들을 위한 것입니다.
+
+///
+
+### 코드 이해하기 { #understand-that-code }
+
+중요한 부분은 **`Annotated` 안에서 함수와 함께 `AfterValidator`를 사용한다는 것**뿐입니다. 이 부분은 건너뛰셔도 됩니다. 🤸
+
+---
+
+하지만 이 특정 코드 예제가 궁금하고 계속 보고 싶다면, 추가 세부사항은 다음과 같습니다.
+
+#### `value.startswith()`를 사용한 문자열 { #string-with-value-startswith }
+
+알고 계셨나요? `value.startswith()`를 사용하는 문자열은 튜플을 받을 수 있으며, 튜플에 있는 각 값을 확인합니다:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### 임의의 항목 { #a-random-item }
+
+`data.items()`를 사용하면 각 딕셔너리 항목의 키와 값을 담은 튜플로 구성된 iterable object를 얻습니다.
+
+이 iterable object를 `list(data.items())`로 적절한 `list`로 변환합니다.
+
+그 다음 `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] *}
+
+## 요약 { #recap }
매개변수에 검증과 메타데이터를 추가 선언할 수 있습니다.
@@ -285,12 +461,14 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
* `description`
* `deprecated`
-특정 문자열 검증:
+문자열에 특화된 검증:
* `min_length`
* `max_length`
-* `regex`
+* `pattern`
+
+`AfterValidator`를 사용하는 커스텀 검증.
예제에서 `str` 값의 검증을 어떻게 추가하는지 살펴보았습니다.
-숫자와 같은 다른 자료형에 대한 검증을 어떻게 선언하는지 확인하려면 다음 장을 확인하기 바랍니다.
+숫자와 같은 다른 타입에 대한 검증을 어떻게 선언하는지 확인하려면 다음 장을 확인하기 바랍니다.
diff --git a/docs/ko/docs/tutorial/query-params.md b/docs/ko/docs/tutorial/query-params.md
index d5b9837c4..5124f73bf 100644
--- a/docs/ko/docs/tutorial/query-params.md
+++ b/docs/ko/docs/tutorial/query-params.md
@@ -1,8 +1,8 @@
-# 쿼리 매개변수
+# 쿼리 매개변수 { #query-parameters }
경로 매개변수의 일부가 아닌 다른 함수 매개변수를 선언하면 "쿼리" 매개변수로 자동 해석합니다.
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *}
쿼리는 URL에서 `?` 후에 나오고 `&`으로 구분되는 키-값 쌍의 집합입니다.
@@ -24,11 +24,11 @@ URL의 일부이므로 "자연스럽게" 문자열입니다.
경로 매개변수에 적용된 동일한 프로세스가 쿼리 매개변수에도 적용됩니다:
* (당연히) 편집기 지원
-* 데이터 "파싱"
+* 데이터 "파싱"
* 데이터 검증
* 자동 문서화
-## 기본값
+## 기본값 { #defaults }
쿼리 매개변수는 경로에서 고정된 부분이 아니기 때문에 선택적일 수 있고 기본값을 가질 수 있습니다.
@@ -57,33 +57,25 @@ http://127.0.0.1:8000/items/?skip=20
* `skip=20`: URL에서 지정했기 때문입니다
* `limit=10`: 기본값이기 때문입니다
-## 선택적 매개변수
+## 선택적 매개변수 { #optional-parameters }
같은 방법으로 기본값을 `None`으로 설정하여 선택적 매개변수를 선언할 수 있습니다:
-{* ../../docs_src/query_params/tutorial002.py hl[9] *}
+{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
이 경우 함수 매개변수 `q`는 선택적이며 기본값으로 `None` 값이 됩니다.
-/// check | 확인
+/// check
-**FastAPI**는 `item_id`가 경로 매개변수이고 `q`는 경로 매개변수가 아닌 쿼리 매개변수라는 것을 알 정도로 충분히 똑똑합니다.
+또한 **FastAPI**는 `item_id`가 경로 매개변수이고 `q`는 경로 매개변수가 아니라서 쿼리 매개변수라는 것을 알 정도로 충분히 똑똑하다는 점도 확인하세요.
///
-/// note | 참고
-
-FastAPI는 `q`가 `= None`이므로 선택적이라는 것을 인지합니다.
-
-`Union[str, None]`에 있는 `Union`은 FastAPI(FastAPI는 `str` 부분만 사용합니다)가 사용하는게 아니지만, `Union[str, None]`은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다.
-
-///
-
-## 쿼리 매개변수 형변환
+## 쿼리 매개변수 형변환 { #query-parameter-type-conversion }
`bool` 형으로 선언할 수도 있고, 아래처럼 변환됩니다:
-{* ../../docs_src/query_params/tutorial003.py hl[9] *}
+{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
이 경우, 아래로 이동하면:
@@ -115,10 +107,10 @@ http://127.0.0.1:8000/items/foo?short=on
http://127.0.0.1:8000/items/foo?short=yes
```
-또는 다른 어떤 변형(대문자, 첫글자만 대문자 등)이더라도 함수는 매개변수 `bool`형을 가진 `short`의 값이 `True`임을 압니다. 그렇지 않은 경우 `False`입니다.
+또는 다른 어떤 변형(대문자, 첫글자만 대문자 등)이더라도 함수는 `bool` 값이 `True`인 매개변수 `short`를 보게 됩니다. 그렇지 않은 경우 `False`입니다.
-## 여러 경로/쿼리 매개변수
+## 여러 경로/쿼리 매개변수 { #multiple-path-and-query-parameters }
여러 경로 매개변수와 쿼리 매개변수를 동시에 선언할 수 있으며 **FastAPI**는 어느 것이 무엇인지 알고 있습니다.
@@ -126,9 +118,9 @@ http://127.0.0.1:8000/items/foo?short=yes
매개변수들은 이름으로 감지됩니다:
-{* ../../docs_src/query_params/tutorial004.py hl[8,10] *}
+{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## 필수 쿼리 매개변수
+## 필수 쿼리 매개변수 { #required-query-parameters }
경로가 아닌 매개변수에 대한 기본값을 선언할 때(지금은 쿼리 매개변수만 보았습니다), 해당 매개변수는 필수적(Required)이지 않았습니다.
@@ -136,7 +128,7 @@ http://127.0.0.1:8000/items/foo?short=yes
그러나 쿼리 매개변수를 필수로 만들려면 단순히 기본값을 선언하지 않으면 됩니다:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
여기 쿼리 매개변수 `needy`는 `str`형인 필수 쿼리 매개변수입니다.
@@ -150,16 +142,17 @@ http://127.0.0.1:8000/items/foo-item
```JSON
{
- "detail": [
- {
- "loc": [
- "query",
- "needy"
- ],
- "msg": "field required",
- "type": "value_error.missing"
- }
- ]
+ "detail": [
+ {
+ "type": "missing",
+ "loc": [
+ "query",
+ "needy"
+ ],
+ "msg": "Field required",
+ "input": null
+ }
+ ]
}
```
@@ -180,7 +173,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
그리고 물론, 일부 매개변수는 필수로, 다른 일부는 기본값을, 또 다른 일부는 선택적으로 선언할 수 있습니다:
-{* ../../docs_src/query_params/tutorial006.py hl[10] *}
+{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
위 예시에서는 3가지 쿼리 매개변수가 있습니다:
@@ -188,8 +181,8 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
* `skip`, 기본값이 `0`인 `int`.
* `limit`, 선택적인 `int`.
-/// tip | 팁
+/// tip
-[경로 매개변수](path-params.md#_8){.internal-link target=_blank}와 마찬가지로 `Enum`을 사용할 수 있습니다.
+[경로 매개변수](path-params.md#predefined-values){.internal-link target=_blank}와 마찬가지로 `Enum`을 사용할 수 있습니다.
///
diff --git a/docs/ko/docs/tutorial/request-files.md b/docs/ko/docs/tutorial/request-files.md
index 9162b353c..cc0000921 100644
--- a/docs/ko/docs/tutorial/request-files.md
+++ b/docs/ko/docs/tutorial/request-files.md
@@ -1,4 +1,4 @@
-# 파일 요청
+# 파일 요청 { #request-files }
`File`을 사용하여 클라이언트가 업로드할 파일들을 정의할 수 있습니다.
@@ -6,23 +6,27 @@
업로드된 파일을 전달받기 위해 먼저 `python-multipart`를 설치해야합니다.
-예시) `pip install python-multipart`.
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고, 활성화한 다음, 예를 들어 다음과 같이 설치하세요:
+
+```console
+$ pip install python-multipart
+```
업로드된 파일들은 "폼 데이터"의 형태로 전송되기 때문에 이 작업이 필요합니다.
///
-## `File` 임포트
+## `File` 임포트 { #import-file }
`fastapi` 에서 `File` 과 `UploadFile` 을 임포트 합니다:
-{* ../../docs_src/request_files/tutorial001.py hl[1] *}
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## `File` 매개변수 정의
+## `File` 매개변수 정의 { #define-file-parameters }
`Body` 및 `Form` 과 동일한 방식으로 파일의 매개변수를 생성합니다:
-{* ../../docs_src/request_files/tutorial001.py hl[7] *}
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
/// info | 정보
@@ -40,20 +44,21 @@ File의 본문을 선언할 때, 매개변수가 쿼리 매개변수 또는 본
파일들은 "폼 데이터"의 형태로 업로드 됩니다.
-*경로 작동 함수*의 매개변수를 `bytes` 로 선언하는 경우 **FastAPI**는 파일을 읽고 `bytes` 형태의 내용을 전달합니다.
+*경로 처리 함수*의 매개변수를 `bytes` 로 선언하는 경우 **FastAPI**는 파일을 읽고 `bytes` 형태의 내용을 전달합니다.
이것은 전체 내용이 메모리에 저장된다는 것을 의미한다는 걸 염두하기 바랍니다. 이는 작은 크기의 파일들에 적합합니다.
어떤 경우에는 `UploadFile` 을 사용하는 것이 더 유리합니다.
-## `File` 매개변수와 `UploadFile`
+## `UploadFile`을 사용하는 `File` 매개변수 { #file-parameters-with-uploadfile }
`File` 매개변수를 `UploadFile` 타입으로 정의합니다:
-{* ../../docs_src/request_files/tutorial001.py hl[12] *}
+{* ../../docs_src/request_files/tutorial001_an_py39.py hl[14] *}
`UploadFile` 을 사용하는 것은 `bytes` 과 비교해 다음과 같은 장점이 있습니다:
+* 매개변수의 기본값에서 `File()`을 사용할 필요가 없습니다.
* "스풀 파일"을 사용합니다.
* 최대 크기 제한까지만 메모리에 저장되며, 이를 초과하는 경우 디스크에 저장됩니다.
* 따라서 이미지, 동영상, 큰 이진코드와 같은 대용량 파일들을 많은 메모리를 소모하지 않고 처리하기에 적합합니다.
@@ -61,13 +66,13 @@ File의 본문을 선언할 때, 매개변수가 쿼리 매개변수 또는 본
* file-like `async` 인터페이스를 갖고 있습니다.
* file-like object를 필요로하는 다른 라이브러리에 직접적으로 전달할 수 있는 파이썬 `SpooledTemporaryFile` 객체를 반환합니다.
-### `UploadFile`
+### `UploadFile` { #uploadfile }
`UploadFile` 은 다음과 같은 어트리뷰트가 있습니다:
* `filename` : 문자열(`str`)로 된 업로드된 파일의 파일명입니다 (예: `myimage.jpg`).
* `content_type` : 문자열(`str`)로 된 파일 형식(MIME type / media type)입니다 (예: `image/jpeg`).
-* `file` : `SpooledTemporaryFile` (파일류 객체)입니다. 이것은 "파일류" 객체를 필요로하는 다른 라이브러리에 직접적으로 전달할 수 있는 실질적인 파이썬 파일입니다.
+* `file` : `SpooledTemporaryFile` (a file-like object)입니다. 이것은 "file-like" 객체를 필요로하는 다른 함수나 라이브러리에 직접적으로 전달할 수 있는 실질적인 파이썬 파일 객체입니다.
`UploadFile` 에는 다음의 `async` 메소드들이 있습니다. 이들은 내부적인 `SpooledTemporaryFile` 을 사용하여 해당하는 파일 메소드를 호출합니다.
@@ -80,77 +85,79 @@ File의 본문을 선언할 때, 매개변수가 쿼리 매개변수 또는 본
상기 모든 메소드들이 `async` 메소드이기 때문에 “await”을 사용하여야 합니다.
-예를들어, `async` *경로 작동 함수*의 내부에서 다음과 같은 방식으로 내용을 가져올 수 있습니다:
+예를들어, `async` *경로 처리 함수*의 내부에서 다음과 같은 방식으로 내용을 가져올 수 있습니다:
```Python
contents = await myfile.read()
```
-만약 일반적인 `def` *경로 작동 함수*의 내부라면, 다음과 같이 `UploadFile.file` 에 직접 접근할 수 있습니다:
+만약 일반적인 `def` *경로 처리 함수*의 내부라면, 다음과 같이 `UploadFile.file` 에 직접 접근할 수 있습니다:
```Python
contents = myfile.file.read()
```
-/// note | "`async` 기술적 세부사항"
+/// note | `async` 기술 세부사항
`async` 메소드들을 사용할 때 **FastAPI**는 스레드풀에서 파일 메소드들을 실행하고 그들을 기다립니다.
///
-/// note | Starlette 기술적 세부사항
+/// note | Starlette 기술 세부사항
**FastAPI**의 `UploadFile` 은 **Starlette**의 `UploadFile` 을 직접적으로 상속받지만, **Pydantic** 및 FastAPI의 다른 부분들과의 호환성을 위해 필요한 부분들이 추가되었습니다.
///
-## "폼 데이터"란
+## "폼 데이터"란 { #what-is-form-data }
HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은 대개 데이터에 JSON과는 다른 "특별한" 인코딩을 사용합니다.
**FastAPI**는 JSON 대신 올바른 위치에서 데이터를 읽을 수 있도록 합니다.
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
폼의 데이터는 파일이 포함되지 않은 경우 일반적으로 "미디어 유형" `application/x-www-form-urlencoded` 을 사용해 인코딩 됩니다.
하지만 파일이 포함된 경우, `multipart/form-data`로 인코딩됩니다. `File`을 사용하였다면, **FastAPI**는 본문의 적합한 부분에서 파일을 가져와야 한다는 것을 인지합니다.
-인코딩과 폼 필드에 대해 더 알고싶다면, POST에 관한MDN웹 문서 를 참고하기 바랍니다,.
+인코딩과 폼 필드에 대해 더 알고싶다면, MDN web docs for POST를 참고하기 바랍니다.
///
/// warning | 경고
-다수의 `File` 과 `Form` 매개변수를 한 *경로 작동*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
+다수의 `File` 과 `Form` 매개변수를 한 *경로 처리*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json` 가 아닌 `multipart/form-data` 로 인코딩 되기 때문에 JSON으로 받아야하는 `Body` 필드를 함께 선언할 수는 없습니다.
이는 **FastAPI**의 한계가 아니라, HTTP 프로토콜에 의한 것입니다.
///
-## 다중 파일 업로드
+## 선택적 파일 업로드 { #optional-file-upload }
-여러 파일을 동시에 업로드 할 수 있습니다.
+표준 타입 애너테이션을 사용하고 기본값을 `None`으로 설정하여 파일을 선택적으로 만들 수 있습니다:
-그들은 "폼 데이터"를 사용하여 전송된 동일한 "폼 필드"에 연결됩니다.
+{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
-이 기능을 사용하기 위해 , `bytes` 의 `List` 또는 `UploadFile` 를 선언하기 바랍니다:
+## 추가 메타데이터를 포함한 `UploadFile` { #uploadfile-with-additional-metadata }
-{* ../../docs_src/request_files/tutorial002.py hl[10,15] *}
+추가 메타데이터를 설정하기 위해 예를 들어 `UploadFile`과 함께 `File()`을 사용할 수도 있습니다:
-선언한대로, `bytes` 의 `list` 또는 `UploadFile` 들을 전송받을 것입니다.
+{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
-/// note | 참고
+## 다중 파일 업로드 { #multiple-file-uploads }
-2019년 4월 14일부터 Swagger UI가 하나의 폼 필드로 다수의 파일을 업로드하는 것을 지원하지 않습니다. 더 많은 정보를 원하면, #4276과 #3641을 참고하세요.
+여러 파일을 동시에 업로드 할 수 있습니다.
-그럼에도, **FastAPI**는 표준 Open API를 사용해 이미 호환이 가능합니다.
+그들은 "폼 데이터"를 사용하여 전송된 동일한 "폼 필드"에 연결됩니다.
-따라서 Swagger UI 또는 기타 그 외의 OpenAPI를 지원하는 툴이 다중 파일 업로드를 지원하는 경우, 이들은 **FastAPI**와 호환됩니다.
+이 기능을 사용하기 위해 , `bytes` 의 `List` 또는 `UploadFile` 를 선언하기 바랍니다:
-///
+{* ../../docs_src/request_files/tutorial002_an_py39.py hl[10,15] *}
+
+선언한대로, `bytes` 의 `list` 또는 `UploadFile` 들을 전송받을 것입니다.
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
`from starlette.responses import HTMLResponse` 역시 사용할 수 있습니다.
@@ -158,6 +165,12 @@ HTML의 폼들(``)이 서버에 데이터를 전송하는 방식은
///
-## 요약
+### 추가 메타데이터를 포함한 다중 파일 업로드 { #multiple-file-uploads-with-additional-metadata }
+
+이전과 같은 방식으로 `UploadFile`에 대해서도 `File()`을 사용해 추가 매개변수를 설정할 수 있습니다:
+
+{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
+
+## 요약 { #recap }
-폼 데이터로써 입력 매개변수로 업로드할 파일을 선언할 경우 `File` 을 사용하기 바랍니다.
+`File`, `bytes`, `UploadFile`을 사용하여 폼 데이터로 전송되는 요청에서 업로드할 파일을 선언하세요.
diff --git a/docs/ko/docs/tutorial/request-form-models.md b/docs/ko/docs/tutorial/request-form-models.md
index 3316a93d5..b37186dfb 100644
--- a/docs/ko/docs/tutorial/request-form-models.md
+++ b/docs/ko/docs/tutorial/request-form-models.md
@@ -1,12 +1,12 @@
-# 폼 모델
+# 폼 모델 { #form-models }
FastAPI에서 **Pydantic 모델**을 이용하여 **폼 필드**를 선언할 수 있습니다.
/// info | 정보
-폼(Form)을 사용하려면, 먼저 `python-multipart`를 설치하세요.
+폼을 사용하려면, 먼저 `python-multipart`를 설치하세요.
-[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 아래와 같이 설치할 수 있습니다:
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, 예를 들어 아래와 같이 설치하세요:
```console
$ pip install python-multipart
@@ -20,7 +20,7 @@ $ pip install python-multipart
///
-## Pydantic 모델을 사용한 폼
+## 폼을 위한 Pydantic 모델 { #pydantic-models-for-forms }
**폼 필드**로 받고 싶은 필드를 **Pydantic 모델**로 선언한 다음, 매개변수를 `Form`으로 선언하면 됩니다:
@@ -28,7 +28,7 @@ $ pip install python-multipart
**FastAPI**는 요청에서 받은 **폼 데이터**에서 **각 필드**에 대한 데이터를 **추출**하고 정의한 Pydantic 모델을 줍니다.
-## 문서 확인하기
+## 문서 확인하기 { #check-the-docs }
문서 UI `/docs`에서 확인할 수 있습니다:
@@ -36,9 +36,9 @@ $ pip install python-multipart
POST에 대한 MDN 웹 문서를 참조하세요.
+이러한 인코딩 및 폼 필드에 대해 더 읽고 싶다면, POST에 대한 MDN 웹 문서를 참조하세요.
///
/// warning | 경고
-*경로 작업*에서 여러 `Form` 매개변수를 선언할 수 있지만, JSON으로 수신할 것으로 예상되는 `Body` 필드와 함께 선언할 수 없습니다. 요청 본문은 `application/json` 대신에 `application/x-www-form-urlencoded`를 사용하여 인코딩되기 때문입니다.
+*경로 처리*에서 여러 `Form` 매개변수를 선언할 수 있지만, JSON으로 수신할 것으로 예상되는 `Body` 필드와 함께 선언할 수 없습니다. 요청 본문은 `application/json` 대신에 `application/x-www-form-urlencoded`를 사용하여 인코딩되기 때문입니다.
이는 **FastAPI**의 제한 사항이 아니며 HTTP 프로토콜의 일부입니다.
///
-## 요약
+## 요약 { #recap }
폼 데이터 입력 매개변수를 선언하려면 `Form`을 사용하세요.
diff --git a/docs/ko/docs/tutorial/response-model.md b/docs/ko/docs/tutorial/response-model.md
index a71d649f9..6246ed9ad 100644
--- a/docs/ko/docs/tutorial/response-model.md
+++ b/docs/ko/docs/tutorial/response-model.md
@@ -1,81 +1,173 @@
-# 응답 모델
+# 응답 모델 - 반환 타입 { #response-model-return-type }
-어떤 *경로 작동*이든 매개변수 `response_model`를 사용하여 응답을 위한 모델을 선언할 수 있습니다:
+*경로 처리 함수*의 **반환 타입**을 어노테이션하여 응답에 사용될 타입을 선언할 수 있습니다.
+
+함수 **매개변수**에서 입력 데이터를 위해 사용하는 것과 동일하게 **타입 어노테이션**을 사용할 수 있으며, Pydantic 모델, 리스트, 딕셔너리, 정수/불리언 같은 스칼라 값 등을 사용할 수 있습니다.
+
+{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
+
+FastAPI는 이 반환 타입을 사용하여:
+
+* 반환된 데이터를 **검증**합니다.
+ * 데이터가 유효하지 않다면(예: 필드가 누락된 경우), 이는 *여러분의* 앱 코드가 깨져서 의도한 값을 반환하지 못한다는 의미이며, 잘못된 데이터를 반환하는 대신 서버 오류를 반환합니다. 이렇게 하면 여러분과 클라이언트는 기대한 데이터와 데이터 형태를 받는다는 것을 확실히 할 수 있습니다.
+* OpenAPI *경로 처리*의 응답에 **JSON Schema**를 추가합니다.
+ * 이는 **자동 문서**에서 사용됩니다.
+ * 또한 자동 클라이언트 코드 생성 도구에서도 사용됩니다.
+
+하지만 가장 중요한 것은:
+
+* 반환 타입에 정의된 내용으로 출력 데이터를 **제한하고 필터링**합니다.
+ * 이는 특히 **보안**에 매우 중요합니다. 아래에서 더 자세히 살펴보겠습니다.
+
+## `response_model` 매개변수 { #response-model-parameter }
+
+타입 선언이 말하는 것과 정확히 일치하지 않는 데이터를 반환해야 하거나 반환하고 싶은 경우가 있습니다.
+
+예를 들어, **딕셔너리**나 데이터베이스 객체를 **반환**하고 싶지만, **Pydantic 모델로 선언**하고 싶을 수 있습니다. 이렇게 하면 Pydantic 모델이 반환한 객체(예: 딕셔너리나 데이터베이스 객체)에 대해 데이터 문서화, 검증 등 모든 작업을 수행합니다.
+
+반환 타입 어노테이션을 추가했다면, 도구와 에디터가 함수가 선언한 타입(예: Pydantic 모델)과 다른 타입(예: dict)을 반환하고 있다는 (올바른) 오류로 불평할 것입니다.
+
+그런 경우에는 반환 타입 대신 *경로 처리 데코레이터*의 매개변수 `response_model`을 사용할 수 있습니다.
+
+`response_model` 매개변수는 모든 *경로 처리*에서 사용할 수 있습니다:
* `@app.get()`
* `@app.post()`
* `@app.put()`
* `@app.delete()`
-* 기타.
+* 등.
-{* ../../docs_src/response_model/tutorial001.py hl[17] *}
+{* ../../docs_src/response_model/tutorial001_py310.py hl[17,22,24:27] *}
/// note | 참고
-`response_model`은 "데코레이터" 메소드(`get`, `post`, 등)의 매개변수입니다. 모든 매개변수들과 본문(body)처럼 *경로 작동 함수*가 아닙니다.
+`response_model`은 "데코레이터" 메서드(`get`, `post` 등)의 매개변수입니다. 모든 매개변수와 body처럼, *경로 처리 함수*의 매개변수가 아닙니다.
///
-Pydantic 모델 어트리뷰트를 선언한 것과 동일한 타입을 수신하므로 Pydantic 모델이 될 수 있지만, `List[Item]`과 같이 Pydantic 모델들의 `list`일 수도 있습니다.
+`response_model`은 Pydantic 모델 필드에 선언하는 것과 동일한 타입을 받습니다. 따라서 Pydantic 모델이 될 수도 있고, `List[Item]`처럼 Pydantic 모델의 `list`가 될 수도 있습니다.
-FastAPI는 이 `response_model`를 사용하여:
+FastAPI는 이 `response_model`을 사용해 데이터 문서화, 검증 등을 수행하고, 또한 출력 데이터를 타입 선언에 맞게 **변환하고 필터링**합니다.
-* 출력 데이터를 타입 선언으로 변환.
-* 데이터 검증.
-* OpenAPI *경로 작동*의 응답에 JSON 스키마 추가.
-* 자동 생성 문서 시스템에 사용.
+/// tip | 팁
-하지만 가장 중요한 것은:
+에디터, mypy 등에서 엄격한 타입 체크를 사용하고 있다면, 함수 반환 타입을 `Any`로 선언할 수 있습니다.
-* 해당 모델의 출력 데이터 제한. 이것이 얼마나 중요한지 아래에서 볼 것입니다.
+이렇게 하면 에디터에 의도적으로 어떤 값이든 반환한다고 알려줍니다. 하지만 FastAPI는 여전히 `response_model`을 사용하여 데이터 문서화, 검증, 필터링 등을 수행합니다.
-/// note | 기술 세부사항
+///
-응답 모델은 함수의 타입 어노테이션 대신 이 매개변수로 선언하는데, 경로 함수가 실제 응답 모델을 반환하지 않고 `dict`, 데이터베이스 객체나 기타 다른 모델을 `response_model`을 사용하여 필드 제한과 직렬화를 수행하고 반환할 수 있기 때문입니다
+### `response_model` 우선순위 { #response-model-priority }
-///
+반환 타입과 `response_model`을 둘 다 선언하면, `response_model`이 우선순위를 가지며 FastAPI에서 사용됩니다.
+
+이렇게 하면 응답 모델과 다른 타입을 반환하는 경우에도 에디터와 mypy 같은 도구에서 사용할 올바른 타입 어노테이션을 함수에 추가할 수 있습니다. 그리고 동시에 FastAPI가 `response_model`을 사용하여 데이터 검증, 문서화 등을 수행하게 할 수도 있습니다.
+
+또한 `response_model=None`을 사용해 해당 *경로 처리*에 대한 응답 모델 생성을 비활성화할 수도 있습니다. 이는 유효한 Pydantic 필드가 아닌 것들에 대해 타입 어노테이션을 추가하는 경우에 필요할 수 있으며, 아래 섹션 중 하나에서 예시를 볼 수 있습니다.
+
+## 동일한 입력 데이터 반환 { #return-the-same-input-data }
-## 동일한 입력 데이터 반환
+여기서는 평문 비밀번호를 포함하는 `UserIn` 모델을 선언합니다:
-여기서 우리는 평문 비밀번호를 포함하는 `UserIn` 모델을 선언합니다:
+{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-{* ../../docs_src/response_model/tutorial002.py hl[9,11] *}
+/// info | 정보
+
+`EmailStr`을 사용하려면 먼저 `email-validator`를 설치하세요.
+
+[가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고, 활성화한 다음 설치해야 합니다. 예를 들어:
+
+```console
+$ pip install email-validator
+```
+
+또는 다음과 같이:
+
+```console
+$ pip install "pydantic[email]"
+```
+
+///
그리고 이 모델을 사용하여 입력을 선언하고 같은 모델로 출력을 선언합니다:
-{* ../../docs_src/response_model/tutorial002.py hl[17:18] *}
+{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
이제 브라우저가 비밀번호로 사용자를 만들 때마다 API는 응답으로 동일한 비밀번호를 반환합니다.
-이 경우, 사용자가 스스로 비밀번호를 발신했기 때문에 문제가 되지 않을 수 있습니다.
+이 경우, 동일한 사용자가 비밀번호를 보내는 것이므로 문제가 되지 않을 수도 있습니다.
-그러나 동일한 모델을 다른 *경로 작동*에서 사용할 경우, 모든 클라이언트에게 사용자의 비밀번호를 발신할 수 있습니다.
+하지만 동일한 모델을 다른 *경로 처리*에서 사용하면, 모든 클라이언트에게 사용자의 비밀번호를 보내게 될 수도 있습니다.
/// danger | 위험
-절대로 사용자의 평문 비밀번호를 저장하거나 응답으로 발신하지 마십시오.
+모든 주의사항을 알고 있으며 무엇을 하는지 정확히 알고 있지 않다면, 이런 방식으로 사용자의 평문 비밀번호를 저장하거나 응답으로 보내지 마세요.
///
-## 출력 모델 추가
+## 출력 모델 추가 { #add-an-output-model }
+
+대신 평문 비밀번호를 포함하는 입력 모델과, 비밀번호가 없는 출력 모델을 만들 수 있습니다:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
+
+여기서 *경로 처리 함수*가 비밀번호를 포함하는 동일한 입력 사용자를 반환하더라도:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
+
+...비밀번호를 포함하지 않는 `UserOut` 모델로 `response_model`을 선언했습니다:
+
+{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
+
+따라서 **FastAPI**는 출력 모델에 선언되지 않은 모든 데이터를 (Pydantic을 사용하여) 필터링합니다.
+
+### `response_model` 또는 반환 타입 { #response-model-or-return-type }
+
+이 경우 두 모델이 서로 다르기 때문에, 함수 반환 타입을 `UserOut`으로 어노테이션하면 에디터와 도구는 서로 다른 클래스인데 잘못된 타입을 반환하고 있다고 불평할 것입니다.
+
+그래서 이 예제에서는 `response_model` 매개변수로 선언해야 합니다.
-대신 평문 비밀번호로 입력 모델을 만들고 해당 비밀번호 없이 출력 모델을 만들 수 있습니다:
+...하지만 아래를 계속 읽으면 이를 극복하는 방법을 볼 수 있습니다.
-{* ../../docs_src/response_model/tutorial003.py hl[9,11,16] *}
+## 반환 타입과 데이터 필터링 { #return-type-and-data-filtering }
-여기서 *경로 작동 함수*가 비밀번호를 포함하는 동일한 입력 사용자를 반환할지라도:
+이전 예제에서 계속해 봅시다. 함수에 **하나의 타입으로 어노테이션**을 하고 싶지만, 함수에서 실제로는 **더 많은 데이터**를 포함하는 것을 반환할 수 있길 원했습니다.
-{* ../../docs_src/response_model/tutorial003.py hl[24] *}
+FastAPI가 응답 모델을 사용해 데이터를 계속 **필터링**하길 원합니다. 그래서 함수가 더 많은 데이터를 반환하더라도, 응답에는 응답 모델에 선언된 필드만 포함되게 합니다.
-...`response_model`을 `UserOut` 모델로 선언했기 때문에 비밀번호를 포함하지 않습니다:
+이전 예제에서는 클래스가 달랐기 때문에 `response_model` 매개변수를 써야 했습니다. 하지만 이는 에디터와 도구가 함수 반환 타입을 체크해 주는 지원을 받지 못한다는 뜻이기도 합니다.
-{* ../../docs_src/response_model/tutorial003.py hl[22] *}
+하지만 대부분 이런 작업이 필요한 경우에는, 이 예제처럼 모델로 일부 데이터를 **필터링/제거**하길 원하는 경우가 많습니다.
-따라서 **FastAPI**는 출력 모델에서 선언하지 않은 모든 데이터를 (Pydantic을 사용하여) 필터링합니다.
+그리고 그런 경우에는 클래스와 상속을 사용하여 함수 **타입 어노테이션**을 활용해 에디터/도구에서 더 나은 지원을 받으면서도 FastAPI의 **데이터 필터링**을 유지할 수 있습니다.
-## 문서에서 보기
+{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
-자동 생성 문서를 보면 입력 모델과 출력 모델이 각자의 JSON 스키마를 가지고 있음을 확인할 수 있습니다:
+이를 통해 이 코드는 타입 관점에서 올바르므로 에디터와 mypy 등의 도구 지원을 받을 수 있고, 동시에 FastAPI의 데이터 필터링도 받을 수 있습니다.
+
+이게 어떻게 동작할까요? 확인해 봅시다. 🤓
+
+### 타입 어노테이션과 도구 지원 { #type-annotations-and-tooling }
+
+먼저 에디터, mypy 및 기타 도구가 이를 어떻게 보는지 살펴봅시다.
+
+`BaseUser`는 기본 필드를 가집니다. 그리고 `UserIn`은 `BaseUser`를 상속하고 `password` 필드를 추가하므로, 두 모델의 모든 필드를 포함하게 됩니다.
+
+함수 반환 타입을 `BaseUser`로 어노테이션하지만, 실제로는 `UserIn` 인스턴스를 반환합니다.
+
+에디터, mypy 및 기타 도구는 이에 대해 불평하지 않습니다. 타이핑 관점에서 `UserIn`은 `BaseUser`의 서브클래스이므로, `BaseUser`인 어떤 것이 기대되는 곳에서는 *유효한* 타입이기 때문입니다.
+
+### FastAPI 데이터 필터링 { #fastapi-data-filtering }
+
+이제 FastAPI는 반환 타입을 보고, 여러분이 반환하는 값이 해당 타입에 선언된 필드 **만** 포함하도록 보장합니다.
+
+FastAPI는 Pydantic을 내부적으로 여러 방식으로 사용하여, 클래스 상속의 동일한 규칙이 반환 데이터 필터링에는 적용되지 않도록 합니다. 그렇지 않으면 기대한 것보다 훨씬 더 많은 데이터를 반환하게 될 수도 있습니다.
+
+이렇게 하면 **도구 지원**이 있는 타입 어노테이션과 **데이터 필터링**이라는 두 가지 장점을 모두 얻을 수 있습니다.
+
+## 문서에서 보기 { #see-it-in-the-docs }
+
+자동 생성 문서를 보면 입력 모델과 출력 모델이 각자의 JSON Schema를 가지고 있음을 확인할 수 있습니다:
@@ -83,29 +175,73 @@ FastAPI는 이 `response_model`를 사용하여:
-## 응답 모델 인코딩 매개변수
+## 기타 반환 타입 어노테이션 { #other-return-type-annotations }
+
+유효한 Pydantic 필드가 아닌 것을 반환하면서도, 도구(에디터, mypy 등)가 제공하는 지원을 받기 위해 함수에 어노테이션을 달아두는 경우가 있을 수 있습니다.
+
+### 응답을 직접 반환하기 { #return-a-response-directly }
+
+가장 흔한 경우는 [고급 문서에서 나중에 설명하는 대로 Response를 직접 반환하는 것](../advanced/response-directly.md){.internal-link target=_blank}입니다.
+
+{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *}
+
+이 간단한 경우는 반환 타입 어노테이션이 `Response` 클래스(또는 그 서브클래스)이기 때문에 FastAPI에서 자동으로 처리됩니다.
+
+그리고 `RedirectResponse`와 `JSONResponse`는 모두 `Response`의 서브클래스이므로, 타입 어노테이션이 올바르기 때문에 도구들도 만족합니다.
+
+### Response 서브클래스 어노테이션 { #annotate-a-response-subclass }
+
+타입 어노테이션에 `Response`의 서브클래스를 사용할 수도 있습니다:
+
+{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *}
+
+이는 `RedirectResponse`가 `Response`의 서브클래스이기 때문에 동작하며, FastAPI가 이 간단한 경우를 자동으로 처리합니다.
+
+### 유효하지 않은 반환 타입 어노테이션 { #invalid-return-type-annotations }
+
+하지만 유효한 Pydantic 타입이 아닌 다른 임의의 객체(예: 데이터베이스 객체)를 반환하고, 함수에서 그렇게 어노테이션하면, FastAPI는 그 타입 어노테이션으로부터 Pydantic 응답 모델을 만들려고 시도하다가 실패합니다.
+
+또한, 유효한 Pydantic 타입이 아닌 타입이 하나 이상 포함된 여러 타입 간의 union이 있는 경우에도 동일합니다. 예를 들어, 아래는 실패합니다 💥:
+
+{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
+
+...이는 타입 어노테이션이 Pydantic 타입이 아니고, 단일 `Response` 클래스/서브클래스도 아니며, `Response`와 `dict` 간 union(둘 중 아무거나)이기 때문에 실패합니다.
+
+### 응답 모델 비활성화 { #disable-response-model }
+
+위 예제에서 이어서, FastAPI가 수행하는 기본 데이터 검증, 문서화, 필터링 등을 원하지 않을 수 있습니다.
+
+하지만 에디터나 타입 체커(예: mypy) 같은 도구 지원을 받기 위해 함수에 반환 타입 어노테이션은 유지하고 싶을 수도 있습니다.
+
+이 경우 `response_model=None`으로 설정하여 응답 모델 생성을 비활성화할 수 있습니다:
+
+{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
+
+그러면 FastAPI는 응답 모델 생성을 건너뛰며, FastAPI 애플리케이션에 영향을 주지 않고 필요한 반환 타입 어노테이션을 어떤 것이든 사용할 수 있습니다. 🤓
+
+## 응답 모델 인코딩 매개변수 { #response-model-encoding-parameters }
응답 모델은 아래와 같이 기본값을 가질 수 있습니다:
-{* ../../docs_src/response_model/tutorial004.py hl[11,13:14] *}
+{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
-* `description: Optional[str] = None`은 기본값으로 `None`을 갖습니다.
+* `description: Union[str, None] = None` (또는 Python 3.10에서 `str | None = None`)은 기본값으로 `None`을 갖습니다.
* `tax: float = 10.5`는 기본값으로 `10.5`를 갖습니다.
-* `tags: List[str] = []` 빈 리스트의 기본값으로: `[]`.
+* `tags: List[str] = []`는 기본값으로 빈 리스트 `[]`를 갖습니다.
-그러나 실제로 저장되지 않았을 경우 결과에서 값을 생략하고 싶을 수 있습니다.
+하지만 실제로 저장되지 않았을 경우 결과에서 이를 생략하고 싶을 수 있습니다.
예를 들어, NoSQL 데이터베이스에 많은 선택적 속성이 있는 모델이 있지만, 기본값으로 가득 찬 매우 긴 JSON 응답을 보내고 싶지 않습니다.
-### `response_model_exclude_unset` 매개변수 사용
+### `response_model_exclude_unset` 매개변수 사용 { #use-the-response-model-exclude-unset-parameter }
-*경로 작동 데코레이터* 매개변수를 `response_model_exclude_unset=True`로 설정 할 수 있습니다:
+*경로 처리 데코레이터* 매개변수 `response_model_exclude_unset=True`로 설정할 수 있습니다:
-{* ../../docs_src/response_model/tutorial004.py hl[24] *}
+{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
-이러한 기본값은 응답에 포함되지 않고 실제로 설정된 값만 포함됩니다.
+그러면 이러한 기본값은 응답에 포함되지 않고, 실제로 설정된 값만 포함됩니다.
-따라서 해당 *경로 작동*에 ID가 `foo`인 항목(items)을 요청으로 보내면 (기본값을 제외한) 응답은 다음과 같습니다:
+따라서 ID가 `foo`인 항목에 대해 해당 *경로 처리*로 요청을 보내면, (기본값을 제외한) 응답은 다음과 같습니다:
```JSON
{
@@ -116,24 +252,18 @@ FastAPI는 이 `response_model`를 사용하여:
/// info | 정보
-FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 `exclude_unset` 매개변수를 사용합니다.
-
-///
-
-/// info | 정보
-
-아래 또한 사용할 수 있습니다:
+다음도 사용할 수 있습니다:
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
-Pydantic 문서에서 `exclude_defaults` 및 `exclude_none`에 대해 설명한 대로 사용할 수 있습니다.
+`exclude_defaults` 및 `exclude_none`에 대해 Pydantic 문서에 설명된 대로 사용할 수 있습니다.
///
-#### 기본값이 있는 필드를 갖는 값의 데이터
+#### 기본값이 있는 필드에 값이 있는 데이터 { #data-with-values-for-fields-with-defaults }
-하지만 모델의 필드가 기본값이 있어도 ID가 `bar`인 항목(items)처럼 데이터가 값을 갖는다면:
+하지만 ID가 `bar`인 항목처럼, 기본값이 있는 모델의 필드에 값이 있다면:
```Python hl_lines="3 5"
{
@@ -144,12 +274,11 @@ FastAPI는 이를 위해 Pydantic 모델의 `.dict()`의 `http.HTTPStatus` 와 같은 `IntEnum` 을 입력받을 수도 있습니다.
///
`status_code` 매개변수는:
* 응답에서 해당 상태 코드를 반환합니다.
-* 상태 코드를 OpenAPI 스키마(및 사용자 인터페이스)에 문서화 합니다.
+* 상태 코드를 OpenAPI 스키마(따라서, 사용자 인터페이스에도)에 문서화합니다:
-
+
/// note | 참고
-어떤 응답 코드들은 해당 응답에 본문이 없다는 것을 의미하기도 합니다 (다음 항목 참고).
+일부 응답 코드(다음 섹션 참고)는 응답에 본문이 없다는 것을 나타냅니다.
-이에 따라 FastAPI는 응답 본문이 없음을 명시하는 OpenAPI를 생성합니다.
+FastAPI는 이를 알고 있으며, 응답 본문이 없다고 명시하는 OpenAPI 문서를 생성합니다.
///
-## HTTP 상태 코드에 대하여
+## HTTP 상태 코드에 대하여 { #about-http-status-codes }
/// note | 참고
-만약 HTTP 상태 코드에 대하여 이미 알고있다면, 다음 항목으로 넘어가십시오.
+만약 HTTP 상태 코드가 무엇인지 이미 알고 있다면, 다음 섹션으로 넘어가세요.
///
-HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다.
+HTTP에서는 응답의 일부로 3자리 숫자 상태 코드를 보냅니다.
-이 상태 코드들은 각자를 식별할 수 있도록 지정된 이름이 있으나, 중요한 것은 숫자 코드입니다.
+이 상태 코드들은 이를 식별할 수 있도록 이름이 연결되어 있지만, 중요한 부분은 숫자입니다.
요약하자면:
-* `1xx` 상태 코드는 "정보"용입니다. 이들은 직접적으로는 잘 사용되지는 않습니다. 이 상태 코드를 갖는 응답들은 본문을 가질 수 없습니다.
-* **`2xx`** 상태 코드는 "성공적인" 응답을 위해 사용됩니다. 가장 많이 사용되는 유형입니다.
- * `200` 은 디폴트 상태 코드로, 모든 것이 "성공적임"을 의미합니다.
- * 다른 예로는 `201` "생성됨"이 있습니다. 일반적으로 데이터베이스에 새로운 레코드를 생성한 후 사용합니다.
- * 단, `204` "내용 없음"은 특별한 경우입니다. 이것은 클라이언트에게 반환할 내용이 없는 경우 사용합니다. 따라서 응답은 본문을 가질 수 없습니다.
-* **`3xx`** 상태 코드는 "리다이렉션"용입니다. 본문을 가질 수 없는 `304` "수정되지 않음"을 제외하고, 이 상태 코드를 갖는 응답에는 본문이 있을 수도, 없을 수도 있습니다.
-* **`4xx`** 상태 코드는 "클라이언트 오류" 응답을 위해 사용됩니다. 이것은 아마 가장 많이 사용하게 될 두번째 유형입니다.
- * 일례로 `404` 는 "찾을 수 없음" 응답을 위해 사용합니다.
- * 일반적인 클라이언트 오류의 경우 `400` 을 사용할 수 있습니다.
-* `5xx` 상태 코드는 서버 오류에 사용됩니다. 이것들을 직접 사용할 일은 거의 없습니다. 응용 프로그램 코드나 서버의 일부에서 문제가 발생하면 자동으로 이들 상태 코드 중 하나를 반환합니다.
+* `100 - 199` 는 "정보"용입니다. 직접 사용할 일은 거의 없습니다. 이 상태 코드를 갖는 응답은 본문을 가질 수 없습니다.
+* **`200 - 299`** 는 "성공적인" 응답을 위한 것입니다. 가장 많이 사용하게 될 유형입니다.
+ * `200` 은 기본 상태 코드로, 모든 것이 "OK"임을 의미합니다.
+ * 다른 예로는 `201` "생성됨"이 있습니다. 일반적으로 데이터베이스에 새 레코드를 생성한 후 사용합니다.
+ * 특별한 경우로 `204` "내용 없음"이 있습니다. 이 응답은 클라이언트에게 반환할 내용이 없을 때 사용되며, 따라서 응답은 본문을 가지면 안 됩니다.
+* **`300 - 399`** 는 "리다이렉션"용입니다. 이 상태 코드를 갖는 응답은 본문이 있을 수도 없을 수도 있으며, 본문이 없어야 하는 `304` "수정되지 않음"을 제외합니다.
+* **`400 - 499`** 는 "클라이언트 오류" 응답을 위한 것입니다. 아마 두 번째로 가장 많이 사용하게 될 유형입니다.
+ * 예를 들어 `404` 는 "찾을 수 없음" 응답을 위해 사용합니다.
+ * 클라이언트의 일반적인 오류에는 `400` 을 그냥 사용할 수 있습니다.
+* `500 - 599` 는 서버 오류에 사용됩니다. 직접 사용할 일은 거의 없습니다. 애플리케이션 코드의 일부나 서버에서 문제가 발생하면 자동으로 이들 상태 코드 중 하나를 반환합니다.
/// tip | 팁
-각각의 상태 코드와 이들이 의미하는 내용에 대해 더 알고싶다면 MDN HTTP 상태 코드에 관한 문서 를 확인하십시오.
+각 상태 코드와 어떤 코드가 어떤 용도인지 더 알고 싶다면 MDN의 HTTP 상태 코드에 관한 문서를 확인하세요.
///
-## 이름을 기억하는 쉬운 방법
+## 이름을 기억하는 쉬운 방법 { #shortcut-to-remember-the-names }
-상기 예시 참고:
+이전 예시를 다시 확인해보겠습니다:
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
-`201` 은 "생성됨"를 의미하는 상태 코드입니다.
+`201` 은 "생성됨"을 위한 상태 코드입니다.
-하지만 모든 상태 코드들이 무엇을 의미하는지 외울 필요는 없습니다.
+하지만 각각의 코드가 무엇을 의미하는지 외울 필요는 없습니다.
`fastapi.status` 의 편의 변수를 사용할 수 있습니다.
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *}
-이것은 단순히 작업을 편리하게 하기 위한 것으로, HTTP 상태 코드와 동일한 번호를 갖고있지만, 이를 사용하면 편집기의 자동완성 기능을 사용할 수 있습니다:
+이것들은 단지 편의를 위한 것으로, 동일한 숫자를 갖고 있지만, 이를 통해 편집기의 자동완성 기능으로 찾을 수 있습니다:
-
+
-/// note | 기술적 세부사항
+/// note | 기술 세부사항
`from starlette import status` 역시 사용할 수 있습니다.
@@ -96,6 +96,6 @@ HTTP는 세자리의 숫자 상태 코드를 응답의 일부로 전송합니다
///
-## 기본값 변경
+## 기본값 변경 { #changing-the-default }
-추후 여기서 선언하는 기본 상태 코드가 아닌 다른 상태 코드를 반환하는 방법을 [숙련된 사용자 지침서](https://fastapi.tiangolo.com/ko/advanced/response-change-status-code/){.internal-link target=_blank}에서 확인할 수 있습니다.
+나중에 [고급 사용자 지침서](../advanced/response-change-status-code.md){.internal-link target=_blank}에서, 여기서 선언하는 기본값과 다른 상태 코드를 반환하는 방법을 확인할 수 있습니다.
diff --git a/docs/ko/docs/tutorial/schema-extra-example.md b/docs/ko/docs/tutorial/schema-extra-example.md
index 77e94db72..b2b54836a 100644
--- a/docs/ko/docs/tutorial/schema-extra-example.md
+++ b/docs/ko/docs/tutorial/schema-extra-example.md
@@ -1,43 +1,21 @@
-# 요청 예제 데이터 선언
+# 요청 예제 데이터 선언 { #declare-request-example-data }
여러분의 앱이 받을 수 있는 데이터 예제를 선언할 수 있습니다.
여기 이를 위한 몇가지 방식이 있습니다.
-## Pydantic 모델 속 추가 JSON 스키마 데이터
+## Pydantic 모델 속 추가 JSON 스키마 데이터 { #extra-json-schema-data-in-pydantic-models }
생성된 JSON 스키마에 추가될 Pydantic 모델을 위한 `examples`을 선언할 수 있습니다.
-//// 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에서 Pydantic 공식 문서: Model Config에 나와 있는 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 것입니다.
+Pydantic 문서: Configuration에 설명된 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 수 있습니다.
`"json_schema_extra"`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
-////
-
-//// tab | Pydantic v1
-
-Pydantic v1에서 Pydantic 공식 문서: Schema customization에서 설명하는 것처럼, 내부 클래스인 `Config`와 `schema_extra`를 사용할 것입니다.
-
-`schema_extra`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
-
-////
-
/// tip | 팁
JSON 스키마를 확장하고 여러분의 별도의 자체 데이터를 추가하기 위해 같은 기술을 사용할 수 있습니다.
@@ -52,19 +30,19 @@ JSON 스키마를 확장하고 여러분의 별도의 자체 데이터를 추가
그 전에는, 하나의 예제만 가능한 `example` 키워드만 지원했습니다. 이는 아직 OpenAPI 3.1.0에서 지원하지만, 지원이 종료될 것이며 JSON 스키마 표준에 포함되지 않습니다. 그렇기에 `example`을 `examples`으로 이전하는 것을 추천합니다. 🤓
-이 문서 끝에 더 많은 읽을거리가 있습니다.
+이 페이지 끝에서 더 많은 내용을 읽을 수 있습니다.
///
-## `Field` 추가 인자
+## `Field` 추가 인자 { #field-additional-arguments }
Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를 선언할 수 있습니다:
{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
-## JSON Schema에서의 `examples` - OpenAPI
+## JSON Schema에서의 `examples` - OpenAPI { #examples-in-json-schema-openapi }
-이들 중에서 사용합니다:
+다음 중 하나를 사용할 때:
* `Path()`
* `Query()`
@@ -74,45 +52,45 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
* `Form()`
* `File()`
-**OpenAPI**의 **JSON 스키마**에 추가될 부가적인 정보를 포함한 `examples` 모음을 선언할 수 있습니다.
+**OpenAPI** 안의 **JSON 스키마**에 추가될 부가적인 정보를 포함한 `examples` 모음을 선언할 수도 있습니다.
-### `examples`를 포함한 `Body`
+### `examples`를 포함한 `Body` { #body-with-examples }
여기, `Body()`에 예상되는 예제 데이터 하나를 포함한 `examples`를 넘겼습니다:
{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
-### 문서 UI 예시
+### 문서 UI 예시 { #example-in-the-docs-ui }
위의 어느 방법과 함께라면 `/docs`에서 다음과 같이 보일 것입니다:
-### 다중 `examples`를 포함한 `Body`
+### 다중 `examples`를 포함한 `Body` { #body-with-multiple-examples }
물론 여러 `examples`를 넘길 수 있습니다:
{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
-이와 같이 하면 이 예제는 그 본문 데이터를 위한 내부 **JSON 스키마**의 일부가 될 것입니다.
+이와 같이 하면 예제들은 그 본문 데이터의 내부 **JSON 스키마**의 일부가 될 것입니다.
그럼에도 불구하고, 지금 이 문서를 작성하는 시간에, 문서 UI를 보여주는 역할을 맡은 Swagger UI는 **JSON 스키마** 속 데이터를 위한 여러 예제의 표현을 지원하지 않습니다. 하지만 해결 방안을 밑에서 읽어보세요.
-### OpenAPI-특화 `examples`
+### OpenAPI-특화 `examples` { #openapi-specific-examples }
-**JSON 스키마**가 `examples`를 지원하기 전 부터, OpenAPI는 `examples`이라 불리는 다른 필드를 지원해 왔습니다.
+**JSON 스키마**가 `examples`를 지원하기 전부터 OpenAPI는 `examples`이라 불리는 다른 필드를 지원해 왔습니다.
-이 **OpenAPI-특화** `examples`는 OpenAPI 명세서의 다른 구역으로 들어갑니다. 각 JSON 스키마 내부가 아니라 **각 *경로 작동* 세부 정보**에 포함됩니다.
+이 **OpenAPI-특화** `examples`는 OpenAPI 명세서의 다른 구역으로 들어갑니다. 각 JSON 스키마 내부가 아니라 **각 *경로 처리* 세부 정보**에 포함됩니다.
그리고 Swagger UI는 이 특정한 `examples` 필드를 한동안 지원했습니다. 그래서, 이를 다른 **문서 UI에 있는 예제**를 **표시**하기 위해 사용할 수 있습니다.
-이 OpenAPI-특화 필드인 `examples`의 형태는 (`list`대신에) **다중 예제**가 포함된 `dict`이며, 각각의 별도 정보 또한 **OpenAPI**에 추가될 것입니다.
+이 OpenAPI-특화 필드인 `examples`의 형태는 (`list` 대신에) **다중 예제**가 포함된 `dict`이며, 각각의 별도 정보 또한 **OpenAPI**에 추가될 것입니다.
-이는 OpenAPI에 포함된 JSON 스키마 안으로 포함되지 않으며, *경로 작동*에 직접적으로 포함됩니다.
+이는 OpenAPI에 포함된 각 JSON 스키마 안으로 포함되지 않으며, *경로 처리*에 직접적으로 포함됩니다.
-### `openapi_examples` 매개변수 사용하기
+### `openapi_examples` 매개변수 사용하기 { #using-the-openapi-examples-parameter }
-다음 예시 속에 OpenAPI-특화 `examples`를 FastAPI 안에서 매개변수 `openapi_examples` 매개변수와 함께 선언할 수 있습니다:
+다음에 대해 FastAPI에서 매개변수 `openapi_examples`로 OpenAPI-특화 `examples`를 선언할 수 있습니다:
* `Path()`
* `Query()`
@@ -122,26 +100,26 @@ Pydantic 모델과 같이 `Field()`를 사용할 때 추가적인 `examples`를
* `Form()`
* `File()`
-`dict`의 키가 또 다른 `dict`인 각 예제와 값을 구별합니다.
+`dict`의 키는 각 예제를 식별하고, 각 값은 또 다른 `dict`입니다.
-각각의 특정 `examples` 속 `dict` 예제는 다음을 포함할 수 있습니다:
+`examples` 안의 각 특정 예제 `dict`에는 다음이 포함될 수 있습니다:
* `summary`: 예제에 대한 짧은 설명문.
* `description`: 마크다운 텍스트를 포함할 수 있는 긴 설명문.
* `value`: 실제로 보여지는 예시, 예를 들면 `dict`.
-* `externalValue`: `value`의 대안이며 예제를 가르키는 URL. 비록 `value`처럼 많은 도구를 지원하지 못할 수 있습니다.
+* `externalValue`: `value`의 대안이며 예제를 가리키는 URL. 비록 `value`처럼 많은 도구를 지원하지 못할 수 있습니다.
이를 다음과 같이 사용할 수 있습니다:
{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
-### 문서 UI에서의 OpenAPI 예시
+### 문서 UI에서의 OpenAPI 예시 { #openapi-examples-in-the-docs-ui }
-`Body()`에 추가된 `openapi_examples`를 포함한 `/docs`는 다음과 같이 보일 것입니다:
+`Body()`에 `openapi_examples`가 추가되면 `/docs`는 다음과 같이 보일 것입니다:
-## 기술적 세부 사항
+## 기술적 세부 사항 { #technical-details }
/// tip | 팁
@@ -167,12 +145,12 @@ JSON 스키마는 `examples`를 가지고 있지 않았고, 따라서 OpenAPI는
OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분에 추가했습니다:
-* `(명세서에 있는) Parameter Object`는 FastAPI의 다음 기능에서 쓰였습니다:
+* `Parameter Object` (명세서에 있는)는 FastAPI의 다음 기능에서 쓰였습니다:
* `Path()`
* `Query()`
* `Header()`
* `Cookie()`
-* (명세서에 있는)`Media Type Object`속 `content`에 있는 `Request Body Object`는 FastAPI의 다음 기능에서 쓰였습니다:
+* `Request Body Object`, `Media Type Object` (명세서에 있는)의 `content` 필드에 있는는 FastAPI의 다음 기능에서 쓰였습니다:
* `Body()`
* `File()`
* `Form()`
@@ -183,15 +161,15 @@ OpenAPI는 또한 `example`과 `examples` 필드를 명세서의 다른 부분
///
-### JSON 스키마의 `examples` 필드
+### JSON 스키마의 `examples` 필드 { #json-schemas-examples-field }
-하지만, 후에 JSON 스키마는 `examples`필드를 명세서의 새 버전에 추가했습니다.
+하지만, 후에 JSON 스키마는 `examples` 필드를 명세서의 새 버전에 추가했습니다.
그리고 새로운 OpenAPI 3.1.0은 이 새로운 `examples` 필드가 포함된 최신 버전 (JSON 스키마 2020-12)을 기반으로 했습니다.
-이제 새로운 `examples` 필드는 이전의 단일 (그리고 커스텀) `example` 필드보다 우선되며, `example`은 사용하지 않는 것이 좋습니다.
+그리고 이제 이 새로운 `examples` 필드는 이제 지원 중단된, 예전의 단일 (그리고 커스텀) `example` 필드보다 우선됩니다.
-JSON 스키마의 새로운 `examples` 필드는 예제 속 **단순한 `list`**이며, (위에서 상술한 것처럼) OpenAPI의 다른 곳에 존재하는 dict으로 된 추가적인 메타데이터가 아닙니다.
+JSON 스키마의 새로운 `examples` 필드는 예제의 **단순한 `list`**일 뿐이며, (위에서 상술한 것처럼) OpenAPI의 다른 곳에 존재하는 추가 메타데이터가 있는 dict가 아닙니다.
/// info | 정보
@@ -201,24 +179,24 @@ JSON 스키마의 새로운 `examples` 필드는 예제 속 **단순한 `list`**
///
-### Pydantic과 FastAPI `examples`
+### Pydantic과 FastAPI `examples` { #pydantic-and-fastapi-examples }
-`examples`를 Pydantic 모델 속에 추가할 때, `schema_extra` 혹은 `Field(examples=["something"])`를 사용하면 Pydantic 모델의 **JSON 스키마**에 해당 예시가 추가됩니다.
+Pydantic 모델 안에 `examples`를 추가할 때, `schema_extra` 또는 `Field(examples=["something"])`를 사용하면 그 예제는 해당 Pydantic 모델의 **JSON 스키마**에 추가됩니다.
그리고 Pydantic 모델의 **JSON 스키마**는 API의 **OpenAPI**에 포함되고, 그 후 문서 UI 속에서 사용됩니다.
-FastAPI 0.99.0 이전 버전에서 (0.99.0 이상 버전은 새로운 OpenAPI 3.1.0을 사용합니다), `example` 혹은 `examples`를 다른 유틸리티(`Query()`, `Body()` 등)와 함께 사용했을 때, 저러한 예시는 데이터를 설명하는 JSON 스키마에 추가되지 않으며 (심지어 OpenAPI의 자체 JSON 스키마에도 포함되지 않습니다), OpenAPI의 *경로 작동* 선언에 직접적으로 추가됩니다 (JSON 스키마를 사용하는 OpenAPI 부분 외에도).
+FastAPI 0.99.0 이전 버전에서 (0.99.0 이상 버전은 새로운 OpenAPI 3.1.0을 사용합니다), 다른 유틸리티(`Query()`, `Body()` 등)와 함께 `example` 또는 `examples`를 사용했을 때, 그러한 예제는 그 데이터를 설명하는 JSON 스키마에 추가되지 않고 (OpenAPI 자체의 JSON 스키마에도 포함되지 않습니다), OpenAPI의 *경로 처리* 선언에 직접적으로 추가됩니다 (JSON 스키마를 사용하는 OpenAPI 부분 밖에서).
-하지만 지금은 FastAPI 0.99.0 및 이후 버전에서는 JSON 스키마 2020-12를 사용하는 OpenAPI 3.1.0과 Swagger UI 5.0.0 및 이후 버전을 사용하며, 모든 것이 더 일관성을 띄고 예시는 JSON 스키마에 포함됩니다.
+하지만 이제 FastAPI 0.99.0 및 이후 버전에서는 JSON 스키마 2020-12를 사용하는 OpenAPI 3.1.0과 Swagger UI 5.0.0 및 이후 버전을 사용하기 때문에, 모든 것이 더 일관성을 띄고 예제도 JSON 스키마에 포함됩니다.
-### Swagger UI와 OpenAPI-특화 `examples`
+### Swagger UI와 OpenAPI-특화 `examples` { #swagger-ui-and-openapi-specific-examples }
-현재 (2023-08-26), Swagger UI가 다중 JSON 스키마 예시를 지원하지 않으며, 사용자는 다중 예시를 문서에 표시하는 방법이 없었습니다.
+Swagger UI는 다중 JSON 스키마 예제를 지원하지 않았기 때문에(2023-08-26 기준), 사용자는 문서에 여러 예제를 표시할 방법이 없었습니다.
-이를 해결하기 위해, FastAPI `0.103.0`은 새로운 매개변수인 `openapi_examples`를 포함하는 예전 **OpenAPI-특화** `examples` 필드를 선언하기 위한 **지원을 추가**했습니다. 🤓
+이를 해결하기 위해, FastAPI `0.103.0`은 새로운 매개변수인 `openapi_examples`로 동일한 예전 **OpenAPI-특화** `examples` 필드를 선언하는 **지원**을 추가했습니다. 🤓
-### 요약
+### 요약 { #summary }
-저는 역사를 그다지 좋아하는 편이 아니라고 말하고는 했지만... "기술 역사" 강의를 가르치는 지금의 저를 보세요.
+저는 역사를 그다지 좋아하는 편이 아니라고 말하고는 했지만... "기술 역사" 강의를 하는 지금의 저를 보세요. 😅
-요약하자면 **FastAPI 0.99.0 혹은 그 이상의 버전**으로 업그레이드하는 것은 많은 것들이 더 **쉽고, 일관적이며 직관적이게** 되며, 여러분은 이 모든 역사적 세부 사항을 알 필요가 없습니다. 😎
+요약하자면 **FastAPI 0.99.0 혹은 그 이상의 버전**으로 업그레이드하면, 많은 것들이 훨씬 더 **단순하고, 일관적이며 직관적**이 되며, 여러분은 이 모든 역사적 세부 사항을 알 필요가 없습니다. 😎
diff --git a/docs/ko/docs/tutorial/security/first-steps.md b/docs/ko/docs/tutorial/security/first-steps.md
new file mode 100644
index 000000000..4c9181b31
--- /dev/null
+++ b/docs/ko/docs/tutorial/security/first-steps.md
@@ -0,0 +1,203 @@
+# 보안 - 첫 단계 { #security-first-steps }
+
+어떤 도메인에 **backend** API가 있다고 가정해 보겠습니다.
+
+그리고 다른 도메인에 **frontend**가 있거나, 같은 도메인의 다른 경로에 있거나(또는 모바일 애플리케이션에 있을 수도 있습니다).
+
+그리고 frontend가 **username**과 **password**를 사용해 backend에 인증할 수 있는 방법이 필요하다고 해봅시다.
+
+**FastAPI**와 함께 **OAuth2**를 사용해서 이를 구현할 수 있습니다.
+
+하지만 필요한 작은 정보 조각들을 찾기 위해 길고 긴 전체 스펙을 읽느라 시간을 쓰지 않도록 하겠습니다.
+
+보안을 처리하기 위해 **FastAPI**가 제공하는 도구들을 사용해 봅시다.
+
+## 어떻게 보이는지 { #how-it-looks }
+
+먼저 코드를 그냥 사용해서 어떻게 동작하는지 보고, 그다음에 무슨 일이 일어나는지 이해하러 다시 돌아오겠습니다.
+
+## `main.py` 만들기 { #create-main-py }
+
+예제를 파일 `main.py`에 복사하세요:
+
+{* ../../docs_src/security/tutorial001_an_py39.py *}
+
+## 실행하기 { #run-it }
+
+/// info | 정보
+
+`python-multipart` 패키지는 `pip install "fastapi[standard]"` 명령을 실행하면 **FastAPI**와 함께 자동으로 설치됩니다.
+
+하지만 `pip install fastapi` 명령을 사용하면 `python-multipart` 패키지가 기본으로 포함되지 않습니다.
+
+수동으로 설치하려면, [가상 환경](../../virtual-environments.md){.internal-link target=_blank}을 만들고 활성화한 다음, 아래로 설치하세요:
+
+```console
+$ pip install python-multipart
+```
+
+이는 **OAuth2**가 `username`과 `password`를 보내기 위해 "form data"를 사용하기 때문입니다.
+
+///
+
+다음으로 예제를 실행하세요:
+
+
+
+/// check | Authorize 버튼!
+
+반짝이는 새 "Authorize" 버튼이 이미 있습니다.
+
+그리고 *경로 처리*에는 오른쪽 상단에 클릭할 수 있는 작은 자물쇠가 있습니다.
+
+///
+
+그리고 이를 클릭하면 `username`과 `password`(그리고 다른 선택적 필드들)를 입력할 수 있는 작은 인증 폼이 나타납니다:
+
+
+
+/// note | 참고
+
+폼에 무엇을 입력하든 아직은 동작하지 않습니다. 하지만 곧 여기까지 구현할 것입니다.
+
+///
+
+물론 이것은 최종 사용자를 위한 frontend는 아니지만, 모든 API를 대화형으로 문서화하는 훌륭한 자동 도구입니다.
+
+frontend 팀(그게 본인일 수도 있습니다)이 사용할 수 있습니다.
+
+서드파티 애플리케이션과 시스템에서도 사용할 수 있습니다.
+
+그리고 동일한 애플리케이션을 디버그하고, 확인하고, 테스트하기 위해 본인이 사용할 수도 있습니다.
+
+## `password` 플로우 { #the-password-flow }
+
+이제 조금 돌아가서 이것들이 무엇인지 이해해 봅시다.
+
+`password` "flow"는 보안과 인증을 처리하기 위해 OAuth2에서 정의한 여러 방식("flows") 중 하나입니다.
+
+OAuth2는 backend 또는 API가 사용자를 인증하는 서버와 독립적일 수 있도록 설계되었습니다.
+
+하지만 이 경우에는 같은 **FastAPI** 애플리케이션이 API와 인증을 모두 처리합니다.
+
+따라서, 단순화된 관점에서 다시 정리해보면:
+
+* 사용자가 frontend에서 `username`과 `password`를 입력하고 `Enter`를 누릅니다.
+* frontend(사용자의 브라우저에서 실행됨)는 해당 `username`과 `password`를 우리 API의 특정 URL로 보냅니다(`tokenUrl="token"`로 선언됨).
+* API는 `username`과 `password`를 확인하고 "token"으로 응답합니다(아직 아무것도 구현하지 않았습니다).
+ * "token"은 나중에 이 사용자를 검증하는 데 사용할 수 있는 어떤 내용이 담긴 문자열일 뿐입니다.
+ * 보통 token은 일정 시간이 지나면 만료되도록 설정합니다.
+ * 그래서 사용자는 나중에 어느 시점엔 다시 로그인해야 합니다.
+ * 그리고 token이 도난당하더라도 위험이 더 낮습니다. 대부분의 경우 영구적으로 항상 동작하는 키와는 다릅니다.
+* frontend는 그 token을 임시로 어딘가에 저장합니다.
+* 사용자가 frontend에서 클릭해서 frontend 웹 앱의 다른 섹션으로 이동합니다.
+* frontend는 API에서 더 많은 데이터를 가져와야 합니다.
+ * 하지만 그 특정 endpoint에는 인증이 필요합니다.
+ * 그래서 우리 API에 인증하기 위해 `Authorization` 헤더를, 값은 `Bearer `에 token을 더한 형태로 보냅니다.
+ * token에 `foobar`가 들어 있다면 `Authorization` 헤더의 내용은 `Bearer foobar`가 됩니다.
+
+## **FastAPI**의 `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }
+
+**FastAPI**는 이런 보안 기능을 구현하기 위해, 서로 다른 추상화 수준에서 여러 도구를 제공합니다.
+
+이 예제에서는 **OAuth2**의 **Password** 플로우와 **Bearer** token을 사용합니다. 이를 위해 `OAuth2PasswordBearer` 클래스를 사용합니다.
+
+/// info | 정보
+
+"bearer" token만이 유일한 선택지는 아닙니다.
+
+하지만 이 사용 사례에는 가장 적합한 선택입니다.
+
+또한 OAuth2 전문가로서 왜 다른 옵션이 더 적합한지 정확히 아는 경우가 아니라면, 대부분의 사용 사례에도 가장 적합할 가능성이 큽니다.
+
+그런 경우를 위해서도 **FastAPI**는 이를 구성할 수 있는 도구를 제공합니다.
+
+///
+
+`OAuth2PasswordBearer` 클래스의 인스턴스를 만들 때 `tokenUrl` 파라미터를 전달합니다. 이 파라미터에는 클라이언트(사용자의 브라우저에서 실행되는 frontend)가 token을 받기 위해 `username`과 `password`를 보낼 URL이 들어 있습니다.
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
+
+/// 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} 같은 고급 사용 사례에서도 애플리케이션이 계속 동작하도록 보장하는 데 중요합니다.
+
+///
+
+이 파라미터는 그 endpoint / *경로 처리*를 만들지는 않지만, URL `/token`이 클라이언트가 token을 얻기 위해 사용해야 할 URL이라고 선언합니다. 이 정보는 OpenAPI에 사용되고, 이어서 대화형 API 문서 시스템에서도 사용됩니다.
+
+곧 실제 경로 처리를 만들 것입니다.
+
+/// info | 정보
+
+엄격한 "Pythonista"라면 `token_url` 대신 `tokenUrl` 같은 파라미터 이름 스타일이 마음에 들지 않을 수도 있습니다.
+
+이는 OpenAPI 스펙에서 사용하는 이름과 동일하게 맞춘 것이기 때문입니다. 그래서 이런 보안 스킴에 대해 더 조사해야 할 때, 그대로 복사해서 붙여 넣어 더 많은 정보를 찾을 수 있습니다.
+
+///
+
+`oauth2_scheme` 변수는 `OAuth2PasswordBearer`의 인스턴스이지만, "callable"이기도 합니다.
+
+다음처럼 호출될 수 있습니다:
+
+```Python
+oauth2_scheme(some, parameters)
+```
+
+따라서 `Depends`와 함께 사용할 수 있습니다.
+
+### 사용하기 { #use-it }
+
+이제 `Depends`로 `oauth2_scheme`를 의존성에 전달할 수 있습니다.
+
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
+
+이 의존성은 `str`을 제공하고, 그 값은 *경로 처리 함수*의 파라미터 `token`에 할당됩니다.
+
+**FastAPI**는 이 의존성을 사용해 OpenAPI 스키마(및 자동 API 문서)에 "security scheme"를 정의할 수 있다는 것을 알게 됩니다.
+
+/// info | 기술 세부사항
+
+**FastAPI**는 (의존성에 선언된) `OAuth2PasswordBearer` 클래스를 사용해 OpenAPI에서 보안 스킴을 정의할 수 있다는 것을 알고 있습니다. 이는 `OAuth2PasswordBearer`가 `fastapi.security.oauth2.OAuth2`를 상속하고, 이것이 다시 `fastapi.security.base.SecurityBase`를 상속하기 때문입니다.
+
+OpenAPI(및 자동 API 문서)와 통합되는 모든 보안 유틸리티는 `SecurityBase`를 상속하며, 그래서 **FastAPI**가 이를 OpenAPI에 어떻게 통합할지 알 수 있습니다.
+
+///
+
+## 무엇을 하는지 { #what-it-does }
+
+요청에서 `Authorization` 헤더를 찾아, 값이 `Bearer `에 어떤 token이 붙은 형태인지 확인한 뒤, 그 token을 `str`로 반환합니다.
+
+`Authorization` 헤더가 없거나, 값에 `Bearer ` token이 없다면, 곧바로 401 상태 코드 오류(`UNAUTHORIZED`)로 응답합니다.
+
+오류를 반환하기 위해 token이 존재하는지 직접 확인할 필요조차 없습니다. 함수가 실행되었다면 그 token에는 `str`이 들어 있다고 확신할 수 있습니다.
+
+대화형 문서에서 이미 시도해 볼 수 있습니다:
+
+
+
+아직 token의 유효성을 검증하진 않지만, 이것만으로도 시작은 된 셈입니다.
+
+## 요약 { #recap }
+
+즉, 추가로 3~4줄만으로도 이미 원시적인 형태의 보안을 갖추게 됩니다.
diff --git a/docs/ko/docs/tutorial/security/get-current-user.md b/docs/ko/docs/tutorial/security/get-current-user.md
index 98ef3885e..f21a22b7a 100644
--- a/docs/ko/docs/tutorial/security/get-current-user.md
+++ b/docs/ko/docs/tutorial/security/get-current-user.md
@@ -1,105 +1,105 @@
-# 현재 사용자 가져오기
+# 현재 사용자 가져오기 { #get-current-user }
-이전 장에서 (의존성 주입 시스템을 기반으로 한)보안 시스템은 *경로 작동 함수*에서 `str`로 `token`을 제공했습니다:
+이전 장에서 (의존성 주입 시스템을 기반으로 한) 보안 시스템은 *경로 처리 함수*에 `str`로 `token`을 제공했습니다:
-{* ../../docs_src/security/tutorial001.py hl[10] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
-그러나 아직도 유용하지 않습니다.
+하지만 이는 여전히 그다지 유용하지 않습니다.
-현재 사용자를 제공하도록 합시다.
+현재 사용자를 제공하도록 해봅시다.
-## 유저 모델 생성하기
+## 사용자 모델 생성하기 { #create-a-user-model }
-먼저 Pydantic 유저 모델을 만들어 보겠습니다.
+먼저 Pydantic 사용자 모델을 만들어 봅시다.
-Pydantic을 사용하여 본문을 선언하는 것과 같은 방식으로 다른 곳에서 사용할 수 있습니다.
+Pydantic을 사용해 본문을 선언하는 것과 같은 방식으로, 다른 곳에서도 어디서든 사용할 수 있습니다:
-{* ../../docs_src/security/tutorial002.py hl[5,12:16] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
-## `get_current_user` 의존성 생성하기
+## `get_current_user` 의존성 생성하기 { #create-a-get-current-user-dependency }
의존성 `get_current_user`를 만들어 봅시다.
-의존성이 하위 의존성을 가질 수 있다는 것을 기억하십니까?
+의존성이 하위 의존성을 가질 수 있다는 것을 기억하시나요?
-`get_current_user`는 이전에 생성한 것과 동일한 `oauth2_scheme`과 종속성을 갖게 됩니다.
+`get_current_user`는 이전에 생성한 것과 동일한 `oauth2_scheme`에 대한 의존성을 갖게 됩니다.
-이전에 *경로 작동*에서 직접 수행했던 것과 동일하게 새 종속성 `get_current_user`는 하위 종속성 `oauth2_scheme`에서 `str`로 `token`을 수신합니다.
+이전에 *경로 처리*에서 직접 수행했던 것과 동일하게, 새 의존성 `get_current_user`는 하위 의존성 `oauth2_scheme`로부터 `str`로 `token`을 받게 됩니다:
-{* ../../docs_src/security/tutorial002.py hl[25] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
-## 유저 가져오기
+## 사용자 가져오기 { #get-the-user }
-`get_current_user`는 토큰을 `str`로 취하고 Pydantic `User` 모델을 반환하는 우리가 만든 (가짜) 유틸리티 함수를 사용합니다.
+`get_current_user`는 우리가 만든 (가짜) 유틸리티 함수를 사용합니다. 이 함수는 `str`로 토큰을 받아 Pydantic `User` 모델을 반환합니다:
-{* ../../docs_src/security/tutorial002.py hl[19:22,26:27] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
-## 현재 유저 주입하기
+## 현재 사용자 주입하기 { #inject-the-current-user }
-이제 *경로 작동*에서 `get_current_user`와 동일한 `Depends`를 사용할 수 있습니다.
+이제 *경로 처리*에서 `get_current_user`와 함께 같은 `Depends`를 사용할 수 있습니다:
-{* ../../docs_src/security/tutorial002.py hl[31] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
-Pydantic 모델인 `User`로 `current_user`의 타입을 선언하는 것을 알아야 합니다.
+`current_user`의 타입을 Pydantic 모델 `User`로 선언한다는 점에 주목하세요.
-이것은 모든 완료 및 타입 검사를 통해 함수 내부에서 우리를 도울 것입니다.
+이는 함수 내부에서 자동 완성과 타입 체크에 도움을 줍니다.
/// tip | 팁
-요청 본문도 Pydantic 모델로 선언된다는 것을 기억할 것입니다.
+요청 본문도 Pydantic 모델로 선언된다는 것을 기억하실지도 모릅니다.
-여기서 **FastAPI**는 `Depends`를 사용하고 있기 때문에 혼동되지 않습니다.
+여기서 **FastAPI**는 `Depends`를 사용하고 있기 때문에 혼동하지 않습니다.
///
/// check | 확인
-이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 다양한 의존성(다른 "의존적인")을 가질 수 있도록 합니다.
+이 의존성 시스템이 설계된 방식은 모두 `User` 모델을 반환하는 서로 다른 의존성(서로 다른 "dependables")을 가질 수 있도록 합니다.
-해당 타입의 데이터를 반환할 수 있는 의존성이 하나만 있는 것으로 제한되지 않습니다.
+해당 타입의 데이터를 반환할 수 있는 의존성이 하나만 있어야 하는 것으로 제한되지 않습니다.
///
-## 다른 모델
+## 다른 모델 { #other-models }
-이제 *경로 작동 함수*에서 현재 사용자를 직접 가져올 수 있으며 `Depends`를 사용하여 **의존성 주입** 수준에서 보안 메커니즘을 처리할 수 있습니다.
+이제 *경로 처리 함수*에서 현재 사용자를 직접 가져올 수 있으며, `Depends`를 사용해 **의존성 주입** 수준에서 보안 메커니즘을 처리할 수 있습니다.
-그리고 보안 요구 사항에 대한 모든 모델 또는 데이터를 사용할 수 있습니다(이 경우 Pydantic 모델 `User`).
+그리고 보안 요구 사항을 위해 어떤 모델이나 데이터든 사용할 수 있습니다(이 경우 Pydantic 모델 `User`).
-그러나 일부 특정 데이터 모델, 클래스 또는 타입을 사용하도록 제한되지 않습니다.
+하지만 특정 데이터 모델, 클래스 또는 타입만 사용해야 하는 것은 아닙니다.
-모델에 `id`와 `email`이 있고 `username`이 없길 원하십니까? 맞습니다. 이들은 동일한 도구를 사용할 수 있습니다.
+모델에 `id`와 `email`이 있고 `username`은 없게 하고 싶으신가요? 물론입니다. 같은 도구를 사용할 수 있습니다.
-`str`만 갖고 싶습니까? 아니면 그냥 `dict`를 갖고 싶습니까? 아니면 데이터베이스 클래스 모델 인스턴스를 직접 갖고 싶습니까? 그들은 모두 같은 방식으로 작동합니다.
+`str`만 갖고 싶으신가요? 아니면 `dict`만요? 또는 데이터베이스 클래스 모델 인스턴스를 직접 쓰고 싶으신가요? 모두 같은 방식으로 동작합니다.
-실제로 애플리케이션에 로그인하는 사용자가 없지만 액세스 토큰만 있는 로봇, 봇 또는 기타 시스템이 있습니까? 다시 말하지만 모두 동일하게 작동합니다.
+애플리케이션에 로그인하는 사용자는 없고, 액세스 토큰만 가진 로봇, 봇 또는 다른 시스템만 있나요? 이것도 마찬가지로 모두 동일하게 동작합니다.
-애플리케이션에 필요한 모든 종류의 모델, 모든 종류의 클래스, 모든 종류의 데이터베이스를 사용하십시오. **FastAPI**는 의존성 주입 시스템을 다루었습니다.
+애플리케이션에 필요한 어떤 종류의 모델, 어떤 종류의 클래스, 어떤 종류의 데이터베이스든 사용하세요. **FastAPI**는 의존성 주입 시스템으로 이를 지원합니다.
-## 코드 사이즈
+## 코드 크기 { #code-size }
-이 예는 장황해 보일 수 있습니다. 동일한 파일에서 보안, 데이터 모델, 유틸리티 기능 및 *경로 작동*을 혼합하고 있음을 염두에 두십시오.
+이 예시는 장황해 보일 수 있습니다. 동일한 파일에서 보안, 데이터 모델, 유틸리티 함수 및 *경로 처리*를 섞어서 사용하고 있다는 점을 기억하세요.
-그러나 이게 키포인트입니다.
+하지만 여기 핵심이 있습니다.
-보안과 종속성 주입 항목을 한 번만 작성하면 됩니다.
+보안과 의존성 주입 관련 코드는 한 번만 작성합니다.
-그리고 원하는 만큼 복잡하게 만들 수 있습니다. 그래도 유연성과 함께 한 곳에 한 번에 작성할 수 있습니다.
+그리고 원하는 만큼 복잡하게 만들 수 있습니다. 그럼에도 여전히 한 번만, 한 곳에만 작성하면 됩니다. 유연성을 모두 유지하면서요.
-그러나 동일한 보안 시스템을 사용하여 수천 개의 엔드포인트(*경로 작동*)를 가질 수 있습니다.
+하지만 같은 보안 시스템을 사용해 수천 개의 엔드포인트(*경로 처리*)를 가질 수 있습니다.
-그리고 그들 모두(또는 원하는 부분)는 이러한 의존성 또는 생성한 다른 의존성을 재사용하는 이점을 얻을 수 있습니다.
+그리고 그들 모두(또는 원하는 일부)는 이러한 의존성 또는 여러분이 생성한 다른 의존성을 재사용하는 이점을 얻을 수 있습니다.
-그리고 이 수천 개의 *경로 작동*은 모두 3줄 정도로 줄일 수 있습니다.
+그리고 이 수천 개의 *경로 처리*는 3줄 정도로도 만들 수 있습니다:
-{* ../../docs_src/security/tutorial002.py hl[30:32] *}
+{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
-## 요약
+## 요약 { #recap }
-이제 *경로 작동 함수*에서 현재 사용자를 직접 가져올 수 있습니다.
+이제 *경로 처리 함수*에서 현재 사용자를 직접 가져올 수 있습니다.
-우리는 이미 이들 사이에 있습니다.
+우리는 이미 절반은 왔습니다.
-사용자/클라이언트가 실제로 `username`과 `password`를 보내려면 *경로 작동*을 추가하기만 하면 됩니다.
+사용자/클라이언트가 실제로 `username`과 `password`를 보내도록 하는 *경로 처리*만 추가하면 됩니다.
-다음 장을 확인해 봅시다.
+다음에 이어집니다.
diff --git a/docs/ko/docs/tutorial/security/index.md b/docs/ko/docs/tutorial/security/index.md
new file mode 100644
index 000000000..2320b0657
--- /dev/null
+++ b/docs/ko/docs/tutorial/security/index.md
@@ -0,0 +1,106 @@
+# 보안 { #security }
+
+보안, 인증(authentication), 인가(authorization)를 처리하는 방법은 매우 다양합니다.
+
+그리고 보통 복잡하고 "어려운" 주제이기도 합니다.
+
+많은 프레임워크와 시스템에서 보안과 인증만 처리하는 데도 큰 노력과 코드가 필요합니다(많은 경우 작성된 전체 코드의 50% 이상이 될 수도 있습니다).
+
+**FastAPI**는 모든 보안 명세를 전부 공부하고 배울 필요 없이, 표준적인 방식으로 쉽고 빠르게 **보안(Security)** 을 다룰 수 있도록 여러 도구를 제공합니다.
+
+하지만 먼저, 몇 가지 작은 개념을 확인해 보겠습니다.
+
+## 급하신가요? { #in-a-hurry }
+
+이 용어들에 관심이 없고 사용자명과 비밀번호 기반 인증을 사용한 보안을 *지금 당장* 추가하기만 하면 된다면, 다음 장들로 넘어가세요.
+
+## OAuth2 { #oauth2 }
+
+OAuth2는 인증과 인가를 처리하는 여러 방법을 정의하는 명세입니다.
+
+상당히 방대한 명세이며 여러 복잡한 사용 사례를 다룹니다.
+
+"제3자"를 사용해 인증하는 방법도 포함합니다.
+
+바로 `"Facebook, Google, X (Twitter), GitHub로 로그인"` 같은 시스템들이 내부적으로 사용하는 방식입니다.
+
+### OAuth 1 { #oauth-1 }
+
+OAuth 1도 있었는데, 이는 OAuth2와 매우 다르고 통신을 암호화하는 방법까지 직접 명세에 포함했기 때문에 더 복잡했습니다.
+
+요즘에는 그다지 인기 있거나 사용되지는 않습니다.
+
+OAuth2는 통신을 어떻게 암호화할지는 명세하지 않고, 애플리케이션이 HTTPS로 제공될 것을 기대합니다.
+
+/// tip | 팁
+
+**배포**에 대한 섹션에서 Traefik과 Let's Encrypt를 사용해 무료로 HTTPS를 설정하는 방법을 볼 수 있습니다.
+
+///
+
+## OpenID Connect { #openid-connect }
+
+OpenID Connect는 **OAuth2**를 기반으로 한 또 다른 명세입니다.
+
+OAuth2에서 비교적 모호한 부분을 일부 구체화하여 상호 운용성을 높이려는 확장입니다.
+
+예를 들어, Google 로그인은 OpenID Connect를 사용합니다(내부적으로는 OAuth2를 사용).
+
+하지만 Facebook 로그인은 OpenID Connect를 지원하지 않습니다. 자체적인 변형의 OAuth2를 사용합니다.
+
+### OpenID("OpenID Connect"가 아님) { #openid-not-openid-connect }
+
+"OpenID"라는 명세도 있었습니다. 이는 **OpenID Connect**와 같은 문제를 해결하려고 했지만, OAuth2를 기반으로 하지 않았습니다.
+
+따라서 완전히 별도의 추가 시스템이었습니다.
+
+요즘에는 그다지 인기 있거나 사용되지는 않습니다.
+
+## OpenAPI { #openapi }
+
+OpenAPI(이전에는 Swagger로 알려짐)는 API를 구축하기 위한 공개 명세입니다(현재 Linux Foundation의 일부).
+
+**FastAPI**는 **OpenAPI**를 기반으로 합니다.
+
+이 덕분에 여러 자동 대화형 문서 인터페이스, 코드 생성 등과 같은 기능을 사용할 수 있습니다.
+
+OpenAPI에는 여러 보안 "scheme"을 정의하는 방법이 있습니다.
+
+이를 사용하면 이러한 대화형 문서 시스템을 포함해, 표준 기반 도구들을 모두 활용할 수 있습니다.
+
+OpenAPI는 다음 보안 scheme들을 정의합니다:
+
+* `apiKey`: 다음에서 전달될 수 있는 애플리케이션 전용 키:
+ * 쿼리 파라미터
+ * 헤더
+ * 쿠키
+* `http`: 표준 HTTP 인증 시스템, 예:
+ * `bearer`: `Authorization` 헤더에 `Bearer ` + 토큰 값을 넣는 방식. OAuth2에서 유래했습니다.
+ * HTTP Basic 인증
+ * HTTP Digest 등
+* `oauth2`: 보안을 처리하는 모든 OAuth2 방식(이를 "flow"라고 부릅니다).
+ * 이 flow들 중 여러 개는 OAuth 2.0 인증 제공자(예: Google, Facebook, X (Twitter), GitHub 등)를 구축하는 데 적합합니다:
+ * `implicit`
+ * `clientCredentials`
+ * `authorizationCode`
+ * 하지만 같은 애플리케이션에서 직접 인증을 처리하는 데 완벽하게 사용할 수 있는 특정 "flow"도 하나 있습니다:
+ * `password`: 다음 장들에서 이에 대한 예시를 다룹니다.
+* `openIdConnect`: OAuth2 인증 데이터를 자동으로 탐색(discover)하는 방법을 정의합니다.
+ * 이 자동 탐색은 OpenID Connect 명세에서 정의됩니다.
+
+
+/// tip | 팁
+
+Google, Facebook, X (Twitter), GitHub 등 다른 인증/인가 제공자를 통합하는 것도 가능하며 비교적 쉽습니다.
+
+가장 복잡한 문제는 그런 인증/인가 제공자 자체를 구축하는 것이지만, **FastAPI**는 어려운 작업을 대신 처리해 주면서 이를 쉽게 할 수 있는 도구를 제공합니다.
+
+///
+
+## **FastAPI** 유틸리티 { #fastapi-utilities }
+
+FastAPI는 `fastapi.security` 모듈에서 각 보안 scheme에 대한 여러 도구를 제공하며, 이러한 보안 메커니즘을 더 쉽게 사용할 수 있게 해줍니다.
+
+다음 장들에서는 **FastAPI**가 제공하는 도구를 사용해 API에 보안을 추가하는 방법을 보게 될 것입니다.
+
+또한 대화형 문서 시스템에 어떻게 자동으로 통합되는지도 확인하게 됩니다.
diff --git a/docs/ko/docs/tutorial/security/oauth2-jwt.md b/docs/ko/docs/tutorial/security/oauth2-jwt.md
index 8d27856e8..907795ca4 100644
--- a/docs/ko/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/ko/docs/tutorial/security/oauth2-jwt.md
@@ -1,36 +1,36 @@
-# 패스워드 해싱을 이용한 OAuth2, JWT 토큰을 사용하는 Bearer 인증
+# 패스워드(해싱 포함)를 사용하는 OAuth2, JWT 토큰을 사용하는 Bearer { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
-모든 보안 흐름을 구성했으므로, 이제 JWT 토큰과 패스워드 해싱을 사용해 애플리케이션을 안전하게 만들 것입니다.
+모든 보안 흐름을 구성했으므로, 이제 JWT 토큰과 안전한 패스워드 해싱을 사용해 애플리케이션을 실제로 안전하게 만들겠습니다.
-이 코드는 실제로 애플리케이션에서 패스워드를 해싱하여 DB에 저장하는 등의 작업에 활용할 수 있습니다.
+이 코드는 실제로 애플리케이션에서 사용할 수 있으며, 패스워드 해시를 데이터베이스에 저장하는 등의 작업에 활용할 수 있습니다.
-이전 장에 이어서 시작해 봅시다.
+이전 장에서 멈춘 지점부터 시작해 내용을 확장해 나가겠습니다.
-## JWT
+## JWT 알아보기 { #about-jwt }
-JWT 는 "JSON Web Tokens" 을 의미합니다.
+JWT는 "JSON Web Tokens"를 의미합니다.
-JSON 객체를 공백이 없는 긴 문자열로 인코딩하는 표준이며, 다음과 같은 형태입니다:
+JSON 객체를 공백이 없는 길고 밀집된 문자열로 부호화하는 표준입니다. 다음과 같은 형태입니다:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```
-JWT는 암호화되지 않아 누구든지 토큰에서 정보를 복원할 수 있습니다.
+암호화된 것이 아니므로, 누구나 내용에서 정보를 복원할 수 있습니다.
-하지만 JWT는 서명되어 있습니다. 그래서 자신이 발급한 토큰을 받았을 때, 실제로 자신이 발급한게 맞는지 검증할 수 있습니다.
+하지만 서명되어 있습니다. 따라서 자신이 발급한 토큰을 받았을 때, 실제로 자신이 발급한 것이 맞는지 검증할 수 있습니다.
-만료 기간이 일주일인 토큰을 발행했다고 가정해 봅시다. 다음 날 사용자가 토큰을 가져왔을 때, 그 사용자가 시스템에 여전히 로그인되어 있다는 것을 알 수 있습니다.
+예를 들어 만료 기간이 1주일인 토큰을 생성할 수 있습니다. 그리고 사용자가 다음 날 토큰을 가지고 돌아오면, 그 사용자가 시스템에 여전히 로그인되어 있다는 것을 알 수 있습니다.
-일주일 뒤에는 토큰이 만료될 것이고, 사용자는 인가되지 않아 새 토큰을 받기 위해 다시 로그인해야 할 것입니다. 만약 사용자(또는 제3자)가 토큰을 수정하거나 만료일을 변경하면, 서명이 일치하지 않기 때문에 알아챌 수 있을 것입니다.
+1주일 뒤에는 토큰이 만료되고 사용자는 인가되지 않으므로 새 토큰을 받기 위해 다시 로그인해야 합니다. 그리고 사용자(또는 제3자)가 만료 시간을 바꾸기 위해 토큰을 수정하려고 하면, 서명이 일치하지 않기 때문에 이를 알아챌 수 있습니다.
-만약 JWT 토큰을 다뤄보고, 작동 방식도 알아보고 싶다면 https://jwt.io 을 확인하십시오.
+JWT 토큰을 직접 다뤄보고 동작 방식을 확인해보고 싶다면 https://jwt.io를 확인하십시오.
-## `PyJWT` 설치
+## `PyJWT` 설치 { #install-pyjwt }
-파이썬으로 JWT 토큰을 생성하고 검증하려면 `PyJWT` 를 설치해야 합니다.
+Python에서 JWT 토큰을 생성하고 검증하려면 `PyJWT`를 설치해야 합니다.
-[가상환경](../../virtual-environments.md){.internal-link target=_blank} 을 만들고 활성화한 다음 `pyjwt` 를 설치하십시오:
+[가상환경](../../virtual-environments.md){.internal-link target=_blank}을 만들고 활성화한 다음 `pyjwt`를 설치하십시오:
-이전과 같은 방법으로 애플리케이션에 인증하십시오.
+이전과 같은 방법으로 애플리케이션을 인가하십시오.
다음 인증 정보를 사용하십시오:
@@ -211,13 +211,13 @@ Password: `secret`
/// check
-코드 어디에도 평문 패스워드 "`secret`" 이 없다는 점에 유의하십시오. 해시된 버전만 있습니다.
+코드 어디에도 평문 패스워드 "`secret`"은 없고, 해시된 버전만 있다는 점에 유의하십시오.
///
-`/users/me/` 를 호출하면 다음과 같은 응답을 얻을 수 있습니다:
+엔드포인트 `/users/me/`를 호출하면 다음과 같은 응답을 받게 됩니다:
```JSON
{
@@ -230,44 +230,44 @@ Password: `secret`
-개발자 도구를 열어보면 전송된 데이터에 토큰만 포함된 것을 확인할 수 있습니다. 패스워드는 사용자를 인증하고 액세스 토큰을 받기 위한 첫 번째 요청에만 전송되며, 이후에는 전송되지 않습니다:
+개발자 도구를 열어보면 전송된 데이터에는 토큰만 포함되어 있고, 패스워드는 사용자를 인증하고 해당 액세스 토큰을 얻기 위한 첫 번째 요청에서만 전송되며 이후에는 전송되지 않는 것을 확인할 수 있습니다:
/// note
-`Bearer `로 시작하는 `Authorization` 헤더에 주목하십시오.
+`Bearer `로 시작하는 값을 가진 `Authorization` 헤더에 주목하십시오.
///
-## `scopes` 의 고급 사용법
+## `scopes`의 고급 사용법 { #advanced-usage-with-scopes }
-OAuth2는 "스코프(scopes)" 라는 개념을 갖고 있습니다.
+OAuth2에는 "scopes"라는 개념이 있습니다.
-이를 사용하여 JWT 토큰에 특정 권한 집합을 추가할 수 있습니다.
+이를 사용해 JWT 토큰에 특정 권한 집합을 추가할 수 있습니다.
-그 후 이 토큰을 사용자에게 직접 제공하거나 제3자에게 제공하여, 특정 제한사항 하에있는 API와 통신하도록 할 수 있습니다.
+그런 다음 이 토큰을 사용자에게 직접 제공하거나 제3자에게 제공하여, 특정 제한사항 하에서 API와 상호작용하도록 할 수 있습니다.
-**FastAPI** 에서의 사용 방법과 통합 방식은 **심화 사용자 안내서** 에서 자세히 배울 수 있습니다.
+어떻게 사용하는지, 그리고 **FastAPI**에 어떻게 통합되는지는 이후 **심화 사용자 안내서**에서 배울 수 있습니다.
-## 요약
+## 요약 { #recap }
-지금까지 살펴본 내용을 바탕으로, OAuth2와 JWT 같은 표준을 사용하여 안전한 **FastAPI** 애플리케이션을 만들 수 있습니다.
+지금까지 살펴본 내용을 바탕으로, OAuth2와 JWT 같은 표준을 사용해 안전한 **FastAPI** 애플리케이션을 설정할 수 있습니다.
-거의 모든 프레임워크에서 보안 처리는 상당히 복잡한 주제입니다.
+거의 모든 프레임워크에서 보안 처리는 꽤 빠르게 복잡한 주제가 됩니다.
-이를 단순화하는 많은 패키지는 데이터 모델, 데이터베이스, 사용 가능한 기능들에 대해 여러 제약이 있습니다. 그리고 지나치게 단순화하는 일부 패키지들은 심각한 보안 결함을 가질 수도 있습니다.
+이를 크게 단순화하는 많은 패키지들은 데이터 모델, 데이터베이스, 사용 가능한 기능들에 대해 많은 타협을 해야 합니다. 그리고 지나치게 단순화하는 일부 패키지들은 실제로 내부에 보안 결함이 있기도 합니다.
---
-**FastAPI** 는 어떤 데이터베이스, 데이터 모델, 도구도 강요하지 않습니다.
+**FastAPI**는 어떤 데이터베이스, 데이터 모델, 도구에도 타협하지 않습니다.
-프로젝트에 가장 적합한 것을 선택할 수 있는 유연성을 제공합니다.
+프로젝트에 가장 잘 맞는 것들을 선택할 수 있는 모든 유연성을 제공합니다.
-그리고 `passlib` 와 `PyJWT` 처럼 잘 관리되고 널리 사용되는 패키지들을 바로 사용할 수 있습니다. **FastAPI** 는 외부 패키지 통합을 위해 복잡한 메커니즘이 필요하지 않기 때문입니다.
+그리고 **FastAPI**는 외부 패키지를 통합하기 위해 복잡한 메커니즘을 요구하지 않기 때문에 `pwdlib`와 `PyJWT` 같은 잘 관리되고 널리 사용되는 패키지들을 바로 사용할 수 있습니다.
-그러나 유연성, 견고성, 보안성을 해치지 않으면서 과정을 단순화할 수 있는 도구들을 제공합니다.
+하지만 유연성, 견고성, 보안성을 해치지 않으면서 과정을 가능한 한 단순화할 수 있도록 도구들을 제공합니다.
-그리고 OAuth2와 같은 표준 프로토콜을 비교적 간단한 방법으로 구현하고 사용할 수 있습니다.
+또한 OAuth2 같은 안전한 표준 프로토콜을 비교적 간단한 방식으로 사용하고 구현할 수 있습니다.
-더 세분화된 권한 체계를 위해 OAuth2의 "스코프"를 사용하는 방법은 **심화 사용자 안내서**에서 더 자세히 배울 수 있습니다. OAuth2의 스코프는 제3자 애플리케이션이 사용자를 대신해 그들의 API와 상호작용하도록 권한을 부여하기 위해, Facebook, Google, GitHub, Microsoft, X (Twitter) 등의 많은 대형 인증 제공업체들이 사용하는 메커니즘입니다.
+더 세분화된 권한 시스템을 위해 OAuth2 "scopes"를 사용하는 방법은, 같은 표준을 따르는 방식으로 **심화 사용자 안내서**에서 더 자세히 배울 수 있습니다. 스코프를 사용하는 OAuth2는 Facebook, Google, GitHub, Microsoft, X (Twitter) 등 많은 대형 인증 제공업체들이 제3자 애플리케이션이 사용자 대신 그들의 API와 상호작용할 수 있도록 인가하는 데 사용하는 메커니즘입니다.
diff --git a/docs/ko/docs/tutorial/security/simple-oauth2.md b/docs/ko/docs/tutorial/security/simple-oauth2.md
index f10c4f588..189dd89f2 100644
--- a/docs/ko/docs/tutorial/security/simple-oauth2.md
+++ b/docs/ko/docs/tutorial/security/simple-oauth2.md
@@ -1,8 +1,8 @@
-# 패스워드와 Bearer를 이용한 간단한 OAuth2
+# 패스워드와 Bearer를 이용한 간단한 OAuth2 { #simple-oauth2-with-password-and-bearer }
이제 이전 장에서 빌드하고 누락된 부분을 추가하여 완전한 보안 흐름을 갖도록 하겠습니다.
-## `username`와 `password` 얻기
+## `username`와 `password` 얻기 { #get-the-username-and-password }
**FastAPI** 보안 유틸리티를 사용하여 `username` 및 `password`를 가져올 것입니다.
@@ -14,11 +14,11 @@ OAuth2는 (우리가 사용하고 있는) "패스워드 플로우"을 사용할
그리고 데이터베이스 모델은 원하는 다른 이름을 사용할 수 있습니다.
-그러나 로그인 *경로 작동*의 경우 사양과 호환되도록 이러한 이름을 사용해야 합니다(예를 들어 통합 API 문서 시스템을 사용할 수 있어야 합니다).
+그러나 로그인 *경로 처리*의 경우 사양과 호환되도록 이러한 이름을 사용해야 합니다(예를 들어 통합 API 문서 시스템을 사용할 수 있어야 합니다).
사양에는 또한 `username`과 `password`가 폼 데이터로 전송되어야 한다고 명시되어 있습니다(따라서 여기에는 JSON이 없습니다).
-### `scope`
+### `scope` { #scope }
사양에는 클라이언트가 다른 폼 필드 "`scope`"를 보낼 수 있다고 나와 있습니다.
@@ -44,15 +44,15 @@ OAuth2의 경우 문자열일 뿐입니다.
///
-## `username`과 `password`를 가져오는 코드
+## `username`과 `password`를 가져오는 코드 { #code-to-get-the-username-and-password }
이제 **FastAPI**에서 제공하는 유틸리티를 사용하여 이를 처리해 보겠습니다.
-### `OAuth2PasswordRequestForm`
+### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }
-먼저 `OAuth2PasswordRequestForm`을 가져와 `/token`에 대한 *경로 작동*에서 `Depends`의 의존성으로 사용합니다.
+먼저 `OAuth2PasswordRequestForm`을 가져와 `/token`에 대한 *경로 처리*에서 `Depends`의 의존성으로 사용합니다.
-{* ../../docs_src/security/tutorial003.py hl[4,76] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
`OAuth2PasswordRequestForm`은 다음을 사용하여 폼 본문을 선언하는 클래스 의존성입니다:
@@ -84,7 +84,7 @@ OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type`
///
-### 폼 데이터 사용하기
+### 폼 데이터 사용하기 { #use-the-form-data }
/// tip | 팁
@@ -100,9 +100,9 @@ OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type`
오류의 경우 `HTTPException` 예외를 사용합니다:
-{* ../../docs_src/security/tutorial003.py hl[3,77:79] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
-### 패스워드 확인하기
+### 패스워드 확인하기 { #check-the-password }
이 시점에서 데이터베이스의 사용자 데이터 형식을 확인했지만 암호를 확인하지 않았습니다.
@@ -112,7 +112,7 @@ OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type`
두 패스워드가 일치하지 않으면 동일한 오류가 반환됩니다.
-#### 패스워드 해싱
+#### 패스워드 해싱 { #password-hashing }
"해싱"은 일부 콘텐츠(이 경우 패스워드)를 횡설수설하는 것처럼 보이는 일련의 바이트(문자열)로 변환하는 것을 의미합니다.
@@ -120,21 +120,15 @@ OAuth2 사양은 실제로 `password`라는 고정 값이 있는 `grant_type`
그러나 횡설수설에서 암호로 다시 변환할 수는 없습니다.
-##### 패스워드 해싱을 사용해야 하는 이유
+##### 패스워드 해싱을 사용해야 하는 이유 { #why-use-password-hashing }
데이터베이스가 유출된 경우 해커는 사용자의 일반 텍스트 암호가 아니라 해시만 갖게 됩니다.
따라서 해커는 다른 시스템에서 동일한 암호를 사용하려고 시도할 수 없습니다(많은 사용자가 모든 곳에서 동일한 암호를 사용하므로 이는 위험할 수 있습니다).
-//// tab | 파이썬 3.7 이상
+{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-{* ../../docs_src/security/tutorial003.py hl[80:83] *}
-
-////
-
-{* ../../docs_src/security/tutorial003_py310.py hl[78:81] *}
-
-#### `**user_dict`에 대해
+#### `**user_dict`에 대해 { #about-user-dict }
`UserInDB(**user_dict)`는 다음을 의미한다:
@@ -152,11 +146,11 @@ UserInDB(
/// info | 정보
-`**user_dict`에 대한 자세한 설명은 [**추가 모델** 문서](../extra-models.md#about-user_indict){.internal-link target=_blank}를 다시 읽어봅시다.
+`**user_dict`에 대한 자세한 설명은 [**추가 모델** 문서](../extra-models.md#about-user-in-dict){.internal-link target=_blank}를 다시 확인해보세요.
///
-## 토큰 반환하기
+## 토큰 반환하기 { #return-the-token }
`token` 엔드포인트의 응답은 JSON 객체여야 합니다.
@@ -174,7 +168,7 @@ UserInDB(
///
-{* ../../docs_src/security/tutorial003.py hl[85] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
/// tip | 팁
@@ -188,19 +182,19 @@ UserInDB(
///
-## 의존성 업데이트하기
+## 의존성 업데이트하기 { #update-the-dependencies }
이제 의존성을 업데이트를 할 겁니다.
이 사용자가 활성화되어 있는 *경우에만* `current_user`를 가져올 겁니다.
-따라서 `get_current_user`를 의존성으로 사용하는 추가 종속성 `get_current_active_user`를 만듭니다.
+따라서 `get_current_user`를 의존성으로 사용하는 추가 의존성 `get_current_active_user`를 만듭니다.
이러한 의존성 모두, 사용자가 존재하지 않거나 비활성인 경우 HTTP 오류를 반환합니다.
따라서 엔드포인트에서는 사용자가 존재하고 올바르게 인증되었으며 활성 상태인 경우에만 사용자를 얻습니다:
-{* ../../docs_src/security/tutorial003.py hl[58:66,69:72,90] *}
+{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
/// info | 정보
@@ -220,11 +214,11 @@ UserInDB(
///
-## 확인하기
+## 확인하기 { #see-it-in-action }
대화형 문서 열기: http://127.0.0.1:8000/docs.
-### 인증하기
+### 인증하기 { #authenticate }
"Authorize" 버튼을 눌러봅시다.
@@ -240,7 +234,7 @@ UserInDB(
-### 자신의 유저 데이터 가져오기
+### 자신의 유저 데이터 가져오기 { #get-your-own-user-data }
이제 `/users/me` 경로에 `GET` 작업을 진행합시다.
@@ -266,7 +260,7 @@ UserInDB(
}
```
-### 비활성된 유저
+### 비활성된 유저 { #inactive-user }
이제 비활성된 사용자로 시도하고, 인증해봅시다:
@@ -284,7 +278,7 @@ UserInDB(
}
```
-## 요약
+## 요약 { #recap }
이제 API에 대한 `username` 및 `password`를 기반으로 완전한 보안 시스템을 구현할 수 있는 도구가 있습니다.
diff --git a/docs/ko/docs/tutorial/sql-databases.md b/docs/ko/docs/tutorial/sql-databases.md
index 58c7017d6..3d64cf627 100644
--- a/docs/ko/docs/tutorial/sql-databases.md
+++ b/docs/ko/docs/tutorial/sql-databases.md
@@ -1,18 +1,18 @@
-# SQL (관계형) 데이터베이스
+# SQL (관계형) 데이터베이스 { #sql-relational-databases }
-**FastAPI**에서 SQL(관계형) 데이터베이스 사용은 필수가 아닙니다. 여러분이 원하는 **어떤 데이터베이스든** 사용할 수 있습니다.
+**FastAPI**에서 SQL(관계형) 데이터베이스 사용은 필수가 아닙니다. 하지만 여러분이 원하는 **어떤 데이터베이스든** 사용할 수 있습니다.
여기서는 SQLModel을 사용하는 예제를 살펴보겠습니다.
-**SQLModel**은 SQLAlchemy와 Pydantic을 기반으로 구축되었습니다.SQLModel은 **SQL 데이터베이스**를 사용하는 FastAPI 애플리케이션에 완벽히 어울리도록 **FastAPI**의 제작자가 설계한 도구입니다.
+**SQLModel**은 SQLAlchemy와 Pydantic을 기반으로 구축되었습니다. **SQL 데이터베이스**를 사용해야 하는 FastAPI 애플리케이션에 완벽히 어울리도록 **FastAPI**와 같은 제작자가 만든 도구입니다.
/// tip | 팁
-다른 SQL 또는 NoSQL 데이터베이스 라이브러리를 사용할 수도 있습니다 (일부는 "ORM"이라고도 불립니다), FastAPI는 특정 라이브러리의 사용을 강요하지 않습니다. 😎
+다른 SQL 또는 NoSQL 데이터베이스 라이브러리를 사용할 수도 있습니다 (일부는 "ORMs"이라고도 불립니다), FastAPI는 특정 라이브러리의 사용을 강요하지 않습니다. 😎
///
-SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하는 모든 데이터베이스**를 손쉽게 사용할 수 있습니다(SQLModel에서도 동일하게 지원됩니다). 예를 들면:
+SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하는 모든 데이터베이스**를 손쉽게 사용할 수 있습니다(이것들은 SQLModel에서도 지원됩니다). 예를 들면:
* PostgreSQL
* MySQL
@@ -20,19 +20,19 @@ SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하
* Oracle
* Microsoft SQL Server 등.
-이 예제에서는 **SQLite**를 사용합니다. SQLite는 단일 파일을 사용하고 파이썬에서 기본적으로 지원하기 때문입니다. 따라서 이 예제를 그대로 복사하여 실행할 수 있습니다.
+이 예제에서는 **SQLite**를 사용합니다. SQLite는 단일 파일을 사용하고 Python에서 통합 지원하기 때문입니다. 따라서 이 예제를 그대로 복사하여 실행할 수 있습니다.
-나중에 실제 프로덕션 애플리케이션에서는 **PostgreSQL**과 같은 데이터베이스 서버를 사용하는 것이 좋습니다.
+나중에 프로덕션 애플리케이션에서는 **PostgreSQL**과 같은 데이터베이스 서버를 사용하는 것이 좋습니다.
/// tip | 팁
-**FastAPI**와 **PostgreSQL**를 포함하여 프론트엔드와 다양한 도구를 제공하는 공식 프로젝트 생성기가 있습니다: https://github.com/fastapi/full-stack-fastapi-template
+프론트엔드와 더 많은 도구를 포함하여 **FastAPI**와 **PostgreSQL**을 포함한 공식 프로젝트 생성기가 있습니다: https://github.com/fastapi/full-stack-fastapi-template
///
-이 튜토리얼은 매우 간단하고 짧습니다. 데이터베이스 기본 개념, SQL, 또는 더 복잡한 기능에 대해 배우고 싶다면, SQLModel 문서를 참고하세요.
+이 튜토리얼은 매우 간단하고 짧습니다. 데이터베이스 기본 개념, SQL, 또는 더 고급 기능에 대해 배우고 싶다면, SQLModel 문서를 참고하세요.
-## `SQLModel` 설치하기
+## `SQLModel` 설치하기 { #install-sqlmodel }
먼저, [가상 환경](../virtual-environments.md){.internal-link target=_blank}을 생성하고 활성화한 다음, `sqlmodel`을 설치하세요:
@@ -45,13 +45,13 @@ $ pip install sqlmodel
-## 단일 모델로 애플리케이션 생성하기
+## 단일 모델로 애플리케이션 생성하기 { #create-the-app-with-a-single-model }
우선 단일 **SQLModel** 모델을 사용하여 애플리케이션의 가장 간단한 첫 번째 버전을 생성해보겠습니다.
-이후 **다중 모델**을 추가하여 보안과 유연성을 강화할 것입니다. 🤓
+이후 아래에서 **여러 모델**로 보안과 유연성을 강화하며 개선하겠습니다. 🤓
-### 모델 생성하기
+### 모델 생성하기 { #create-models }
`SQLModel`을 가져오고 데이터베이스 모델을 생성합니다:
@@ -61,45 +61,45 @@ $ pip install sqlmodel
몇 가지 차이점이 있습니다:
-* `table=True`는 SQLModel에 이 모델이 *테이블 모델*이며, 단순한 데이터 모델이 아니라 SQL 데이터베이스의 **테이블**을 나타낸다는 것을 알려줍니다. (다른 일반적인 Pydantic 클래스처럼) 단순한 *데이터 모델*이 아닙니다.
+* `table=True`는 SQLModel에 이 모델이 *테이블 모델*이며, SQL 데이터베이스의 **테이블**을 나타내야 한다는 것을 알려줍니다. (다른 일반적인 Pydantic 클래스처럼) 단순한 *데이터 모델*이 아닙니다.
* `Field(primary_key=True)`는 SQLModel에 `id`가 SQL 데이터베이스의 **기본 키**임을 알려줍니다 (SQL 기본 키에 대한 자세한 내용은 SQLModel 문서를 참고하세요).
- `int | None` 유형으로 설정하면, SQLModel은 해당 열이 SQL 데이터베이스에서 `INTEGER` 유형이며 `NULLABLE` 값이어야 한다는 것을 알 수 있습니다.
+ **참고:** 기본 키 필드에 `int | None`을 사용하는 이유는, Python 코드에서 *`id` 없이 객체를 생성*할 수 있게 하기 위해서입니다(`id=None`). 데이터베이스가 *저장할 때 생성해 줄 것*이라고 가정합니다. SQLModel은 데이터베이스가 `id`를 제공한다는 것을 이해하고, 데이터베이스 스키마에서 *해당 열을 null이 아닌 `INTEGER`*로 정의합니다. 자세한 내용은 기본 키에 대한 SQLModel 문서를 참고하세요.
-* `Field(index=True)`는 SQLModel에 해당 열에 대해 **SQL 인덱스**를 생성하도록 지시합니다. 이를 통해 데이터베이스에서 이 열으로 필터링된 데이터를 읽을 때 더 빠르게 조회할 수 있습니다.
+* `Field(index=True)`는 SQLModel에 해당 열에 대해 **SQL 인덱스**를 생성하도록 지시합니다. 이를 통해 데이터베이스에서 이 열로 필터링된 데이터를 읽을 때 더 빠르게 조회할 수 있습니다.
SQLModel은 `str`으로 선언된 항목이 SQL 데이터베이스에서 `TEXT` (또는 데이터베이스에 따라 `VARCHAR`) 유형의 열로 저장된다는 것을 인식합니다.
-### 엔진 생성하기
+### 엔진 생성하기 { #create-an-engine }
SQLModel의 `engine` (내부적으로는 SQLAlchemy `engine`)은 데이터베이스에 대한 **연결을 유지**하는 역할을 합니다.
-**하나의 단일 engine 객체**를 통해 코드 전체에서 동일한 데이터베이스에 연결할 수 있습니다.
+코드 전체에서 동일한 데이터베이스에 연결하기 위해 **하나의 단일 `engine` 객체**를 사용합니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[14:18] hl[14:15,17:18] *}
-`check_same_thread=False`를 사용하면 FastAPI에서 여러 스레드에서 동일한 SQLite 데이터베이스를 사용할 수 있습니다. 이는 **하나의 단일 요청**이 **여러 스레드**를 사용할 수 있기 때문에 필요합니다(예: 의존성에서 사용되는 경우).
+`check_same_thread=False`를 사용하면 FastAPI에서 여러 스레드에서 동일한 SQLite 데이터베이스를 사용할 수 있습니다. 이는 **하나의 단일 요청**이 **둘 이상의 스레드**를 사용할 수 있기 때문에 필요합니다(예: 의존성에서 사용되는 경우).
-걱정하지 마세요. 코드가 구조화된 방식으로 인해, 이후에 **각 요청마다 단일 SQLModel *세션*을 사용**하도록 보장할 것입니다. 실제로 그것이 `check_same_thread`가 하려는 것입니다.
+걱정하지 마세요. 코드가 구조화된 방식으로 인해, 이후에 **각 요청마다 단일 SQLModel *세션*을 사용**하도록 보장할 것입니다. 실제로 이것이 `check_same_thread`가 하려는 것입니다.
-### 테이블 생성하기
+### 테이블 생성하기 { #create-the-tables }
그 다음 `SQLModel.metadata.create_all(engine)`을 사용하여 모든 *테이블 모델*의 **테이블을 생성**하는 함수를 추가합니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
-### 세션 의존성 생성하기
+### 세션 의존성 생성하기 { #create-a-session-dependency }
**`Session`**은 **메모리에 객체**를 저장하고 데이터에 필요한 모든 변경 사항을 추적한 후, **`engine`을 통해** 데이터베이스와 통신합니다.
`yield`를 사용해 FastAPI의 **의존성**을 생성하여 각 요청마다 새로운 `Session`을 제공합니다. 이는 요청당 하나의 세션만 사용되도록 보장합니다. 🤓
-그런 다음 이 의존성을 사용하는 코드를 간소화하기 위해 `Annotated` 의존성 `SessionDep`을 생성합니다.
+그런 다음 이 의존성을 사용하는 나머지 코드를 간소화하기 위해 `Annotated` 의존성 `SessionDep`을 생성합니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
-### 시작 시 데이터베이스 테이블 생성하기
+### 시작 시 데이터베이스 테이블 생성하기 { #create-database-tables-on-startup }
애플리케이션 시작 시 데이터베이스 테이블을 생성합니다.
@@ -115,9 +115,9 @@ SQLModel은 Alembic을 감싸는 마이그레이션 유틸리티를 제공할
///
-### Hero 생성하기
+### Hero 생성하기 { #create-a-hero }
-각 SQLModel 모델은 Pydantic 모델이기도 하므로, Pydantic 모델을 사용할 수 있는 **타입 어노테이**션에서 동일하게 사용할 수 있습니다.
+각 SQLModel 모델은 Pydantic 모델이기도 하므로, Pydantic 모델을 사용할 수 있는 동일한 **타입 어노테이션**에서 사용할 수 있습니다.
예를 들어, 파라미터를 `Hero` 타입으로 선언하면 **JSON 본문**에서 값을 읽어옵니다.
@@ -125,31 +125,29 @@ SQLModel은 Alembic을 감싸는 마이그레이션 유틸리티를 제공할
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *}
-
+여기서는 `SessionDep` 의존성(`Session`)을 사용하여 새로운 `Hero`를 `Session` 인스턴스에 추가하고, 데이터베이스에 변경 사항을 커밋하고, `hero` 데이터의 최신 상태를 갱신한 다음 이를 반환합니다.
-여기서 `SessionDep` 의존성 (즉, `Session`)을 사용하여 새로운 `Hero`를 `Session` 인스턴스에 추가하고, 데이터베이스에 변경 사항을 커밋하고, `hero` 데이터의 최신 상태를 갱신한 다음 이를 반환합니다.
-
-### Heroes 조회하기
+### Heroes 조회하기 { #read-heroes }
`select()`를 사용하여 데이터베이스에서 `Hero`를 **조회**할 수 있습니다. 결과에 페이지네이션을 적용하기 위해 `limit`와 `offset`을 포함할 수 있습니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
-### 단일 Hero 조회하기
+### 단일 Hero 조회하기 { #read-one-hero }
단일 `Hero`를 **조회**할 수도 있습니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
-### Hero 삭제하기
+### Hero 삭제하기 { #delete-a-hero }
`Hero`를 **삭제**하는 것도 가능합니다.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
-### 애플리케이션 실행하기
+### 애플리케이션 실행하기 { #run-the-app }
-애플리케이션을 실행하려면 다음 명령을 사용합니다:
+애플리케이션을 실행할 수 있습니다:
-
-
- 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 -%} -
-
-Als je een CLI-app bouwt die in de terminal moet worden gebruikt in plaats van een web-API, gebruik dan **Typer**.
-
-**Typer** is het kleine broertje van FastAPI. En het is bedoeld als de **FastAPI van CLI's**. ️
-
-## Vereisten
-
-FastAPI staat op de schouders van reuzen:
-
-* Starlette voor de webonderdelen.
-* Pydantic voor de datadelen.
-
-## Installatie
-
-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
deleted file mode 100644
index fb8b1e5fd..000000000
--- a/docs/nl/docs/python-types.md
+++ /dev/null
@@ -1,587 +0,0 @@
-# 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
deleted file mode 100644
index de18856f4..000000000
--- a/docs/nl/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/pl/docs/features.md b/docs/pl/docs/features.md
deleted file mode 100644
index 80d3bdece..000000000
--- a/docs/pl/docs/features.md
+++ /dev/null
@@ -1,201 +0,0 @@
-# Cechy
-
-## Cechy FastAPI
-
-**FastAPI** zapewnia Ci następujące korzyści:
-
-### Oparcie o standardy open
-
-* OpenAPI do tworzenia API, w tym deklaracji ścieżek operacji, parametrów, ciał zapytań, bezpieczeństwa, itp.
-* Automatyczna dokumentacja modelu danych za pomocą JSON Schema (ponieważ OpenAPI bazuje na JSON Schema).
-* Zaprojektowane z myślą o zgodności z powyższymi standardami zamiast dodawania ich obsługi po fakcie.
-* Możliwość automatycznego **generowania kodu klienta** w wielu językach.
-
-### Automatyczna dokumentacja
-
-Interaktywna dokumentacja i webowe interfejsy do eksploracji API. Z racji tego, że framework bazuje na OpenAPI, istnieje wiele opcji, z czego 2 są domyślnie dołączone.
-
-* Swagger UI, z interaktywnym interfejsem - odpytuj i testuj swoje API bezpośrednio z przeglądarki.
-
-
-
-* Alternatywna dokumentacja API z ReDoc.
-
-
-
-### Nowoczesny Python
-
-Wszystko opiera się na standardowych deklaracjach typu **Python 3.8** (dzięki Pydantic). Brak nowej składni do uczenia. Po prostu standardowy, współczesny Python.
-
-Jeśli potrzebujesz szybkiego przypomnienia jak używać deklaracji typów w Pythonie (nawet jeśli nie używasz FastAPI), sprawdź krótki samouczek: [Python Types](python-types.md){.internal-link target=_blank}.
-
-Wystarczy, że napiszesz standardowe deklaracje typów Pythona:
-
-```Python
-from datetime import date
-
-from pydantic import BaseModel
-
-# Zadeklaruj parametr jako str
-# i uzyskaj wsparcie edytora wewnątrz funkcji
-def main(user_id: str):
- return user_id
-
-
-# Model Pydantic
-class User(BaseModel):
- id: int
- name: str
- joined: date
-```
-
-A one będą mogły zostać później użyte w następujący sposób:
-
-```Python
-my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
-
-second_user_data = {
- "id": 4,
- "name": "Mary",
- "joined": "2018-11-30",
-}
-
-my_second_user: User = User(**second_user_data)
-```
-
-/// info
-
-`**second_user_data` oznacza:
-
-Przekaż klucze i wartości słownika `second_user_data` bezpośrednio jako argumenty klucz-wartość, co jest równoznaczne z: `User(id=4, name="Mary", joined="2018-11-30")`
-
-///
-
-### Wsparcie edytora
-
-Cały framework został zaprojektowany tak, aby był łatwy i intuicyjny w użyciu. Wszystkie pomysły zostały przetestowane na wielu edytorach jeszcze przed rozpoczęciem procesu tworzenia, aby zapewnić najlepsze wrażenia programistyczne.
-
-Ostatnia ankieta Python developer survey jasno wskazuje, że najczęściej używaną funkcjonalnością jest autouzupełnianie w edytorze.
-
-Cała struktura frameworku **FastAPI** jest na tym oparta. Autouzupełnianie działa wszędzie.
-
-Rzadko będziesz musiał wracać do dokumentacji.
-
-Oto, jak twój edytor może Ci pomóc:
-
-* Visual Studio Code:
-
-
-
-* PyCharm:
-
-
-
-Otrzymasz uzupełnienie nawet w miejscach, w których normalnie uzupełnienia nie ma. Na przykład klucz "price" w treści JSON (który mógł być zagnieżdżony), który pochodzi z zapytania.
-
-Koniec z wpisywaniem błędnych nazw kluczy, przechodzeniem tam i z powrotem w dokumentacji lub przewijaniem w górę i w dół, aby sprawdzić, czy w końcu użyłeś nazwy `username` czy `user_name`.
-
-### Zwięzłość
-
-Wszystko posiada sensowne **domyślne wartości**. Wszędzie znajdziesz opcjonalne konfiguracje. Wszystkie parametry możesz dostroić, aby zrobić to co potrzebujesz do zdefiniowania API.
-
-Ale domyślnie wszystko **"po prostu działa"**.
-
-### Walidacja
-
-* Walidacja większości (lub wszystkich?) **typów danych** Pythona, w tym:
- * Obiektów JSON (`dict`).
- * Tablic JSON (`list`) ze zdefiniowanym typem elementów.
- * Pól tekstowych (`str`) z określeniem minimalnej i maksymalnej długości.
- * Liczb (`int`, `float`) z wartościami minimalnymi, maksymalnymi, itp.
-
-* Walidacja bardziej egzotycznych typów danych, takich jak:
- * URL.
- * Email.
- * UUID.
- * ...i inne.
-
-Cała walidacja jest obsługiwana przez ugruntowaną i solidną bibliotekę **Pydantic**.
-
-### Bezpieczeństwo i uwierzytelnianie
-
-Bezpieczeństwo i uwierzytelnianie jest zintegrowane. Bez żadnych kompromisów z bazami czy modelami danych.
-
-Wszystkie schematy bezpieczeństwa zdefiniowane w OpenAPI, w tym:
-
-* Podstawowy protokół HTTP.
-* **OAuth2** (również z **tokenami JWT**). Sprawdź samouczek [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
-* Klucze API w:
- * Nagłówkach.
- * Parametrach zapytań.
- * Ciasteczkach, itp.
-
-Plus wszystkie funkcje bezpieczeństwa Starlette (włączając w to **ciasteczka sesyjne**).
-
-Wszystko zbudowane jako narzędzia i komponenty wielokrotnego użytku, które można łatwo zintegrować z systemami, magazynami oraz bazami danych - relacyjnymi, NoSQL, itp.
-
-### Wstrzykiwanie Zależności
-
-FastAPI zawiera niezwykle łatwy w użyciu, ale niezwykle potężny system Wstrzykiwania Zależności.
-
-* Nawet zależności mogą mieć zależności, tworząc hierarchię lub **"graf" zależności**.
-* Wszystko jest **obsługiwane automatycznie** przez framework.
-* Wszystkie zależności mogą wymagać danych w żądaniach oraz rozszerzać ograniczenia i automatyczną dokumentację **operacji na ścieżce**.
-* **Automatyczna walidacja** parametrów *operacji na ścieżce* zdefiniowanych w zależnościach.
-* Obsługa złożonych systemów uwierzytelniania użytkowników, **połączeń z bazami danych**, itp.
-* Bazy danych, front end, itp. **bez kompromisów**, ale wciąż łatwe do integracji.
-
-### Nieograniczone "wtyczki"
-
-Lub ujmując to inaczej - brak potrzeby wtyczek. Importuj i używaj kod, który potrzebujesz.
-
-Każda integracja została zaprojektowana tak, aby była tak prosta w użyciu (z zależnościami), że możesz utworzyć "wtyczkę" dla swojej aplikacji w 2 liniach kodu, używając tej samej struktury i składni, które są używane w *operacjach na ścieżce*.
-
-### Testy
-
-* 100% pokrycia kodu testami.
-* 100% adnotacji typów.
-* Używany w aplikacjach produkcyjnych.
-
-## Cechy Starlette
-
-**FastAPI** jest w pełni kompatybilny z (oraz bazuje na) Starlette. Tak więc każdy dodatkowy kod Starlette, który posiadasz, również będzie działał.
-
-`FastAPI` jest w rzeczywistości podklasą `Starlette`, więc jeśli już znasz lub używasz Starlette, większość funkcji będzie działać w ten sam sposób.
-
-Dzięki **FastAPI** otrzymujesz wszystkie funkcje **Starlette** (ponieważ FastAPI to po prostu Starlette na sterydach):
-
-* Bardzo imponująca wydajność. Jest to jeden z najszybszych dostępnych frameworków Pythona, na równi z **NodeJS** i **Go**.
-* Wsparcie dla **WebSocket**.
-* Zadania w tle.
-* Eventy startup i shutdown.
-* Klient testowy zbudowany na bazie biblioteki `requests`.
-* **CORS**, GZip, pliki statyczne, streamy.
-* Obsługa **sesji i ciasteczek**.
-* 100% pokrycie testami.
-* 100% adnotacji typów.
-
-## Cechy Pydantic
-
-**FastAPI** jest w pełni kompatybilny z (oraz bazuje na) Pydantic. Tak więc każdy dodatkowy kod Pydantic, który posiadasz, również będzie działał.
-
-Wliczając w to zewnętrzne biblioteki, również oparte o Pydantic, takie jak ORM, ODM dla baz danych.
-
-Oznacza to, że w wielu przypadkach możesz przekazać ten sam obiekt, który otrzymasz z żądania **bezpośrednio do bazy danych**, ponieważ wszystko jest walidowane automatycznie.
-
-Działa to również w drugą stronę, w wielu przypadkach możesz po prostu przekazać obiekt otrzymany z bazy danych **bezpośrednio do klienta**.
-
-Dzięki **FastAPI** otrzymujesz wszystkie funkcje **Pydantic** (ponieważ FastAPI bazuje na Pydantic do obsługi wszystkich danych):
-
-* **Bez prania mózgu**:
- * Brak nowego mikrojęzyka do definiowania schematu, którego trzeba się nauczyć.
- * Jeśli znasz adnotacje typów Pythona to wiesz jak używać Pydantic.
-* Dobrze współpracuje z Twoim **IDE/linterem/mózgiem**:
- * Ponieważ struktury danych Pydantic to po prostu instancje klas, które definiujesz; autouzupełnianie, linting, mypy i twoja intuicja powinny działać poprawnie z Twoimi zwalidowanymi danymi.
-* Walidacja **złożonych struktur**:
- * Wykorzystanie hierarchicznych modeli Pydantic, Pythonowego modułu `typing` zawierającego `List`, `Dict`, itp.
- * Walidatory umożliwiają jasne i łatwe definiowanie, sprawdzanie złożonych struktur danych oraz dokumentowanie ich jako JSON Schema.
- * Możesz mieć głęboko **zagnieżdżone obiekty JSON** i wszystkie je poddać walidacji i adnotować.
-* **Rozszerzalność**:
- * Pydantic umożliwia zdefiniowanie niestandardowych typów danych lub rozszerzenie walidacji o metody na modelu, na których użyty jest dekorator walidatora.
-* 100% pokrycie testami.
diff --git a/docs/pl/docs/help-fastapi.md b/docs/pl/docs/help-fastapi.md
deleted file mode 100644
index 05e491d55..000000000
--- a/docs/pl/docs/help-fastapi.md
+++ /dev/null
@@ -1,269 +0,0 @@
-# Pomóż FastAPI - Uzyskaj pomoc
-
-Czy podoba Ci się **FastAPI**?
-
-Czy chciałbyś pomóc FastAPI, jego użytkownikom i autorowi?
-
-Może napotkałeś na trudności z **FastAPI** i potrzebujesz pomocy?
-
-Istnieje kilka bardzo łatwych sposobów, aby pomóc (czasami wystarczy jedno lub dwa kliknięcia).
-
-Istnieje również kilka sposobów uzyskania pomocy.
-
-## Zapisz się do newslettera
-
-Możesz zapisać się do rzadkiego [newslettera o **FastAPI i jego przyjaciołach**](newsletter.md){.internal-link target=_blank}, aby być na bieżąco z:
-
-* Aktualnościami o FastAPI i przyjaciołach 🚀
-* Przewodnikami 📝
-* Funkcjami ✨
-* Przełomowymi zmianami 🚨
-* Poradami i sztuczkami ✅
-
-## Śledź FastAPI na X (Twitter)
-
-Śledź @fastapi na **X (Twitter)** aby być na bieżąco z najnowszymi wiadomościami o **FastAPI**. 🐦
-
-## Dodaj gwiazdkę **FastAPI** na GitHubie
-
-Możesz "dodać gwiazdkę" FastAPI na GitHubie (klikając przycisk gwiazdki w prawym górnym rogu): https://github.com/fastapi/fastapi. ⭐️
-
-Dodając gwiazdkę, inni użytkownicy będą mogli łatwiej znaleźć projekt i zobaczyć, że był już przydatny dla innych.
-
-## Obserwuj repozytorium GitHub w poszukiwaniu nowych wydań
-
-Możesz "obserwować" FastAPI na GitHubie (klikając przycisk "obserwuj" w prawym górnym rogu): https://github.com/fastapi/fastapi. 👀
-
-Wybierz opcję "Tylko wydania".
-
-Dzięki temu będziesz otrzymywać powiadomienia (na swój adres e-mail) za każdym razem, gdy pojawi się nowe wydanie (nowa wersja) **FastAPI** z poprawkami błędów i nowymi funkcjami.
-
-## Skontaktuj się z autorem
-
-Możesz skontaktować się ze mną (Sebastián Ramírez / `tiangolo`), autorem.
-
-Możesz:
-
-* Śledzić mnie na **GitHubie**.
- * Zobacz inne projekty open source, które stworzyłem, a mogą być dla Ciebie pomocne.
- * Śledź mnie, aby dostać powiadomienie, gdy utworzę nowy projekt open source.
-* Śledzić mnie na **X (Twitter)** lub na Mastodonie.
- * Napisz mi, w jaki sposób korzystasz z FastAPI (uwielbiam o tym czytać).
- * Dowiedz się, gdy ogłoszę coś nowego lub wypuszczę nowe narzędzia.
- * Możesz także śledzić @fastapi na X (Twitter) (to oddzielne konto).
-* Nawiąż ze mną kontakt na **Linkedinie**.
- * Dowiedz się, gdy ogłoszę coś nowego lub wypuszczę nowe narzędzia (chociaż częściej korzystam z Twittera 🤷♂).
-* Czytaj moje posty (lub śledź mnie) na **Dev.to** lub na **Medium**.
- * Czytaj o innych pomysłach, artykułach i dowiedz się o narzędziach, które stworzyłem.
- * Śledź mnie, by wiedzieć gdy opublikuję coś nowego.
-
-## Napisz tweeta o **FastAPI**
-
-Napisz tweeta o **FastAPI** i powiedz czemu Ci się podoba. 🎉
-
-Uwielbiam czytać w jaki sposób **FastAPI** jest używane, co Ci się w nim podobało, w jakim projekcie/firmie go używasz itp.
-
-## Głosuj na FastAPI
-
-* Głosuj na **FastAPI** w Slant.
-* Głosuj na **FastAPI** w AlternativeTo.
-* Powiedz, że używasz **FastAPI** na StackShare.
-
-## Pomagaj innym, odpowiadając na ich pytania na GitHubie
-
-Możesz spróbować pomóc innym, odpowiadając w:
-
-* Dyskusjach na GitHubie
-* Problemach na GitHubie
-
-W wielu przypadkach możesz już znać odpowiedź na te pytania. 🤓
-
-Jeśli pomożesz wielu ludziom, możesz zostać oficjalnym [Ekspertem FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. 🎉
-
-Pamiętaj tylko o najważniejszym: bądź życzliwy. Ludzie przychodzą sfrustrowani i w wielu przypadkach nie zadają pytań w najlepszy sposób, ale mimo to postaraj się być dla nich jak najbardziej życzliwy. 🤗
-
-Chciałbym, by społeczność **FastAPI** była życzliwa i przyjazna. Nie akceptuj prześladowania ani braku szacunku wobec innych. Dbajmy o siebie nawzajem.
-
----
-
-Oto, jak pomóc innym z pytaniami (w dyskusjach lub problemach):
-
-### Zrozum pytanie
-
-* Upewnij się, czy rozumiesz **cel** i przypadek użycia osoby pytającej.
-
-* Następnie sprawdź, czy pytanie (większość to pytania) jest **jasne**.
-
-* W wielu przypadkach zadane pytanie dotyczy rozwiązania wymyślonego przez użytkownika, ale może istnieć **lepsze** rozwiązanie. Jeśli dokładnie zrozumiesz problem i przypadek użycia, być może będziesz mógł zaproponować lepsze **alternatywne rozwiązanie**.
-
-* Jeśli nie rozumiesz pytania, poproś o więcej **szczegółów**.
-
-### Odtwórz problem
-
-W większości przypadków problem wynika z **autorskiego kodu** osoby pytającej.
-
-Często pytający umieszczają tylko fragment kodu, niewystarczający do **odtworzenia problemu**.
-
-* Możesz poprosić ich o dostarczenie minimalnego, odtwarzalnego przykładu, który możesz **skopiować i wkleić** i uruchomić lokalnie, aby zobaczyć ten sam błąd lub zachowanie, które widzą, lub lepiej zrozumieć ich przypadki użycia.
-
-* Jeśli jesteś wyjątkowo pomocny, możesz spróbować **stworzyć taki przykład** samodzielnie, opierając się tylko na opisie problemu. Miej na uwadze, że może to zająć dużo czasu i lepiej może być najpierw poprosić ich o wyjaśnienie problemu.
-
-### Proponuj rozwiązania
-
-* Po zrozumieniu pytania możesz podać im możliwą **odpowiedź**.
-
-* W wielu przypadkach lepiej zrozumieć ich **podstawowy problem lub przypadek użycia**, ponieważ może istnieć lepszy sposób rozwiązania niż to, co próbują zrobić.
-
-### Poproś o zamknięcie
-
-Jeśli odpowiedzą, jest duża szansa, że rozwiązałeś ich problem, gratulacje, **jesteś bohaterem**! 🦸
-
-* Jeśli Twoja odpowiedź rozwiązała problem, możesz poprosić o:
-
- * W Dyskusjach na GitHubie: oznaczenie komentarza jako **odpowiedź**.
- * W Problemach na GitHubie: **zamknięcie** problemu.
-
-## Obserwuj repozytorium na GitHubie
-
-Możesz "obserwować" FastAPI na GitHubie (klikając przycisk "obserwuj" w prawym górnym rogu): https://github.com/fastapi/fastapi. 👀
-
-Jeśli wybierzesz "Obserwuj" zamiast "Tylko wydania", otrzymasz powiadomienia, gdy ktoś utworzy nowy problem lub pytanie. Możesz również określić, że chcesz być powiadamiany tylko o nowych problemach, dyskusjach, PR-ach itp.
-
-Następnie możesz spróbować pomóc rozwiązać te problemy.
-
-## Zadawaj pytania
-
-Możesz utworzyć nowe pytanie w repozytorium na GitHubie, na przykład aby:
-
-* Zadać **pytanie** lub zapytać o **problem**.
-* Zaproponować nową **funkcję**.
-
-**Uwaga**: jeśli to zrobisz, poproszę Cię również o pomoc innym. 😉
-
-## Przeglądaj Pull Requesty
-
-Możesz pomóc mi w przeglądaniu pull requestów autorstwa innych osób.
-
-Jak wcześniej wspomniałem, postaraj się być jak najbardziej życzliwy. 🤗
-
----
-
-Oto, co warto mieć na uwadze podczas oceny pull requestu:
-
-### Zrozum problem
-
-* Najpierw upewnij się, że **rozumiesz problem**, który próbuje rozwiązać pull request. Może być osadzony w większym kontekście w GitHubowej dyskusji lub problemie.
-
-* Jest też duża szansa, że pull request nie jest konieczny, ponieważ problem można rozwiązać w **inny sposób**. Wtedy możesz to zasugerować lub o to zapytać.
-
-### Nie martw się stylem
-
-* Nie przejmuj się zbytnio rzeczami takimi jak style wiadomości commitów, przy wcielaniu pull requesta łączę commity i modyfikuję opis sumarycznego commita ręcznie.
-
-* Nie przejmuj się również stylem kodu, automatyczne narzędzia w repozytorium sprawdzają to samodzielnie.
-
-A jeśli istnieje jakaś konkretna potrzeba dotycząca stylu lub spójności, sam poproszę o zmiany lub dodam commity z takimi zmianami.
-
-### Sprawdź kod
-
-* Przeczytaj kod, zastanów się czy ma sens, **uruchom go lokalnie** i potwierdź czy faktycznie rozwiązuje problem.
-
-* Następnie dodaj **komentarz** z informacją o tym, że sprawdziłeś kod, dzięki temu będę miał pewność, że faktycznie go sprawdziłeś.
-
-/// info
-
-Niestety, nie mogę ślepo ufać PR-om, nawet jeśli mają kilka zatwierdzeń.
-
-Kilka razy zdarzyło się, że PR-y miały 3, 5 lub więcej zatwierdzeń (prawdopodobnie dlatego, że opis obiecuje rozwiązanie ważnego problemu), ale gdy sam sprawdziłem danego PR-a, okazał się być zbugowany lub nie rozwiązywał problemu, który rzekomo miał rozwiązywać. 😅
-
-Dlatego tak ważne jest, abyś faktycznie przeczytał i uruchomił kod oraz napisał w komentarzu, że to zrobiłeś. 🤓
-
-///
-
-* Jeśli PR można uprościć w jakiś sposób, możesz o to poprosić, ale nie ma potrzeby być zbyt wybrednym, może być wiele subiektywnych punktów widzenia (a ja też będę miał swój 🙈), więc lepiej żebyś skupił się na kluczowych rzeczach.
-
-### Testy
-
-* Pomóż mi sprawdzić, czy PR ma **testy**.
-
-* Sprawdź, czy testy **nie przechodzą** przed PR. 🚨
-
-* Następnie sprawdź, czy testy **przechodzą** po PR. ✅
-
-* Wiele PR-ów nie ma testów, możesz **przypomnieć** im o dodaniu testów, a nawet **zaproponować** samemu jakieś testy. To jedna z rzeczy, które pochłaniają najwięcej czasu i możesz w tym bardzo pomóc.
-
-* Następnie skomentuj również to, czego spróbowałeś, wtedy będę wiedział, że to sprawdziłeś. 🤓
-
-## Utwórz Pull Request
-
-Możesz [wnieść wkład](contributing.md){.internal-link target=_blank} do kodu źródłowego za pomocą Pull Requestu, na przykład:
-
-* Naprawić literówkę, którą znalazłeś w dokumentacji.
-* Podzielić się artykułem, filmem lub podcastem, który stworzyłeś lub znalazłeś na temat FastAPI, edytując ten plik.
- * Upewnij się, że dodajesz swój link na początku odpowiedniej sekcji.
-* Pomóc w [tłumaczeniu dokumentacji](contributing.md#translations){.internal-link target=_blank} na Twój język.
- * Możesz również pomóc w weryfikacji tłumaczeń stworzonych przez innych.
-* Zaproponować nowe sekcje dokumentacji.
-* Naprawić istniejący problem/błąd.
- * Upewnij się, że dodajesz testy.
-* Dodać nową funkcję.
- * Upewnij się, że dodajesz testy.
- * Upewnij się, że dodajesz dokumentację, jeśli jest to istotne.
-
-## Pomóż w utrzymaniu FastAPI
-
-Pomóż mi utrzymać **FastAPI**! 🤓
-
-Jest wiele pracy do zrobienia, a w większości przypadków **TY** możesz to zrobić.
-
-Główne zadania, które możesz wykonać teraz to:
-
-* [Pomóc innym z pytaniami na GitHubie](#pomagaj-innym-odpowiadajac-na-ich-pytania-na-githubie){.internal-link target=_blank} (zobacz sekcję powyżej).
-* [Oceniać Pull Requesty](#przegladaj-pull-requesty){.internal-link target=_blank} (zobacz sekcję powyżej).
-
-Te dwie czynności **zajmują najwięcej czasu**. To główna praca związana z utrzymaniem FastAPI.
-
-Jeśli możesz mi w tym pomóc, **pomożesz mi utrzymać FastAPI** i zapewnisz że będzie **rozwijać się szybciej i lepiej**. 🚀
-
-## Dołącz do czatu
-
-Dołącz do 👥 serwera czatu na Discordzie 👥 i spędzaj czas z innymi w społeczności FastAPI.
-
-/// tip | Wskazówka
-
-Jeśli masz pytania, zadaj je w Dyskusjach na GitHubie, jest dużo większa szansa, że otrzymasz pomoc od [Ekspertów FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}.
-
-Używaj czatu tylko do innych ogólnych rozmów.
-
-///
-
-### Nie zadawaj pytań na czacie
-
-Miej na uwadze, że ponieważ czaty pozwalają na bardziej "swobodną rozmowę", łatwo jest zadawać pytania, które są zbyt ogólne i trudniejsze do odpowiedzi, więc możesz nie otrzymać odpowiedzi.
-
-Na GitHubie szablon poprowadzi Cię do napisania odpowiedniego pytania, dzięki czemu łatwiej uzyskasz dobrą odpowiedź, a nawet rozwiążesz problem samodzielnie, zanim zapytasz. Ponadto na GitHubie mogę się upewnić, że zawsze odpowiadam na wszystko, nawet jeśli zajmuje to trochę czasu. Osobiście nie mogę tego zrobić z systemami czatu. 😅
-
-Rozmów w systemach czatu nie można tak łatwo przeszukiwać, jak na GitHubie, więc pytania i odpowiedzi mogą zaginąć w rozmowie. A tylko te na GitHubie liczą się do zostania [Ekspertem FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}, więc najprawdopodobniej otrzymasz więcej uwagi na GitHubie.
-
-Z drugiej strony w systemach czatu są tysiące użytkowników, więc jest duża szansa, że znajdziesz tam kogoś do rozmowy, prawie w każdej chwili. 😄
-
-## Wspieraj autora
-
-Możesz również finansowo wesprzeć autora (mnie) poprzez sponsoring na GitHubie.
-
-Tam możesz postawić mi kawę ☕️ aby podziękować. 😄
-
-Możesz także zostać srebrnym lub złotym sponsorem FastAPI. 🏅🎉
-
-## Wspieraj narzędzia, które napędzają FastAPI
-
-Jak widziałeś w dokumentacji, FastAPI stoi na ramionach gigantów, Starlette i Pydantic.
-
-Możesz również wesprzeć:
-
-* Samuel Colvin (Pydantic)
-* Encode (Starlette, Uvicorn)
-
----
-
-Dziękuję! 🚀
diff --git a/docs/pl/docs/index.md b/docs/pl/docs/index.md
deleted file mode 100644
index 976d610d4..000000000
--- a/docs/pl/docs/index.md
+++ /dev/null
@@ -1,467 +0,0 @@
-# FastAPI
-
-
-
-
-
-
- FastAPI to szybki, prosty w nauce i gotowy do użycia w produkcji framework -
- - ---- - -**Dokumentacja**: https://fastapi.tiangolo.com - -**Kod żródłowy**: https://github.com/fastapi/fastapi - ---- - -FastAPI to nowoczesny, wydajny framework webowy do budowania API z użyciem Pythona bazujący na standardowym typowaniu Pythona. - -Kluczowe cechy: - -* **Wydajność**: FastAPI jest bardzo wydajny, na równi z **NodeJS** oraz **Go** (dzięki Starlette i Pydantic). [Jeden z najszybszych dostępnych frameworków Pythonowych](#wydajnosc). -* **Szybkość kodowania**: Przyśpiesza szybkość pisania nowych funkcjonalności o około 200% do 300%. * -* **Mniejsza ilość błędów**: Zmniejsza ilość ludzkich (dewelopera) błędy o około 40%. * -* **Intuicyjność**: Wspaniałe wsparcie dla edytorów kodu. Dostępne wszędzie automatyczne uzupełnianie kodu. Krótszy czas debugowania. -* **Łatwość**: Zaprojektowany by być prosty i łatwy do nauczenia. Mniej czasu spędzonego na czytanie dokumentacji. -* **Kompaktowość**: Minimalizacja powtarzającego się kodu. Wiele funkcjonalności dla każdej deklaracji parametru. Mniej błędów. -* **Solidność**: Kod gotowy dla środowiska produkcyjnego. Wraz z automatyczną interaktywną dokumentacją. -* **Bazujący na standardach**: Oparty na (i w pełni kompatybilny z) otwartych standardach API: OpenAPI (wcześniej znane jako Swagger) oraz JSON Schema. - -* oszacowania bazowane na testach wykonanych przez wewnętrzny zespół deweloperów, budujących aplikacie używane na środowisku produkcyjnym. - -## Sponsorzy - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Jeżeli tworzysz aplikacje CLI, która ma być używana w terminalu zamiast API, sprawdź **Typer**.
-
-**Typer** to młodsze rodzeństwo FastAPI. Jego celem jest pozostanie **FastAPI aplikacji konsolowych** . ⌨️ 🚀
-
-## Wymagania
-
-FastAPI oparty jest na:
-
-* Starlette dla części webowej.
-* Pydantic dla części obsługujących dane.
-
-## Instalacja
-
-async def...uvicorn main:app --reload...email-validator - dla walidacji adresów email.
-
-Używane przez Starlette:
-
-* httpx - Wymagane jeżeli chcesz korzystać z `TestClient`.
-* aiofiles - Wymagane jeżeli chcesz korzystać z `FileResponse` albo `StaticFiles`.
-* jinja2 - Wymagane jeżeli chcesz używać domyślnej konfiguracji szablonów.
-* python-multipart - Wymagane jeżelich chcesz wsparcie "parsowania" formularzy, używając `request.form()`.
-* itsdangerous - Wymagany dla wsparcia `SessionMiddleware`.
-* pyyaml - Wymagane dla wsparcia `SchemaGenerator` z Starlette (z FastAPI prawdopodobnie tego nie potrzebujesz).
-* graphene - Wymagane dla wsparcia `GraphQLApp`.
-
-Używane przez FastAPI / Starlette:
-
-* uvicorn - jako serwer, który ładuje i obsługuje Twoją aplikację.
-* orjson - Wymagane jeżeli chcesz używać `ORJSONResponse`.
-* ujson - Wymagane jeżeli chcesz korzystać z `UJSONResponse`.
-
-Możesz zainstalować wszystkie te aplikacje przy pomocy `pip install fastapi[all]`.
-
-## Licencja
-
-Ten projekt jest na licencji MIT.
diff --git a/docs/pl/docs/tutorial/first-steps.md b/docs/pl/docs/tutorial/first-steps.md
deleted file mode 100644
index 8fa4c75ad..000000000
--- a/docs/pl/docs/tutorial/first-steps.md
+++ /dev/null
@@ -1,335 +0,0 @@
-# Pierwsze kroki
-
-Najprostszy plik FastAPI może wyglądać tak:
-
-{* ../../docs_src/first_steps/tutorial001.py *}
-
-Skopiuj to do pliku `main.py`.
-
-Uruchom serwer:
-
-get
-
-/// info | `@decorator` Info
-
-Składnia `@something` jest w Pythonie nazywana "dekoratorem".
-
-Umieszczasz to na szczycie funkcji. Jak ładną ozdobną czapkę (chyba stąd wzięła się nazwa).
-
-"Dekorator" przyjmuje funkcję znajdującą się poniżej jego i coś z nią robi.
-
-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:
-
-* `@app.post()`
-* `@app.put()`
-* `@app.delete()`
-
-Oraz tych bardziej egzotycznych:
-
-* `@app.options()`
-* `@app.head()`
-* `@app.patch()`
-* `@app.trace()`
-
-/// tip
-
-Możesz dowolnie używać każdej operacji (metody HTTP).
-
-**FastAPI** nie narzuca żadnego konkretnego znaczenia.
-
-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ę**
-
-To jest nasza "**funkcja obsługująca ścieżkę**":
-
-* **ścieżka**: to `/`.
-* **operacja**: to `get`.
-* **funkcja**: to funkcja poniżej "dekoratora" (poniżej `@app.get("/")`).
-
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
-
-Jest to funkcja Python.
-
-Zostanie ona wywołana przez **FastAPI** za każdym razem, gdy otrzyma żądanie do adresu URL "`/`" przy użyciu operacji `GET`.
-
-W tym przypadku jest to funkcja "asynchroniczna".
-
----
-
-Możesz również zdefiniować to jako normalną funkcję zamiast `async def`:
-
-{* ../../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}.
-
-///
-
-### Krok 5: zwróć zawartość
-
-{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
-
-Możesz zwrócić `dict`, `list`, pojedynczą wartość jako `str`, `int`, itp.
-
-Możesz również zwrócić modele Pydantic (więcej o tym później).
-
-Istnieje wiele innych obiektów i modeli, które zostaną automatycznie skonwertowane do formatu JSON (w tym ORM itp.). Spróbuj użyć swoich ulubionych, jest bardzo prawdopodobne, że są już obsługiwane.
-
-## Podsumowanie
-
-* Zaimportuj `FastAPI`.
-* Stwórz instancję `app`.
-* Dodaj **dekorator operacji na ścieżce** (taki jak `@app.get("/")`).
-* Napisz **funkcję obsługującą ścieżkę** (taką jak `def root(): ...` powyżej).
-* Uruchom serwer deweloperski (`uvicorn main:app --reload`).
diff --git a/docs/pl/docs/tutorial/index.md b/docs/pl/docs/tutorial/index.md
deleted file mode 100644
index 66f7c6d62..000000000
--- a/docs/pl/docs/tutorial/index.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Samouczek
-
-Ten samouczek pokaże Ci, krok po kroku, jak używać większości funkcji **FastAPI**.
-
-Każda część korzysta z poprzednich, ale jest jednocześnie osobnym tematem. Możesz przejść bezpośrednio do każdego rozdziału, jeśli szukasz rozwiązania konkretnego problemu.
-
-Samouczek jest tak zbudowany, żeby służył jako punkt odniesienia w przyszłości.
-
-Możesz wracać i sprawdzać dokładnie to czego potrzebujesz.
-
-## Wykonywanie kodu
-
-Wszystkie fragmenty kodu mogą być skopiowane bezpośrednio i użyte (są poprawnymi i przetestowanymi plikami).
-
-Żeby wykonać każdy przykład skopiuj kod to pliku `main.py` i uruchom `uvicorn` za pomocą:
-
-lt
+* XWT
+* PSGI
+
+### O abbr fornece uma explicação { #the-abbr-gives-an-explanation }
+
+* cluster
+* Deep Learning
+
+### O abbr fornece uma frase completa e uma explicação { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | Informação
+
+Os atributos "title" dos elementos "abbr" são traduzidos seguindo algumas instruções específicas.
+
+As traduções podem adicionar seus próprios elementos "abbr" que o LLM não deve remover. Por exemplo, para explicar palavras em inglês.
+
+Veja a seção `### HTML abbr elements` no prompt geral em `scripts/translate.py`.
+
+////
+
+## Títulos { #headings }
+
+//// tab | Teste
+
+### Desenvolver uma webapp - um tutorial { #develop-a-webapp-a-tutorial }
+
+Olá.
+
+### Anotações de tipo e -anotações { #type-hints-and-annotations }
+
+Olá novamente.
+
+### Super- e subclasses { #super-and-subclasses }
+
+Olá novamente.
+
+////
+
+//// tab | Informação
+
+A única regra rígida para títulos é que o LLM deixe a parte do hash dentro de chaves inalterada, o que garante que os links não quebrem.
+
+Veja a seção `### Headings` no prompt geral em `scripts/translate.py`.
+
+Para algumas instruções específicas do idioma, veja, por exemplo, a seção `### Headings` em `docs/de/llm-prompt.md`.
+
+////
+
+## Termos usados na documentação { #terms-used-in-the-docs }
+
+//// tab | Teste
+
+* você
+* seu
+
+* por exemplo
+* etc.
+
+* `foo` como um `int`
+* `bar` como uma `str`
+* `baz` como uma `list`
+
+* o Tutorial - Guia do Usuário
+* o Guia do Usuário Avançado
+* a documentação do SQLModel
+* a documentação da API
+* a documentação automática
+
+* Ciência de Dados
+* Deep Learning
+* Aprendizado de Máquina
+* Injeção de Dependências
+* autenticação HTTP Basic
+* HTTP Digest
+* formato ISO
+* o padrão JSON Schema
+* o JSON schema
+* a definição do schema
+* Fluxo de Senha
+* Mobile
+
+* descontinuado
+* projetado
+* inválido
+* dinamicamente
+* padrão
+* padrão predefinido
+* sensível a maiúsculas e minúsculas
+* não sensível a maiúsculas e minúsculas
+
+* servir a aplicação
+* servir a página
+
+* o app
+* a aplicação
+
+* a requisição
+* a resposta
+* a resposta de erro
+
+* a operação de rota
+* o decorador de operação de rota
+* a função de operação de rota
+
+* o corpo
+* o corpo da requisição
+* o corpo da resposta
+* o corpo JSON
+* o corpo do formulário
+* o corpo do arquivo
+* o corpo da função
+
+* o parâmetro
+* o parâmetro de corpo
+* o parâmetro de path
+* o parâmetro de query
+* o parâmetro de cookie
+* o parâmetro de header
+* o parâmetro de formulário
+* o parâmetro da função
+
+* o evento
+* o evento de inicialização
+* a inicialização do servidor
+* o evento de encerramento
+* o evento de lifespan
+
+* o manipulador
+* o manipulador de eventos
+* o manipulador de exceções
+* tratar
+
+* o modelo
+* o modelo Pydantic
+* o modelo de dados
+* o modelo de banco de dados
+* o modelo de formulário
+* o objeto de modelo
+
+* a classe
+* a classe base
+* a classe pai
+* a subclasse
+* a classe filha
+* a classe irmã
+* o método de classe
+
+* o cabeçalho
+* os cabeçalhos
+* o cabeçalho de autorização
+* o cabeçalho `Authorization`
+* o cabeçalho encaminhado
+
+* o sistema de injeção de dependências
+* a dependência
+* o dependable
+* o dependant
+
+* limitado por I/O
+* limitado por CPU
+* concorrência
+* paralelismo
+* multiprocessamento
+
+* a env var
+* a variável de ambiente
+* o `PATH`
+* a variável `PATH`
+
+* a autenticação
+* o provedor de autenticação
+* a autorização
+* o formulário de autorização
+* o provedor de autorização
+* o usuário se autentica
+* o sistema autentica o usuário
+
+* a CLI
+* a interface de linha de comando
+
+* o servidor
+* o cliente
+
+* o provedor de nuvem
+* o serviço de nuvem
+
+* o desenvolvimento
+* as etapas de desenvolvimento
+
+* o dict
+* o dicionário
+* a enumeração
+* o enum
+* o membro do enum
+
+* o codificador
+* o decodificador
+* codificar
+* decodificar
+
+* a exceção
+* lançar
+
+* a expressão
+* a instrução
+
+* o frontend
+* o backend
+
+* a discussão do GitHub
+* a issue do GitHub
+
+* o desempenho
+* a otimização de desempenho
+
+* o tipo de retorno
+* o valor de retorno
+
+* a segurança
+* o esquema de segurança
+
+* a tarefa
+* a tarefa em segundo plano
+* a função da tarefa
+
+* o template
+* o mecanismo de template
+
+* a anotação de tipo
+* a anotação de tipo
+
+* o worker de servidor
+* o worker do Uvicorn
+* o Worker do Gunicorn
+* o processo worker
+* a classe de worker
+* a carga de trabalho
+
+* a implantação
+* implantar
+
+* o SDK
+* o kit de desenvolvimento de software
+
+* o `APIRouter`
+* o `requirements.txt`
+* o Bearer Token
+* a alteração com quebra de compatibilidade
+* o bug
+* o botão
+* o chamável
+* o código
+* o commit
+* o gerenciador de contexto
+* a corrotina
+* a sessão do banco de dados
+* o disco
+* o domínio
+* o mecanismo
+* o X falso
+* o método HTTP GET
+* o item
+* a biblioteca
+* o lifespan
+* o bloqueio
+* o middleware
+* a aplicação mobile
+* o módulo
+* a montagem
+* a rede
+* a origem
+* a sobrescrita
+* a carga útil
+* o processador
+* a propriedade
+* o proxy
+* o pull request
+* a consulta
+* a RAM
+* a máquina remota
+* o código de status
+* a string
+* a tag
+* o framework web
+* o curinga
+* retornar
+* validar
+
+////
+
+//// tab | Informação
+
+Esta é uma lista não completa e não normativa de termos (principalmente) técnicos vistos na documentação. Pode ser útil para o designer do prompt descobrir para quais termos o LLM precisa de uma ajudinha. Por exemplo, quando ele continua revertendo uma boa tradução para uma tradução subótima. Ou quando tem problemas para conjugar/declinar um termo no seu idioma.
+
+Veja, por exemplo, a seção `### List of English terms and their preferred German translations` em `docs/de/llm-prompt.md`.
+
+////
diff --git a/docs/pt/docs/about/index.md b/docs/pt/docs/about/index.md
index 1f42e8831..39e160741 100644
--- a/docs/pt/docs/about/index.md
+++ b/docs/pt/docs/about/index.md
@@ -1,3 +1,3 @@
-# Sobre
+# Sobre { #about }
-Sobre o FastAPI, seus padrões, inspirações e muito mais. 🤓
+Sobre o FastAPI, seu design, inspiração e mais. 🤓
diff --git a/docs/pt/docs/advanced/additional-responses.md b/docs/pt/docs/advanced/additional-responses.md
index 1060d18af..688bc1696 100644
--- a/docs/pt/docs/advanced/additional-responses.md
+++ b/docs/pt/docs/advanced/additional-responses.md
@@ -1,6 +1,6 @@
-# Retornos Adicionais no OpenAPI
+# Retornos Adicionais no OpenAPI { #additional-responses-in-openapi }
-/// warning | Aviso
+/// warning | Atenção
Este é um tema bem avançado.
@@ -14,7 +14,7 @@ Essas respostas adicionais serão incluídas no esquema do OpenAPI, e também ap
Porém para as respostas adicionais, você deve garantir que está retornando um `Response` como por exemplo o `JSONResponse` diretamente, junto com o código de status e o conteúdo.
-## Retorno Adicional com `model`
+## Retorno Adicional com `model` { #additional-response-with-model }
Você pode fornecer o parâmetro `responses` aos seus *decoradores de caminho*.
@@ -26,7 +26,7 @@ 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:
-{* ../../docs_src/additional_responses/tutorial001.py hl[18,22] *}
+{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
/// note | Nota
@@ -49,7 +49,7 @@ O local correto é:
///
-O retorno gerado no OpenAI para esta *operação de caminho* será:
+O retorno gerado no OpenAPI para esta *operação de rota* será:
```JSON hl_lines="3-12"
{
@@ -169,13 +169,13 @@ Os esquemas são referenciados em outro local dentro do esquema OpenAPI:
}
```
-## Media types adicionais para o retorno principal
+## Media types adicionais para o retorno principal { #additional-media-types-for-the-main-response }
Você pode utilizar o mesmo parâmetro `responses` para adicionar diferentes media types para o mesmo retorno principal.
-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:
+Por exemplo, você pode adicionar um media type adicional de `image/png`, declarando que a sua *operação de rota* pode retornar um objeto JSON (com o media type `application/json`) ou uma imagem PNG:
-{* ../../docs_src/additional_responses/tutorial002.py hl[19:24,28] *}
+{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
/// note | Nota
@@ -191,7 +191,7 @@ Porém se você especificou uma classe de retorno com o valor `None` como media
///
-## Combinando informações
+## Combinando informações { #combining-information }
Você também pode combinar informações de diferentes lugares, incluindo os parâmetros `response_model`, `status_code`, e `responses`.
@@ -203,15 +203,15 @@ 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:
-{* ../../docs_src/additional_responses/tutorial003.py hl[20:31] *}
+{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
Isso será combinado e incluído em seu OpenAPI, e disponibilizado na documentação da sua API:
-## Combinar retornos predefinidos e personalizados
+## Combinar retornos predefinidos e personalizados { #combine-predefined-responses-and-custom-ones }
-Você pode querer possuir alguns retornos predefinidos que são aplicados para diversas *operações de caminho*, porém você deseja combinar com retornos personalizados que são necessários para cada *operação de caminho*.
+Você pode querer possuir alguns retornos predefinidos que são aplicados para diversas *operações de rota*, porém você deseja combinar com retornos personalizados que são necessários para cada *operação de rota*.
Para estes casos, você pode utilizar a técnica do Python de "desempacotamento" de um `dict` utilizando `**dict_to_unpack`:
@@ -233,15 +233,15 @@ Aqui, o `new_dict` terá todos os pares de chave-valor do `old_dict` mais o novo
}
```
-Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de caminho* e combiná-las com personalizações adicionais.
+Você pode utilizar essa técnica para reutilizar alguns retornos predefinidos nas suas *operações de rota* e combiná-las com personalizações adicionais.
Por exemplo:
-{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
-## Mais informações sobre retornos OpenAPI
+## Mais informações sobre retornos OpenAPI { #more-information-about-openapi-responses }
Para verificar exatamente o que você pode incluir nos retornos, você pode conferir estas seções na especificação do OpenAPI:
-* Objeto de Retorno OpenAPI, inclui o `Response Object`.
-* Objeto de Retorno OpenAPI, você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
+* Objeto de Retorno OpenAPI, inclui o `Response Object`.
+* Objeto de Retorno OpenAPI, você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
diff --git a/docs/pt/docs/advanced/additional-status-codes.md b/docs/pt/docs/advanced/additional-status-codes.md
index 06d619151..fd90b1795 100644
--- a/docs/pt/docs/advanced/additional-status-codes.md
+++ b/docs/pt/docs/advanced/additional-status-codes.md
@@ -1,22 +1,22 @@
-# Códigos de status adicionais
+# Códigos de status adicionais { #additional-status-codes }
-Por padrão, o **FastAPI** retornará as respostas utilizando o `JSONResponse`, adicionando o conteúdo do retorno da sua *operação de caminho* dentro do `JSONResponse`.
+Por padrão, o **FastAPI** retornará as respostas utilizando o `JSONResponse`, adicionando o conteúdo do retorno da sua *operação de rota* dentro do `JSONResponse`.
-Ele usará o código de status padrão ou o que você definir na sua *operação de caminho*.
+Ele usará o código de status padrão ou o que você definir na sua *operação de rota*.
-## Códigos de status adicionais
+## Códigos de status adicionais { #additional-status-codes_1 }
Caso você queira retornar códigos de status adicionais além do código principal, você pode fazer isso retornando um `Response` diretamente, como por exemplo um `JSONResponse`, e definir os códigos de status adicionais diretamente.
-Por exemplo, vamos dizer que você deseja ter uma *operação de caminho* que permita atualizar itens, e retornar um código de status HTTP 200 "OK" quando for bem sucedido.
+Por exemplo, vamos dizer que você deseja ter uma *operação de rota* que permita atualizar itens, e retornar um código de status HTTP 200 "OK" quando for bem sucedido.
-Mas você também deseja aceitar novos itens. E quando os itens não existiam, ele os cria, e retorna o código de status HTTP 201 "Created.
+Mas você também deseja aceitar novos itens. E quando os itens não existiam, ele os cria, e retorna o código de status HTTP 201 "Created".
Para conseguir isso, importe `JSONResponse` e retorne o seu conteúdo diretamente, definindo o `status_code` que você deseja:
{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
-/// warning | Aviso
+/// warning | Atenção
Quando você retorna um `Response` diretamente, como no exemplo acima, ele será retornado diretamente.
@@ -26,7 +26,7 @@ Garanta que ele tenha toda informação que você deseja, e que os valores sejam
///
-/// note | Detalhes técnicos
+/// note | Detalhes Técnicos
Você também pode utilizar `from starlette.responses import JSONResponse`.
@@ -34,7 +34,7 @@ O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` ape
///
-## OpenAPI e documentação da API
+## OpenAPI e documentação da API { #openapi-and-api-docs }
Se você retorna códigos de status adicionais e retornos diretamente, eles não serão incluídos no esquema do OpenAPI (a documentação da API), porque o FastAPI não tem como saber de antemão o que será retornado.
diff --git a/docs/pt/docs/advanced/advanced-dependencies.md b/docs/pt/docs/advanced/advanced-dependencies.md
index f57abba61..1ad9ea617 100644
--- a/docs/pt/docs/advanced/advanced-dependencies.md
+++ b/docs/pt/docs/advanced/advanced-dependencies.md
@@ -1,6 +1,6 @@
-# Dependências avançadas
+# Dependências avançadas { #advanced-dependencies }
-## Dependências parametrizadas
+## Dependências parametrizadas { #parameterized-dependencies }
Todas as dependências que vimos até agora são funções ou classes fixas.
@@ -10,7 +10,7 @@ Vamos imaginar que queremos ter uma dependência que verifica se o parâmetro de
Porém nós queremos poder parametrizar o conteúdo fixo.
-## Uma instância "chamável"
+## Uma instância "chamável" { #a-callable-instance }
Em Python existe uma maneira de fazer com que uma instância de uma classe seja um "chamável".
@@ -22,7 +22,7 @@ Para fazer isso, nós declaramos o método `__call__`:
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.
-## Parametrizar a instância
+## Parametrizar a instância { #parameterize-the-instance }
E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da instância que podemos utilizar para "parametrizar" a dependência:
@@ -30,7 +30,7 @@ E agora, nós podemos utilizar o `__init__` para declarar os parâmetros da inst
Neste caso, o **FastAPI** nunca tocará ou se importará com o `__init__`, nós vamos utilizar diretamente em nosso código.
-## Crie uma instância
+## Crie uma instância { #create-an-instance }
Nós poderíamos criar uma instância desta classe com:
@@ -38,7 +38,7 @@ Nós poderíamos criar uma instância desta classe com:
E deste modo nós podemos "parametrizar" a nossa dependência, que agora possui `"bar"` dentro dele, como o atributo `checker.fixed_content`.
-## Utilize a instância como dependência
+## Utilize a instância como dependência { #use-the-instance-as-a-dependency }
Então, nós podemos utilizar este `checker` em um `Depends(checker)`, no lugar de `Depends(FixedContentQueryChecker)`, porque a dependência é a instância, `checker`, e não a própria classe.
@@ -63,3 +63,101 @@ Nos capítulos sobre segurança, existem funções utilitárias que são impleme
Se você entendeu tudo isso, você já sabe como essas funções utilitárias para segurança funcionam por debaixo dos panos.
///
+
+## Dependências com `yield`, `HTTPException`, `except` e Tarefas em Segundo Plano { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | Atenção
+
+Muito provavelmente você não precisa desses detalhes técnicos.
+
+Esses detalhes são úteis principalmente se você tinha uma aplicação FastAPI anterior à versão 0.121.0 e está enfrentando problemas com dependências com `yield`.
+
+///
+
+Dependências com `yield` evoluíram ao longo do tempo para contemplar diferentes casos de uso e corrigir alguns problemas, aqui está um resumo do que mudou.
+
+### Dependências com `yield` e `scope` { #dependencies-with-yield-and-scope }
+
+Na versão 0.121.0, o FastAPI adicionou suporte a `Depends(scope="function")` para dependências com `yield`.
+
+Usando `Depends(scope="function")`, o código de saída após o `yield` é executado logo depois que a *função de operação de rota* termina, antes de a response ser enviada de volta ao cliente.
+
+E ao usar `Depends(scope="request")` (o padrão), o código de saída após o `yield` é executado depois que a response é enviada.
+
+Você pode ler mais na documentação em [Dependências com `yield` - Saída antecipada e `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).
+
+### Dependências com `yield` e `StreamingResponse`, Detalhes Técnicos { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+Antes do FastAPI 0.118.0, se você usasse uma dependência com `yield`, o código de saída (após o `yield`) rodaria depois que a *função de operação de rota* retornasse, mas logo antes de enviar a resposta.
+
+A intenção era evitar manter recursos por mais tempo que o necessário, esperando a resposta percorrer a rede.
+
+Essa mudança também significava que, se você retornasse um `StreamingResponse`, o código de saída da dependência com `yield` já teria sido executado.
+
+Por exemplo, se você tivesse uma sessão de banco de dados em uma dependência com `yield`, o `StreamingResponse` não conseguiria usar essa sessão enquanto transmite dados, porque a sessão já teria sido fechada no código de saída após o `yield`.
+
+Esse comportamento foi revertido na versão 0.118.0, para que o código de saída após o `yield` seja executado depois que a resposta for enviada.
+
+/// info | Informação
+
+Como você verá abaixo, isso é muito semelhante ao comportamento antes da versão 0.106.0, mas com várias melhorias e correções de bugs para casos extremos.
+
+///
+
+#### Casos de uso com código de saída antecipado { #use-cases-with-early-exit-code }
+
+Há alguns casos de uso, com condições específicas, que poderiam se beneficiar do comportamento antigo de executar o código de saída das dependências com `yield` antes de enviar a resposta.
+
+Por exemplo, imagine que você tem código que usa uma sessão de banco de dados em uma dependência com `yield` apenas para verificar um usuário, mas a sessão de banco de dados nunca é usada novamente na *função de operação de rota*, somente na dependência, e a resposta demora a ser enviada, como um `StreamingResponse` que envia dados lentamente, mas por algum motivo não usa o banco de dados.
+
+Nesse caso, a sessão de banco de dados seria mantida até que a resposta termine de ser enviada, mas se você não a usa, então não seria necessário mantê-la.
+
+Veja como poderia ser:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+O código de saída, o fechamento automático da `Session` em:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+...seria executado depois que a resposta terminar de enviar os dados lentos:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+Mas como `generate_stream()` não usa a sessão do banco de dados, não é realmente necessário manter a sessão aberta enquanto envia a resposta.
+
+Se você tiver esse caso específico usando SQLModel (ou SQLAlchemy), você poderia fechar explicitamente a sessão depois que não precisar mais dela:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+Dessa forma a sessão liberaria a conexão com o banco de dados, para que outras requisições pudessem usá-la.
+
+Se você tiver um caso diferente que precise sair antecipadamente de uma dependência com `yield`, por favor crie uma Pergunta no GitHub Discussions com o seu caso específico e por que você se beneficiaria de ter o fechamento antecipado para dependências com `yield`.
+
+Se houver casos de uso convincentes para fechamento antecipado em dependências com `yield`, considerarei adicionar uma nova forma de optar por esse fechamento antecipado.
+
+### Dependências com `yield` e `except`, Detalhes Técnicos { #dependencies-with-yield-and-except-technical-details }
+
+Antes do FastAPI 0.110.0, se você usasse uma dependência com `yield`, e então capturasse uma exceção com `except` nessa dependência, e você não relançasse a exceção, a exceção seria automaticamente levantada/encaminhada para quaisquer tratadores de exceção ou para o tratador de erro interno do servidor.
+
+Isso foi alterado na versão 0.110.0 para corrigir consumo de memória não tratado decorrente de exceções encaminhadas sem um tratador (erros internos do servidor), e para torná-lo consistente com o comportamento do código Python regular.
+
+### Tarefas em Segundo Plano e Dependências com `yield`, Detalhes Técnicos { #background-tasks-and-dependencies-with-yield-technical-details }
+
+Antes do FastAPI 0.106.0, lançar exceções após o `yield` não era possível, o código de saída em dependências com `yield` era executado depois que a resposta era enviada, então [Tratadores de Exceções](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} já teriam sido executados.
+
+Isso foi projetado assim principalmente para permitir o uso dos mesmos objetos "yielded" por dependências dentro de tarefas em segundo plano, porque o código de saída seria executado depois que as tarefas em segundo plano fossem concluídas.
+
+Isso foi alterado no FastAPI 0.106.0 com a intenção de não manter recursos enquanto se espera a resposta percorrer a rede.
+
+/// tip | Dica
+
+Além disso, uma tarefa em segundo plano normalmente é um conjunto de lógica independente que deve ser tratado separadamente, com seus próprios recursos (por exemplo, sua própria conexão de banco de dados).
+
+Assim, desta forma você provavelmente terá um código mais limpo.
+
+///
+
+Se você costumava depender desse comportamento, agora você deve criar os recursos para tarefas em segundo plano dentro da própria tarefa em segundo plano, e usar internamente apenas dados que não dependam dos recursos de dependências com `yield`.
+
+Por exemplo, em vez de usar a mesma sessão de banco de dados, você criaria uma nova sessão de banco de dados dentro da tarefa em segundo plano, e obteria os objetos do banco de dados usando essa nova sessão. E então, em vez de passar o objeto do banco de dados como parâmetro para a função da tarefa em segundo plano, você passaria o ID desse objeto e então obteria o objeto novamente dentro da função da tarefa em segundo plano.
diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md
index a2b79426c..953ebedd9 100644
--- a/docs/pt/docs/advanced/async-tests.md
+++ b/docs/pt/docs/advanced/async-tests.md
@@ -1,4 +1,4 @@
-# Testes Assíncronos
+# Testes Assíncronos { #async-tests }
Você já viu como testar as suas aplicações **FastAPI** utilizando o `TestClient` que é fornecido. Até agora, você viu apenas como escrever testes síncronos, sem utilizar funções `async`.
@@ -6,11 +6,11 @@ Ser capaz de utilizar funções assíncronas em seus testes pode ser útil, por
Vamos ver como nós podemos fazer isso funcionar.
-## pytest.mark.anyio
+## pytest.mark.anyio { #pytest-mark-anyio }
Se quisermos chamar funções assíncronas em nossos testes, as nossas funções de teste precisam ser assíncronas. O AnyIO oferece um plugin bem legal para isso, que nos permite especificar que algumas das nossas funções de teste precisam ser chamadas de forma assíncrona.
-## HTTPX
+## HTTPX { #httpx }
Mesmo que a sua aplicação **FastAPI** utilize funções normais com `def` no lugar de `async def`, ela ainda é uma aplicação `async` por baixo dos panos.
@@ -18,7 +18,7 @@ O `TestClient` faz algumas mágicas para invocar a aplicação FastAPI assíncro
O `TestClient` é baseado no HTTPX, e felizmente nós podemos utilizá-lo diretamente para testar a API.
-## Exemplo
+## Exemplo { #example }
Para um exemplos simples, vamos considerar uma estrutura de arquivos semelhante ao descrito em [Bigger Applications](../tutorial/bigger-applications.md){.internal-link target=_blank} e [Testing](../tutorial/testing.md){.internal-link target=_blank}:
@@ -32,13 +32,13 @@ Para um exemplos simples, vamos considerar uma estrutura de arquivos semelhante
O arquivo `main.py` teria:
-{* ../../docs_src/async_tests/main.py *}
+{* ../../docs_src/async_tests/app_a_py39/main.py *}
O arquivo `test_main.py` teria os testes para para o arquivo `main.py`, ele poderia ficar assim:
-{* ../../docs_src/async_tests/test_main.py *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py *}
-## Executá-lo
+## Executá-lo { #run-it }
Você pode executar os seus testes normalmente via:
@@ -52,11 +52,11 @@ $ pytest
-## Respostas disponíveis
+## Respostas disponíveis { #available-responses }
Aqui estão algumas dos tipos de resposta disponíveis.
@@ -121,7 +121,7 @@ O **FastAPI** provê a mesma `starlette.responses` como `fastapi.responses` apen
///
-### `Response`
+### `Response` { #response }
A classe principal de respostas, todas as outras respostas herdam dela.
@@ -136,25 +136,25 @@ Ela aceita os seguintes parâmetros:
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] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-### `HTMLResponse`
+### `HTMLResponse` { #htmlresponse }
Usa algum texto ou sequência de bytes e retorna uma resposta HTML. Como você leu acima.
-### `PlainTextResponse`
+### `PlainTextResponse` { #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] *}
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
-### `JSONResponse`
+### `JSONResponse` { #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`
+### `ORJSONResponse` { #orjsonresponse }
Uma alternativa mais rápida de resposta JSON utilizando o `orjson`, como você leu acima.
@@ -164,7 +164,7 @@ Essa resposta requer a instalação do pacote `orjson`, com o comando `pip insta
///
-### `UJSONResponse`
+### `UJSONResponse` { #ujsonresponse }
Uma alternativa de resposta JSON utilizando a biblioteca `ujson`.
@@ -174,13 +174,13 @@ Essa resposta requer a instalação do pacote `ujson`, com o comando `pip instal
///
-/// warning | Aviso
+/// warning | Atenção
`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] *}
+{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *}
/// tip | Dica
@@ -188,19 +188,19 @@ Essa resposta requer a instalação do pacote `ujson`, com o comando `pip instal
///
-### `RedirectResponse`
+### `RedirectResponse` { #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] *}
+{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *}
---
Ou você pode utilizá-la no parâmetro `response_class`:
-{* ../../docs_src/custom_response/tutorial006b.py hl[2,7,9] *}
+{* ../../docs_src/custom_response/tutorial006b_py39.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*
@@ -210,28 +210,26 @@ Neste caso, o `status_code` utilizada será o padrão de `RedirectResponse`, que
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] *}
+{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *}
-### `StreamingResponse`
+### `StreamingResponse` { #streamingresponse }
-Recebe uma gerador assíncrono ou um gerador/iterador comum e retorna o corpo da requisição continuamente (stream).
+Recebe um gerador assíncrono ou um gerador/iterador comum e retorna o corpo da resposta de forma contínua (stream).
-{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
+{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *}
-#### Utilizando `StreamingResponse` com objetos semelhantes a arquivos
+#### Utilizando `StreamingResponse` com objetos semelhantes a arquivos { #using-streamingresponse-with-file-like-objects }
-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.
+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!}
-```
+{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *}
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.
+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 enviada.
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.
@@ -244,10 +242,10 @@ Perceba que aqui estamos utilizando o `open()` da biblioteca padrão que não su
///
-### `FileResponse`
+### `FileResponse` { #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
@@ -257,15 +255,15 @@ Recebe um conjunto de argumentos do construtor diferente dos outros tipos de res
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] *}
+{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *}
Você também pode usar o parâmetro `response_class`:
-{* ../../docs_src/custom_response/tutorial009b.py hl[2,8,10] *}
+{* ../../docs_src/custom_response/tutorial009b_py39.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
+## Classe de resposta personalizada { #custom-response-class }
Você pode criar sua própria classe de resposta, herdando de `Response` e usando essa nova classe.
@@ -273,9 +271,9 @@ Por exemplo, vamos supor que você queira utilizar o `dataclasses` da mesma forma:
-{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
Isso ainda é suportado graças ao **Pydantic**, pois ele tem suporte interno para `dataclasses`.
@@ -28,11 +28,11 @@ Mas se você tem um monte de dataclasses por aí, este é um truque legal para u
///
-## Dataclasses em `response_model`
+## Dataclasses em `response_model` { #dataclasses-in-response-model }
Você também pode usar `dataclasses` no parâmetro `response_model`:
-{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}
A dataclass será automaticamente convertida para uma dataclass Pydantic.
@@ -40,7 +40,7 @@ Dessa forma, seu esquema aparecerá na interface de documentação da API:
-## Dataclasses em Estruturas de Dados Aninhadas
+## Dataclasses em Estruturas de Dados Aninhadas { #dataclasses-in-nested-data-structures }
Você também pode combinar `dataclasses` com outras anotações de tipo para criar estruturas de dados aninhadas.
@@ -48,9 +48,7 @@ Em alguns casos, você ainda pode ter que usar a versão do Pydantic das `datacl
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!}
-```
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
1. Ainda importamos `field` das `dataclasses` padrão.
@@ -86,12 +84,12 @@ Você pode combinar `dataclasses` com outras anotações de tipo em muitas combi
Confira as dicas de anotação no código acima para ver mais detalhes específicos.
-## Saiba Mais
+## Saiba Mais { #learn-more }
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
+## Versão { #version }
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 504b6db57..8cdc35828 100644
--- a/docs/pt/docs/advanced/events.md
+++ b/docs/pt/docs/advanced/events.md
@@ -1,67 +1,66 @@
-# Eventos de vida útil
+# Eventos de lifespan { #lifespan-events }
-Você pode definir a lógica (código) que poderia ser executada antes da aplicação **inicializar**. Isso significa que esse código será executado **uma vez**, **antes** da aplicação **começar a receber requisições**.
+Você pode definir a lógica (código) que deve ser executada antes da aplicação **inicializar**. Isso significa que esse código será executado **uma vez**, **antes** de a aplicação **começar a receber requisições**.
-Do mesmo modo, você pode definir a lógica (código) que será executada quando a aplicação estiver sendo **encerrada**. Nesse caso, este código será executado **uma vez**, **depois** de ter possivelmente tratado **várias requisições**.
+Da mesma forma, você pode definir a lógica (código) que deve ser executada quando a aplicação estiver **encerrando**. Nesse caso, esse código será executado **uma vez**, **depois** de possivelmente ter tratado **várias requisições**.
-Por conta desse código ser executado antes da aplicação **começar** a receber requisições, e logo após **terminar** de lidar com as requisições, ele cobre toda a **vida útil** (_lifespan_) da aplicação (o termo "vida útil" será importante em um segundo 😉).
+Como esse código é executado antes de a aplicação **começar** a receber requisições e logo depois que ela **termina** de lidar com as requisições, ele cobre todo o **lifespan** da aplicação (a palavra "lifespan" será importante em um segundo 😉).
-Pode ser muito útil para configurar **recursos** que você precisa usar por toda aplicação, e que são **compartilhados** entre as requisições, e/ou que você precisa **limpar** depois. Por exemplo, o pool de uma conexão com o banco de dados ou carregamento de um modelo compartilhado de aprendizado de máquina (_machine learning_).
+Isso pode ser muito útil para configurar **recursos** que você precisa usar por toda a aplicação, e que são **compartilhados** entre as requisições e/ou que você precisa **limpar** depois. Por exemplo, um pool de conexões com o banco de dados ou o carregamento de um modelo de machine learning compartilhado.
-## Caso de uso
+## Caso de uso { #use-case }
-Vamos iniciar com um exemplo de **caso de uso** e então ver como resolvê-lo com isso.
+Vamos começar com um exemplo de **caso de uso** e então ver como resolvê-lo com isso.
-Vamos imaginar que você tem alguns **modelos de _machine learning_** que deseja usar para lidar com as requisições. 🤖
+Vamos imaginar que você tem alguns **modelos de machine learning** que deseja usar para lidar com as requisições. 🤖
-Os mesmos modelos são compartilhados entre as requisições, então não é um modelo por requisição, ou um por usuário ou algo parecido.
+Os mesmos modelos são compartilhados entre as requisições, então não é um modelo por requisição, ou um por usuário, ou algo parecido.
-Vamos imaginar que o carregamento do modelo pode **demorar bastante tempo**, porque ele tem que ler muitos **dados do disco**. Então você não quer fazer isso a cada requisição.
+Vamos imaginar que o carregamento do modelo pode **demorar bastante tempo**, porque ele precisa ler muitos **dados do disco**. Então você não quer fazer isso a cada requisição.
-Você poderia carregá-lo no nível mais alto do módulo/arquivo, mas isso também poderia significaria **carregar o modelo** mesmo se você estiver executando um simples teste automatizado, então esse teste poderia ser **lento** porque teria que esperar o carregamento do modelo antes de ser capaz de executar uma parte independente do código.
+Você poderia carregá-lo no nível mais alto do módulo/arquivo, mas isso também significaria **carregar o modelo** mesmo se você estivesse executando um teste automatizado simples; então esse teste poderia ser **lento** porque teria que esperar o carregamento do modelo antes de conseguir executar uma parte independente do código.
+É isso que vamos resolver: vamos carregar o modelo antes de as requisições serem tratadas, mas apenas um pouco antes de a aplicação começar a receber requisições, não enquanto o código estiver sendo carregado.
-Isso é que nós iremos resolver, vamos carregar o modelo antes das requisições serem manuseadas, mas apenas um pouco antes da aplicação começar a receber requisições, não enquanto o código estiver sendo carregado.
+## Lifespan { #lifespan }
-## Vida útil (_Lifespan_)
+Você pode definir essa lógica de *inicialização* e *encerramento* usando o parâmetro `lifespan` da aplicação `FastAPI`, e um "gerenciador de contexto" (vou mostrar o que é isso em um segundo).
-Você pode definir essa lógica de *inicialização* e *encerramento* usando os parâmetros de `lifespan` da aplicação `FastAPI`, e um "gerenciador de contexto" (te mostrarei o que é isso a seguir).
+Vamos começar com um exemplo e depois ver em detalhes.
-Vamos iniciar com um exemplo e ver isso detalhadamente.
+Nós criamos uma função assíncrona `lifespan()` com `yield` assim:
-Nós criamos uma função assíncrona chamada `lifespan()` com `yield` como este:
+{* ../../docs_src/events/tutorial003_py39.py hl[16,19] *}
-{* ../../docs_src/events/tutorial003.py hl[16,19] *}
+Aqui estamos simulando a operação de *inicialização* custosa de carregar o modelo, colocando a (falsa) função do modelo no dicionário com modelos de machine learning antes do `yield`. Esse código será executado **antes** de a aplicação **começar a receber requisições**, durante a *inicialização*.
-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.
+E então, logo após o `yield`, descarregamos o modelo. Esse código será executado **depois** de a aplicação **terminar de lidar com as requisições**, pouco antes do *encerramento*. Isso poderia, por exemplo, liberar recursos como memória ou uma GPU.
/// tip | Dica
O `shutdown` aconteceria quando você estivesse **encerrando** a aplicação.
-Talvez você precise inicializar uma nova versão, ou apenas cansou de executá-la. 🤷
+Talvez você precise iniciar uma nova versão, ou apenas cansou de executá-la. 🤷
///
-### Função _lifespan_
+### Função lifespan { #lifespan-function }
-A primeira coisa a notar, é que estamos definindo uma função assíncrona com `yield`. Isso é muito semelhante à Dependências com `yield`.
+A primeira coisa a notar é que estamos definindo uma função assíncrona com `yield`. Isso é muito semelhante a Dependências com `yield`.
-{* ../../docs_src/events/tutorial003.py hl[14:19] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[14:19] *}
-A primeira parte da função, antes do `yield`, será executada **antes** da aplicação inicializar.
+A primeira parte da função, antes do `yield`, será executada **antes** de a aplicação iniciar.
-E a parte posterior do `yield` irá executar **após** a aplicação ser encerrada.
+E a parte posterior ao `yield` será executada **depois** de a aplicação ter terminado.
-### Gerenciador de Contexto Assíncrono
+### Gerenciador de contexto assíncrono { #async-context-manager }
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**".
+Isso converte a função em algo chamado "**gerenciador de contexto assíncrono**".
-{* ../../docs_src/events/tutorial003.py hl[1,13] *}
+{* ../../docs_src/events/tutorial003_py39.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:
@@ -70,97 +69,97 @@ with open("file.txt") as file:
file.read()
```
-Nas versões mais recentes de Python, há também um **gerenciador de contexto assíncrono**. Você o usaria com `async with`:
+Em versões mais recentes do Python, há também um **gerenciador de contexto assíncrono**. Você o usaria com `async with`:
```Python
async with lifespan(app):
await do_stuff()
```
-Quando você cria um gerenciador de contexto ou um gerenciador de contexto assíncrono como mencionado acima, o que ele faz é que, antes de entrar no bloco `with`, ele irá executar o código anterior ao `yield`, e depois de sair do bloco `with`, ele irá executar o código depois do `yield`.
+Quando você cria um gerenciador de contexto ou um gerenciador de contexto assíncrono como acima, o que ele faz é: antes de entrar no bloco `with`, ele executa o código antes do `yield`, e após sair do bloco `with`, ele executa o código depois do `yield`.
-No nosso exemplo de código acima, nós não usamos ele diretamente, mas nós passamos para o FastAPI para ele usá-lo.
+No nosso exemplo de código acima, não o usamos diretamente, mas passamos para o FastAPI para que ele o use.
-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.
+O parâmetro `lifespan` da aplicação `FastAPI` aceita um **gerenciador de contexto assíncrono**, então podemos passar para ele nosso novo gerenciador de contexto assíncrono `lifespan`.
-{* ../../docs_src/events/tutorial003.py hl[22] *}
+{* ../../docs_src/events/tutorial003_py39.py hl[22] *}
-## Eventos alternativos (deprecados)
+## Eventos alternativos (descontinuados) { #alternative-events-deprecated }
-/// warning | Aviso
+/// warning | Atenção
-A maneira recomendada para lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI` como descrito acima.
+A forma recomendada de lidar com a *inicialização* e o *encerramento* é usando o parâmetro `lifespan` da aplicação `FastAPI`, como descrito acima. Se você fornecer um parâmetro `lifespan`, os manipuladores de eventos `startup` e `shutdown` não serão mais chamados. É tudo `lifespan` ou tudo por eventos, não ambos.
-Você provavelmente pode pular essa parte.
+Você provavelmente pode pular esta parte.
///
-Existe uma forma alternativa para definir a execução dessa lógica durante *inicialização* e durante *encerramento*.
+Existe uma forma alternativa de definir essa lógica para ser executada durante a *inicialização* e durante o *encerramento*.
-Você pode definir manipuladores de eventos (funções) que precisam ser executadas antes da aplicação inicializar, ou quando a aplicação estiver encerrando.
+Você pode definir manipuladores de eventos (funções) que precisam ser executados antes de a aplicação iniciar ou quando a aplicação estiver encerrando.
Essas funções podem ser declaradas com `async def` ou `def` normal.
-### Evento `startup`
+### Evento `startup` { #startup-event }
-Para adicionar uma função que deve rodar antes da aplicação iniciar, declare-a com o evento `"startup"`:
+Para adicionar uma função que deve rodar antes de a aplicação iniciar, declare-a com o evento `"startup"`:
-{* ../../docs_src/events/tutorial001.py hl[8] *}
+{* ../../docs_src/events/tutorial001_py39.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.
+Nesse caso, a função de manipulador do evento `startup` inicializará os itens do "banco de dados" (apenas um `dict`) com alguns valores.
-Você pode adicionar mais que uma função de manipulação de evento.
+Você pode adicionar mais de uma função de manipulador de eventos.
-E sua aplicação não irá começar a receber requisições até que todos os manipuladores de eventos de `startup` sejam concluídos.
+E sua aplicação não começará a receber requisições até que todos os manipuladores de eventos `startup` sejam concluídos.
-### Evento `shutdown`
+### Evento `shutdown` { #shutdown-event }
-Para adicionar uma função que deve ser executada quando a aplicação estiver encerrando, declare ela com o evento `"shutdown"`:
+Para adicionar uma função que deve ser executada quando a aplicação estiver encerrando, declare-a com o evento `"shutdown"`:
-{* ../../docs_src/events/tutorial002.py hl[6] *}
+{* ../../docs_src/events/tutorial002_py39.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`.
+Aqui, a função de manipulador do evento `shutdown` 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.
+Na função `open()`, o `mode="a"` significa "acrescentar", então a linha será adicionada depois do que já estiver naquele arquivo, sem sobrescrever o conteúdo anterior.
///
/// tip | Dica
-Perceba que nesse caso nós estamos usando a função padrão do Python `open()` que interage com um arquivo.
+Perceba que, nesse caso, 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.
+Então, isso envolve I/O (input/output), que requer "esperar" que as 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`.
+Assim, declaramos a função de manipulador de evento com `def` padrão em vez de `async def`.
///
-### `startup` e `shutdown` juntos
+### `startup` e `shutdown` juntos { #startup-and-shutdown-together }
-Há uma grande chance que a lógica para sua *inicialização* e *encerramento* esteja conectada, você pode querer iniciar alguma coisa e então finalizá-la, adquirir um recurso e então liberá-lo, etc.
+Há uma grande chance de que a lógica para sua *inicialização* e *encerramento* esteja conectada, você pode querer iniciar alguma coisa e então finalizá-la, adquirir um recurso e então liberá-lo, etc.
-Fazendo isso em funções separadas que não compartilham lógica ou variáveis entre elas é mais difícil já que você precisa armazenar os valores em variáveis globais ou truques parecidos.
+Fazer isso em funções separadas que não compartilham lógica ou variáveis entre si é mais difícil, pois você precisaria armazenar valores em variáveis globais ou truques semelhantes.
-Por causa disso, agora é recomendado em vez disso usar o `lifespan` como explicado acima.
+Por causa disso, agora é recomendado usar o `lifespan`, como explicado acima.
-## Detalhes técnicos
+## Detalhes técnicos { #technical-details }
-Só um detalhe técnico para nerds curiosos. 🤓
+Apenas 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`.
+Por baixo, na especificação técnica do ASGI, isso é 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.
+Você pode ler mais sobre os manipuladores de `lifespan` do Starlette na Documentação do Lifespan do Starlette.
-Incluindo como manipular estado do lifespan que pode ser usado em outras áreas do seu código.
+Incluindo como lidar com estado do lifespan que pode ser usado em outras áreas do seu código.
///
-## Sub Aplicações
+## Sub Aplicações { #sub-applications }
-🚨 Tenha em mente que esses eventos de lifespan (de inicialização e desligamento) irão somente ser executados para a aplicação principal, não para [Sub Aplicações - Montagem](sub-applications.md){.internal-link target=_blank}.
+🚨 Tenha em mente que esses eventos de lifespan (inicialização e encerramento) serão executados apenas para a aplicação principal, não para [Sub Aplicações - Montagem](sub-applications.md){.internal-link target=_blank}.
diff --git a/docs/pt/docs/advanced/generate-clients.md b/docs/pt/docs/advanced/generate-clients.md
index dc6b29511..5134bc7cb 100644
--- a/docs/pt/docs/advanced/generate-clients.md
+++ b/docs/pt/docs/advanced/generate-clients.md
@@ -1,115 +1,76 @@
-# Generate Clients
+# Gerando SDKs { #generating-sdks }
-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).
+Como o **FastAPI** é baseado na especificação **OpenAPI**, suas APIs podem ser descritas em um formato padrão que muitas ferramentas entendem.
-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.
+Isso facilita gerar **documentação** atualizada, bibliotecas clientes (**SDKs**) em várias linguagens e **testes** ou **fluxos de trabalho de automação** que permanecem em sincronia com o seu código.
-## Geradores de Clientes OpenAPI
+Neste guia, você aprenderá como gerar um **SDK em TypeScript** para o seu backend FastAPI.
-Existem muitas ferramentas para gerar clientes a partir do **OpenAPI**.
+## Geradores de SDK de código aberto { #open-source-sdk-generators }
-Uma ferramenta comum é o OpenAPI Generator.
+Uma opção versátil é o OpenAPI Generator, que suporta **muitas linguagens de programação** e pode gerar SDKs a partir da sua especificação OpenAPI.
-Se voce está construindo um **frontend**, uma alternativa muito interessante é o openapi-ts.
+Para **clientes TypeScript**, o Hey API é uma solução feita sob medida, oferecendo uma experiência otimizada para o ecossistema TypeScript.
-## Geradores de Clientes e SDKs - Patrocinadores
+Você pode descobrir mais geradores de SDK em OpenAPI.Tools.
-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.
+/// tip | Dica
+
+O FastAPI gera automaticamente especificações **OpenAPI 3.1**, então qualquer ferramenta que você usar deve suportar essa versão.
+
+///
+
+## Geradores de SDK dos patrocinadores do FastAPI { #sdk-generators-from-fastapi-sponsors }
+
+Esta seção destaca soluções **financiadas por investimento** e **com suporte de empresas** que patrocinam o FastAPI. Esses produtos fornecem **funcionalidades adicionais** e **integrações** além de SDKs gerados com 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**.
+Ao ✨ [**patrocinar o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, essas empresas ajudam a garantir que o framework e seu **ecossistema** continuem saudáveis e **sustentáveis**.
-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. 🙇
+O patrocínio também demonstra um forte compromisso com a **comunidade** FastAPI (você), mostrando que elas se importam não apenas em oferecer um **ótimo serviço**, mas também em apoiar um **framework robusto e próspero**, o FastAPI. 🙇
Por exemplo, você pode querer experimentar:
* Speakeasy
-* Stainless
-* liblab
+* Stainless
+* liblab
-Existem também várias outras empresas que oferecem serviços semelhantes que você pode pesquisar e encontrar online. 🤓
+Algumas dessas soluções também podem ser open source ou oferecer planos gratuitos, para que você possa testá-las sem compromisso financeiro. Outros geradores comerciais de SDK estão disponíveis e podem ser encontrados online. 🤓
-## Gerar um Cliente Frontend TypeScript
+## Crie um SDK em TypeScript { #create-a-typescript-sdk }
-Vamos começar com um aplicativo **FastAPI** simples:
+Vamos começar com uma aplicação 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
+### Documentação da API { #api-docs }
-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:
+Se você for para `/docs`, 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).
+Essas informações estão disponíveis no **schema OpenAPI** do app e são mostradas na documentação da API.
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:
-
-
@@ -119,7 +80,7 @@ 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`.
+Observe o preenchimento automático para `name` e `price`, que foi definido na aplicação FastAPI, no modelo `Item`.
///
@@ -131,17 +92,17 @@ O objeto de resposta também terá preenchimento automático:
-## App FastAPI com Tags
+## Aplicação FastAPI com Tags { #fastapi-app-with-tags }
-Em muitos casos seu app FastAPI será maior, e você provavelmente usará tags para separar diferentes grupos de *operações de rota*.
+Em muitos casos, sua aplicação 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
+### Gere um cliente TypeScript com Tags { #generate-a-typescript-client-with-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.
+Se você gerar um cliente para uma aplicação 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:
@@ -152,33 +113,33 @@ Nesse caso você tem:
* `ItemsService`
* `UsersService`
-### Nomes dos Métodos do Cliente
+### Nomes dos métodos do cliente { #client-method-names }
-Agora os nomes dos métodos gerados como `createItemItemsPost` não parecem muito "limpos":
+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*.
+...isso ocorre porque o gerador de clientes usa o **ID de operação** 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.
+O OpenAPI exige que cada ID de operação seja único em todas as *operações de rota*, então o FastAPI usa o **nome da função**, o **path** e o **método/operação HTTP** para gerar esse ID de operação, porque dessa forma ele pode garantir que os IDs de operação sejam únicos.
Mas eu vou te mostrar como melhorar isso a seguir. 🤓
-### IDs de Operação Personalizados e Melhores Nomes de Método
+## IDs de operação personalizados e nomes de métodos melhores { #custom-operation-ids-and-better-method-names }
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).
+Por exemplo, você poderia garantir que cada *operação de rota* tenha uma tag, e então gerar o ID de 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
+### Função personalizada para gerar IDs exclusivos { #custom-generate-unique-id-function }
-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.
+O FastAPI usa um **ID exclusivo** para cada *operação de rota*, ele é usado para o **ID de 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.
+Você pode personalizar essa função. Ela recebe uma `APIRoute` e retorna 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).
@@ -186,15 +147,15 @@ Você pode então passar essa função personalizada para o **FastAPI** como o p
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
-### Gerar um Cliente TypeScript com IDs de Operação Personalizados
+### Gere um cliente TypeScript com IDs de operação personalizados { #generate-a-typescript-client-with-custom-operation-ids }
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.
+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 path da URL e da operação HTTP.
-### Pré-processar a Especificação OpenAPI para o Gerador de Clientes
+### Pré-processar a especificação OpenAPI para o gerador de clientes { #preprocess-the-openapi-specification-for-the-client-generator }
O código gerado ainda tem algumas **informações duplicadas**.
@@ -202,11 +163,11 @@ Nós já sabemos que esse método está relacionado aos **items** porque essa pa
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**.
+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 agradáveis e **limpos**.
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 *}
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
//// tab | Node.js
@@ -218,44 +179,30 @@ Poderíamos baixar o JSON do OpenAPI para um arquivo `openapi.json` e então pod
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"
- }
-}
+### Gere um cliente TypeScript com o OpenAPI pré-processado { #generate-a-typescript-client-with-the-preprocessed-openapi }
+
+Como o resultado final está agora em um arquivo `openapi.json`, você precisa atualizar o local de entrada:
+
+```sh
+npx @hey-api/openapi-ts -i ./openapi.json -o src/client
```
-Depois de gerar o novo cliente, você teria agora **nomes de métodos "limpos"**, com todo o **preenchimento automático**, **erros em linha**, etc:
+Depois de gerar o novo cliente, você terá agora **nomes de métodos “limpos”**, com todo o **preenchimento automático**, **erros em linha**, etc:
-## Benefícios
+## Benefícios { #benefits }
-Ao usar os clientes gerados automaticamente, você teria **preenchimento automático** para:
+Ao usar os clientes gerados automaticamente, você terá **preenchimento automático** para:
* Métodos.
-* Corpo de requisições, parâmetros da query, etc.
-* Corpo de respostas.
+* Corpos de requisições, parâmetros de query, etc.
+* Corpos de respostas.
-Você também teria **erros em linha** para tudo.
+Você também terá **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. 🤓
+E sempre que você atualizar o código do backend e **regenerar** o frontend, ele terá quaisquer novas *operações de rota* disponíveis como métodos, as antigas removidas, e qualquer outra alteração será 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.
+Isso também significa que, se algo mudou, será **refletido** no código do cliente automaticamente. E se você **construir** o cliente, ele falhará caso haja qualquer **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. ✨
+Assim, você **detectará muitos 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 22ba2bf4a..23e551074 100644
--- a/docs/pt/docs/advanced/index.md
+++ b/docs/pt/docs/advanced/index.md
@@ -1,10 +1,10 @@
-# Guia de Usuário Avançado
+# Guia de Usuário Avançado { #advanced-user-guide }
-## Recursos Adicionais
+## Recursos Adicionais { #additional-features }
O [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} deve ser o suficiente para dar a você um tour por todos os principais recursos do **FastAPI**.
-Na próxima seção você verá outras opções, configurações, e recursos adicionais.
+Nas próximas seções você verá outras opções, configurações, e recursos adicionais.
/// tip | Dica
@@ -14,14 +14,8 @@ E é possível que para seu caso de uso, a solução esteja em uma delas.
///
-## Leia o Tutorial primeiro
+## Leia o Tutorial primeiro { #read-the-tutorial-first }
Você ainda pode usar a maior parte dos recursos no **FastAPI** com o conhecimento do [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank}.
E as próximas seções assumem que você já leu ele, e que você conhece suas ideias principais.
-
-## Curso TestDriven.io
-
-Se você gostaria de fazer um curso avançado-iniciante para complementar essa seção da documentação, você pode querer conferir: Test-Driven Development com FastAPI e Docker por **TestDriven.io**.
-
-Eles estão atualmente doando 10% de todos os lucros para o desenvolvimento do **FastAPI**. 🎉 😄
diff --git a/docs/pt/docs/advanced/middleware.md b/docs/pt/docs/advanced/middleware.md
index 8167f7d27..30c183479 100644
--- a/docs/pt/docs/advanced/middleware.md
+++ b/docs/pt/docs/advanced/middleware.md
@@ -1,4 +1,4 @@
-# Middleware Avançado
+# Middleware Avançado { #advanced-middleware }
No tutorial principal você leu como adicionar [Middleware Personalizado](../tutorial/middleware.md){.internal-link target=_blank} à sua aplicação.
@@ -6,9 +6,9 @@ E então você também leu como lidar com [CORS com o `CORSMiddleware`](../tutor
Nesta seção, veremos como usar outros middlewares.
-## Adicionando middlewares ASGI
+## Adicionando middlewares ASGI { #adding-asgi-middlewares }
-Como o **FastAPI** é baseado no Starlette e implementa a especificação ASGI, você pode usar qualquer middleware 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.
@@ -39,52 +39,53 @@ 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
+## Middlewares Integrados { #integrated-middlewares }
**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`.
+Para os próximos exemplos, 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`
+## `HTTPSRedirectMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *}
-## `TrustedHostMiddleware`
+## `TrustedHostMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial002_py39.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.
+* `www_redirect` - Se definido como True, as requisições para versões sem www dos hosts permitidos serão redirecionadas para suas versões com www. O padrão é `True`.
Se uma requisição recebida não for validada corretamente, uma resposta `400` será enviada.
-## `GZipMiddleware`
+## `GZipMiddleware` { #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] *}
+{* ../../docs_src/advanced_middleware/tutorial003_py39.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
+## Outros middlewares { #other-middlewares }
Há muitos outros middlewares ASGI.
@@ -93,4 +94,4 @@ 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.
+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
index b0659d3d6..57c8c5e81 100644
--- a/docs/pt/docs/advanced/openapi-callbacks.md
+++ b/docs/pt/docs/advanced/openapi-callbacks.md
@@ -1,29 +1,29 @@
-# Callbacks na OpenAPI
+# Callbacks na OpenAPI { #openapi-callbacks }
-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).
+Você poderia criar uma API com uma *operação de rota* que poderia acionar um request 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).
+O processo que acontece quando sua aplicação de API chama a *API externa* é chamado de "callback". Porque o software que o desenvolvedor externo escreveu envia um request para sua API e então sua API *chama de volta*, enviando um request 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
+## Um aplicativo com callbacks { #an-app-with-callbacks }
Vamos ver tudo isso com um exemplo.
-Imagine que você tem um aplicativo que permite criar faturas.
+Imagine que você desenvolve 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.
+O usuário da sua API (um desenvolvedor externo) criará uma fatura na sua API com um request POST.
Então sua API irá (vamos imaginar):
-* Enviar uma solicitação de pagamento para o desenvolvedor externo.
+* Enviar a fatura para algum cliente do 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").
+ * Isso será feito enviando um request POST (de *sua API*) para alguma *API externa* fornecida por esse desenvolvedor externo (este é o "callback").
-## O aplicativo **FastAPI** normal
+## O aplicativo **FastAPI** normal { #the-normal-fastapi-app }
Vamos primeiro ver como o aplicativo da API normal se pareceria antes de adicionar o callback.
@@ -31,7 +31,7 @@ Ele terá uma *operação de rota* que receberá um corpo `Invoice`, e um parâm
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] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *}
/// tip | Dica
@@ -39,11 +39,11 @@ O parâmetro de consulta `callback_url` usa um tipo Pydantic HTTPX ou Requisições.
+Ao implementar o callback por conta própria, você pode usar algo como HTTPX ou Requests.
///
-## Escrevendo o código de documentação do callback
+## Escreva o código de documentação do callback { #write-the-callback-documentation-code }
Esse código não será executado em seu aplicativo, nós só precisamos dele para *documentar* como essa *API externa* deveria ser.
@@ -80,37 +80,37 @@ Então vamos usar esse mesmo conhecimento para documentar como a *API externa* d
/// 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*.
+Ao 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*.
+Adotar temporariamente esse ponto de vista (do *desenvolvedor externo*) pode ajudar a perceber mais facilmente 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
+### Crie um `APIRouter` de callback { #create-a-callback-apirouter }
-Primeiramente crie um novo `APIRouter` que conterá um ou mais callbacks.
+Primeiro crie um novo `APIRouter` que conterá um ou mais callbacks.
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *}
-### Crie a *operação de rota* do callback
+### Crie a *operação de rota* do callback { #create-the-callback-path-operation }
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:
+Ela 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`.
+* Ela provavelmente deveria ter uma declaração do corpo que deveria receber, por exemplo, `body: InvoiceEvent`.
+* E também poderia ter uma declaração da resposta que deveria retornar, por exemplo, `response_model=InvoiceEventReceived`.
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[16:18,21:22,28:32] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *}
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*.
+* O *path* pode conter uma expressão OpenAPI 3 (veja mais abaixo) em que 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 expressão do path do callback { #the-callback-path-expression }
-A *rota* do callback pode ter uma expressão OpenAPI 3 que pode conter partes da solicitação original enviada para *sua API*.
+O *path* 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`:
@@ -118,7 +118,7 @@ Nesse caso, é a `str`:
"{$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:
+Então, se o usuário da sua API (o desenvolvedor externo) enviar um request para *sua API* para:
```
https://yourapi.com/invoices/?callback_url=https://www.external.org/events
@@ -134,7 +134,7 @@ com um corpo JSON de:
}
```
-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*):
+então *sua API* processará a fatura e, em algum momento posterior, enviará um request de callback para o `callback_url` (a *API externa*):
```
https://www.external.org/events/invoices/2expen51ve
@@ -163,13 +163,13 @@ Perceba como a URL de callback usada contém a URL recebida como um parâmetro d
///
-### Adicionar o roteador de callback
+### Adicione o roteador de callback { #add-the-callback-router }
-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.
+Nesse ponto você tem a(s) *operação(ões) 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:
+Agora use o parâmetro `callbacks` no decorador da *operação de rota da sua API* para passar o atributo `.routes` (que é na verdade apenas uma `list` de rotas/*operações de path*) do roteador de callback:
-{* ../../docs_src/openapi_callbacks/tutorial001.py hl[35] *}
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Dica
@@ -177,7 +177,7 @@ Perceba que você não está passando o roteador em si (`invoices_callback_route
///
-### Verifique a documentação
+### Verifique a documentação { #check-the-docs }
Agora você pode iniciar seu aplicativo e ir para http://127.0.0.1:8000/docs.
diff --git a/docs/pt/docs/advanced/openapi-webhooks.md b/docs/pt/docs/advanced/openapi-webhooks.md
index f35922234..011898e8c 100644
--- a/docs/pt/docs/advanced/openapi-webhooks.md
+++ b/docs/pt/docs/advanced/openapi-webhooks.md
@@ -1,4 +1,4 @@
-# Webhooks OpenAPI
+# Webhooks OpenAPI { #openapi-webhooks }
Existem situações onde você deseja informar os **usuários** da sua API que a sua aplicação pode chamar a aplicação *deles* (enviando uma requisição) com alguns dados, normalmente para **notificar** algum tipo de **evento**.
@@ -6,7 +6,7 @@ Isso significa que no lugar do processo normal de seus usuários enviarem requis
Isso normalmente é chamado de **webhook**.
-## Etapas dos Webhooks
+## Etapas dos webhooks { #webhooks-steps }
Normalmente, o processo é que **você define** em seu código qual é a mensagem que você irá mandar, o **corpo da sua requisição**.
@@ -16,7 +16,7 @@ E os **seus usuários** definem de alguma forma (em algum painel por exemplo) a
Toda a **lógica** sobre como cadastrar as URLs para os webhooks e o código para enviar de fato as requisições cabe a você definir. Você escreve da maneira que você desejar no **seu próprio código**.
-## Documentando webhooks com o FastAPI e OpenAPI
+## Documentando webhooks com o FastAPI e OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }
Com o **FastAPI**, utilizando o OpenAPI, você pode definir os nomes destes webhooks, os tipos das operações HTTP que a sua aplicação pode enviar (e.g. `POST`, `PUT`, etc.) e os **corpos** da requisição que a sua aplicação enviaria.
@@ -28,11 +28,11 @@ Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do Fast
///
-## Uma aplicação com webhooks
+## Uma aplicação com webhooks { #an-app-with-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()`.
-{* ../../docs_src/openapi_webhooks/tutorial001.py hl[9:13,36:53] *}
+{* ../../docs_src/openapi_webhooks/tutorial001_py39.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.
@@ -42,11 +42,11 @@ O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que vo
///
-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`.
+Note que utilizando webhooks você não está de fato declarando um *path* (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`.
-Isto porque espera-se que os **seus usuários** definam o verdadeiro **caminho da URL** onde eles desejam receber a requisição do webhook de algum outra maneira. (e.g. um painel).
+Isto porque espera-se que os **seus usuários** definam o verdadeiro **URL path** onde eles desejam receber a requisição do webhook de algum outra maneira. (e.g. um painel).
-### Confira a documentação
+### Confira a documentação { #check-the-docs }
Agora você pode iniciar a sua aplicação e ir até http://127.0.0.1:8000/docs.
diff --git a/docs/pt/docs/advanced/path-operation-advanced-configuration.md b/docs/pt/docs/advanced/path-operation-advanced-configuration.md
index 411d0f9a7..b3af116a2 100644
--- a/docs/pt/docs/advanced/path-operation-advanced-configuration.md
+++ b/docs/pt/docs/advanced/path-operation-advanced-configuration.md
@@ -1,8 +1,8 @@
-# Configuração Avançada da Operação de Rota
+# Configuração Avançada da Operação de Rota { #path-operation-advanced-configuration }
-## operationId do OpenAPI
+## operationId do OpenAPI { #openapi-operationid }
-/// warning | Aviso
+/// warning | Atenção
Se você não é um "especialista" no OpenAPI, você provavelmente não precisa disso.
@@ -10,25 +10,25 @@ Se você não é um "especialista" no OpenAPI, você provavelmente não precisa
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.
+Você deveria ter certeza que ele é único para cada operação.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *}
-### Utilizando o nome da *função de operação de rota* como o operationId
+### Utilizando o nome da *função de operação de rota* como o operationId { #using-the-path-operation-function-name-as-the-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.
+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 `operation_id` 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*.
+Você deveria 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] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *}
/// tip | Dica
-Se você chamar `app.openapi()` manualmente, os `operationId`s devem ser atualizados antes dessa chamada.
+Se você chamar `app.openapi()` manualmente, você deveria atualizar os `operationId`s antes dessa chamada.
///
-/// warning | Aviso
+/// warning | Atenção
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.
@@ -36,23 +36,23 @@ Mesmo que elas estejam em módulos (arquivos Python) diferentes.
///
-## Excluir do OpenAPI
+## Excluir do OpenAPI { #exclude-from-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] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *}
-## Descrição avançada a partir de docstring
+## Descrição avançada a partir de docstring { #advanced-description-from-docstring }
-Você pode limitar as linhas utilizadas a partir de uma docstring de uma *função de operação de rota* para o OpenAPI.
+Você pode limitar as linhas utilizadas a partir da 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.
+Adicionar um `\f` (um caractere de escape para "form feed") faz com que o **FastAPI** trunque a saída usada para o 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.
+Ele não será mostrado na documentação, mas outras ferramentas (como o Sphinx) serão capazes de utilizar o resto.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
-## Respostas Adicionais
+## Respostas Adicionais { #additional-responses }
Você provavelmente já viu como declarar o `response_model` e `status_code` para uma *operação de rota*.
@@ -62,11 +62,11 @@ Você também pode declarar respostas adicionais, com seus modelos, códigos de
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
+## Extras do OpenAPI { #openapi-extra }
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
+/// note | Detalhes Técnicos
Na especificação do OpenAPI, isso é chamado de um Objeto de Operação.
@@ -88,11 +88,11 @@ Caso você só precise declarar respostas adicionais, uma forma conveniente de f
Você pode estender o esquema do OpenAPI para uma *operação de rota* utilizando o parâmetro `openapi_extra`.
-### Extensões do OpenAPI
+### Extensões do OpenAPI { #openapi-extensions }
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] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.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.
@@ -129,73 +129,41 @@ E se você olhar o esquema OpenAPI resultante (na rota `/openapi.json` da sua AP
}
```
-### Esquema de *operação de rota* do OpenAPI personalizado
+### Esquema de *operação de rota* do OpenAPI personalizado { #custom-openapi-path-operation-schema }
-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*.
+O dicionário em `openapi_extra` vai ser mesclado profundamente com o esquema OpenAPI gerado automaticamente para a *operação de rota*.
-Então, você pode adicionar dados extras para o esquema gerado automaticamente.
+Então, você pode adicionar dados extras ao 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.
+Por exemplo, você poderia decidir ler e validar a requisição com seu próprio código, sem usar as funcionalidades automáticas do FastAPI com o Pydantic, mas ainda assim querer 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] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.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.
+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
+### Tipo de conteúdo do OpenAPI personalizado { #custom-openapi-content-type }
-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*.
+Utilizando esse mesmo truque, você pode usar um modelo Pydantic para definir o JSON Schema 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.
+E você pode fazer isso até mesmo quando o tipo de dados na requisição não é 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:
+Por exemplo, nesta aplicação nós não usamos a funcionalidade integrada ao FastAPI de extrair o JSON Schema dos modelos Pydantic nem a validação automática para JSON. Na verdade, estamos declarando o tipo de conteúdo da requisição como YAML, em vez de JSON:
-//// tab | Pydantic v2
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *}
-{* ../../docs_src/path_operation_advanced_configuration/tutorial007.py hl[17:22,24] *}
+Entretanto, mesmo que não utilizemos a funcionalidade integrada por padrão, ainda estamos usando um modelo Pydantic para gerar um JSON Schema manualmente para os dados que queremos receber em 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 payload da requisição como JSON.
-//// tab | Pydantic v1
+E então no nosso código, nós analisamos o conteúdo YAML diretamente e, em seguida, estamos usando novamente o mesmo modelo Pydantic para validar o conteúdo YAML:
-{* ../../docs_src/path_operation_advanced_configuration/tutorial007_pv1.py hl[17:22,24] *}
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *}
-////
-
-/// 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
+/// tip | Dica
Aqui reutilizamos o mesmo modelo do Pydantic.
diff --git a/docs/pt/docs/advanced/response-change-status-code.md b/docs/pt/docs/advanced/response-change-status-code.md
index 358c12d54..ee81f0bfc 100644
--- a/docs/pt/docs/advanced/response-change-status-code.md
+++ b/docs/pt/docs/advanced/response-change-status-code.md
@@ -1,10 +1,10 @@
-# Retorno - Altere o Código de Status
+# Retorno - Altere o Código de Status { #response-change-status-code }
Você provavelmente leu anteriormente que você pode definir um [Código de Status do Retorno](../tutorial/response-status-code.md){.internal-link target=_blank} padrão.
Porém em alguns casos você precisa retornar um código de status diferente do padrão.
-## Caso de uso
+## Caso de uso { #use-case }
Por exemplo, imagine que você deseja retornar um código de status HTTP de "OK" `200` por padrão.
@@ -14,13 +14,13 @@ Mas você ainda quer ser capaz de filtrar e converter o dado que você retornar
Para estes casos, você pode utilizar um parâmetro `Response`.
-## Use um parâmetro `Response`
+## Use um parâmetro `Response` { #use-a-response-parameter }
Você pode declarar um parâmetro do tipo `Response` em sua *função de operação de rota* (assim como você pode fazer para cookies e headers).
E então você pode definir o `status_code` neste objeto de retorno temporal.
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.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
index eed69f222..67820b433 100644
--- a/docs/pt/docs/advanced/response-cookies.md
+++ b/docs/pt/docs/advanced/response-cookies.md
@@ -1,12 +1,12 @@
-# Cookies de Resposta
+# Cookies de Resposta { #response-cookies }
-## Usando um parâmetro `Response`
+## Use um parâmetro `Response` { #use-a-response-parameter }
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] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.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).
@@ -16,15 +16,15 @@ E se você declarou um `response_model`, ele ainda será usado para filtrar e co
Você também pode declarar o parâmetro `Response` em dependências e definir cookies (e cabeçalhos) nelas.
-## Retornando uma `Response` diretamente
+## Retorne uma `Response` diretamente { #return-a-response-directly }
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}.
+Para fazer isso, você pode criar uma resposta como descrito em [Retorne 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] *}
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
/// tip | Dica
@@ -36,7 +36,7 @@ E também que você não esteja enviando nenhum dado que deveria ter sido filtra
///
-### Mais informações
+### Mais informações { #more-info }
/// note | Detalhes Técnicos
@@ -48,4 +48,4 @@ E como o `Response` pode ser usado frequentemente para definir cabeçalhos e coo
///
-Para ver todos os parâmetros e opções disponíveis, verifique a documentação no Starlette.
+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
index ea717be00..bbbef2f91 100644
--- a/docs/pt/docs/advanced/response-directly.md
+++ b/docs/pt/docs/advanced/response-directly.md
@@ -1,4 +1,4 @@
-# Retornando uma Resposta Diretamente
+# Retornando uma Resposta Diretamente { #return-a-response-directly }
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.
@@ -10,7 +10,7 @@ Mas você pode retornar a `JSONResponse` diretamente nas suas *operações de ro
Pode ser útil para retornar cabeçalhos e cookies personalizados, por exemplo.
-## Retornando uma `Response`
+## Retornando uma `Response` { #return-a-response }
Na verdade, você pode retornar qualquer `Response` ou subclasse dela.
@@ -26,7 +26,7 @@ Ele não vai fazer conversões de dados com modelos do Pydantic, não irá conve
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`
+## Utilizando o `jsonable_encoder` em uma `Response` { #using-the-jsonable-encoder-in-a-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.
@@ -34,7 +34,7 @@ Por exemplo, você não pode colocar um modelo do Pydantic em uma `JSONResponse`
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] *}
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
/// note | Detalhes Técnicos
@@ -44,23 +44,22 @@ Você também pode utilizar `from starlette.responses import JSONResponse`.
///
-## Retornando uma `Response`
+## Retornando uma `Response` personalizada { #returning-a-custom-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.
+Vamos dizer que você 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] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-## Notas
+## Notas { #notes }
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}.
+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
index a8034a7a4..14c3fb186 100644
--- a/docs/pt/docs/advanced/response-headers.md
+++ b/docs/pt/docs/advanced/response-headers.md
@@ -1,12 +1,12 @@
-# Cabeçalhos de resposta
+# Cabeçalhos de resposta { #response-headers }
-## Usando um parâmetro `Response`
+## Use um parâmetro `Response` { #use-a-response-parameter }
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] *}
+{* ../../docs_src/response_headers/tutorial002_py39.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.).
@@ -16,15 +16,15 @@ Se você declarou um `response_model`, ele ainda será utilizado para filtrar e
Você também pode declarar o parâmetro `Response` em dependências e definir cabeçalhos (e cookies) nelas.
-## Retornar uma `Response` diretamente
+## Retorne uma `Response` diretamente { #return-a-response-directly }
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] *}
+{* ../../docs_src/response_headers/tutorial001_py39.py hl[10:12] *}
-/// note | Detalhes técnicos
+/// note | Detalhes Técnicos
Você também pode usar `from starlette.responses import Response` ou `from starlette.responses import JSONResponse`.
@@ -34,8 +34,8 @@ E como a `Response` pode ser usada frequentemente para definir cabeçalhos e coo
///
-## Cabeçalhos personalizados
+## Cabeçalhos personalizados { #custom-headers }
-Tenha em mente que cabeçalhos personalizados proprietários podem ser adicionados usando o prefixo 'X-'.
+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.
+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
index 331513927..bd572217b 100644
--- a/docs/pt/docs/advanced/security/http-basic-auth.md
+++ b/docs/pt/docs/advanced/security/http-basic-auth.md
@@ -1,10 +1,10 @@
-# HTTP Basic Auth
+# HTTP Basic Auth { #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*).
+Caso ela não receba, ela retorna um erro HTTP 401 "Unauthorized".
E retorna um cabeçalho `WWW-Authenticate` com o valor `Basic`, e um parâmetro opcional `realm`.
@@ -12,7 +12,7 @@ Isso sinaliza ao navegador para mostrar o prompt integrado para um usuário e se
Então, quando você digitar o usuário e senha, o navegador os envia automaticamente no cabeçalho.
-## HTTP Basic Auth Simples
+## HTTP Basic Auth Simples { #simple-http-basic-auth }
* Importe `HTTPBasic` e `HTTPBasicCredentials`.
* Crie um "esquema `security`" utilizando `HTTPBasic`.
@@ -22,11 +22,11 @@ Então, quando você digitar o usuário e senha, o navegador os envia automatica
{* ../../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:
+Quando você tentar abrir a URL pela primeira vez (ou clicar no botão "Executar" na documentação) o navegador vai pedir pelo seu usuário e senha:
-## Verifique o usuário
+## Verifique o usuário { #check-the-username }
Aqui está um exemplo mais completo.
@@ -52,7 +52,7 @@ if not (credentials.username == "stanleyjobson") or not (credentials.password ==
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
+### Ataques de Temporização { #timing-attacks }
Mas o que é um "timing attack" (ataque de temporização)?
@@ -80,19 +80,19 @@ 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
+#### O tempo para responder ajuda os invasores { #the-time-to-answer-helps-the-attackers }
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"
+#### Um ataque "profissional" { #a-professional-attack }
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()`
+#### Corrija com o `secrets.compare_digest()` { #fix-it-with-secrets-compare-digest }
Mas em nosso código já estamos utilizando o `secrets.compare_digest()`.
@@ -100,8 +100,7 @@ Resumindo, levará o mesmo tempo para comparar `stanleyjobsox` com `stanleyjobso
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
+### Retorne o erro { #return-the-error }
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:
diff --git a/docs/pt/docs/advanced/security/index.md b/docs/pt/docs/advanced/security/index.md
index 6c7becb67..70fb999d0 100644
--- a/docs/pt/docs/advanced/security/index.md
+++ b/docs/pt/docs/advanced/security/index.md
@@ -1,6 +1,6 @@
-# Segurança Avançada
+# Segurança Avançada { #advanced-security }
-## Funcionalidades Adicionais
+## Funcionalidades Adicionais { #additional-features }
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}.
@@ -12,7 +12,7 @@ E é possível que para o seu caso de uso, a solução está em uma delas.
///
-## Leia o Tutorial primeiro
+## Leia o Tutorial primeiro { #read-the-tutorial-first }
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}.
diff --git a/docs/pt/docs/advanced/security/oauth2-scopes.md b/docs/pt/docs/advanced/security/oauth2-scopes.md
index 07b345945..591ac9b4a 100644
--- a/docs/pt/docs/advanced/security/oauth2-scopes.md
+++ b/docs/pt/docs/advanced/security/oauth2-scopes.md
@@ -1,4 +1,4 @@
-# Escopos OAuth2
+# Escopos OAuth2 { #oauth2-scopes }
Você pode utilizar escopos do OAuth2 diretamente com o **FastAPI**, eles são integrados para funcionar perfeitamente.
@@ -10,7 +10,7 @@ Toda vez que você "se autentica com" Facebook, Google, GitHub, Microsoft, X (Tw
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
+/// warning | Atenção
Isso é uma seção mais ou menos avançada. Se você está apenas começando, você pode pular.
@@ -18,7 +18,7 @@ Você não necessariamente precisa de escopos do OAuth2, e você pode lidar com
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.
+No entanto, 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.
@@ -26,7 +26,7 @@ Mas se você sabe que precisa, ou está curioso, continue lendo.
///
-## Escopos OAuth2 e OpenAPI
+## Escopos OAuth2 e OpenAPI { #oauth2-scopes-and-openapi }
A especificação OAuth2 define "escopos" como uma lista de strings separadas por espaços.
@@ -58,15 +58,15 @@ Para o OAuth2, eles são apenas strings.
///
-## Visão global
+## Visão global { #global-view }
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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
Agora vamos revisar essas mudanças passo a passo.
-## Esquema de segurança OAuth2
+## Esquema de segurança OAuth2 { #oauth2-security-scheme }
A primeira mudança é que agora nós estamos declarando o esquema de segurança OAuth2 com dois escopos disponíveis, `me` e `items`.
@@ -82,9 +82,9 @@ Este é o mesmo mecanismo utilizado quando você adiciona permissões enquanto s
-## Token JWT com escopos
+## Token JWT com escopos { #jwt-token-with-scopes }
-Agora, modifique o *caminho de rota* para retornar os escopos solicitados.
+Agora, modifique a *operação de rota* do token 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.
@@ -98,15 +98,15 @@ Porém em sua aplicação, por segurança, você deve garantir que você apenas
///
-{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}
-## Declare escopos em *operações de rota* e dependências
+## Declare escopos em *operações de rota* e dependências { #declare-scopes-in-path-operations-and-dependencies }
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).
+Você pode utilizar `Security` para declarar dependências (assim como `Depends`), porém o `Security` também recebe o parâmetro `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`).
@@ -124,9 +124,9 @@ Nós estamos fazendo isso aqui para demonstrar como o **FastAPI** lida com escop
///
-{* ../../docs_src/security/tutorial005_an_py310.py hl[5,140,171] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
-/// info | Informações Técnicas
+/// info | Detalhes Técnicos
`Security` é na verdade uma subclasse de `Depends`, e ele possui apenas um parâmetro extra que veremos depois.
@@ -136,7 +136,7 @@ Mas quando você importa `Query`, `Path`, `Depends`, `Security` entre outros de
///
-## Utilize `SecurityScopes`
+## Utilize `SecurityScopes` { #use-securityscopes }
Agora atualize a dependência `get_current_user`.
@@ -152,7 +152,7 @@ A classe `SecurityScopes` é semelhante à classe `Request` (`Request` foi utili
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
-## Utilize os `scopes`
+## Utilize os `scopes` { #use-the-scopes }
O parâmetro `security_scopes` será do tipo `SecurityScopes`.
@@ -166,7 +166,7 @@ Nesta exceção, nós incluímos os escopos necessários (se houver algum) como
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
-## Verifique o `username` e o formato dos dados
+## Verifique o `username` e o formato dos dados { #verify-the-username-and-data-shape }
Nós verificamos que nós obtemos um `username`, e extraímos os escopos.
@@ -180,17 +180,17 @@ No lugar de, por exemplo, um `dict`, ou alguma outra coisa, que poderia quebrar
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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}
-## Verifique os `scopes`
+## Verifique os `scopes` { #verify-the-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] *}
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
-## Árvore de dependência e escopos
+## Árvore de dependência e escopos { #dependency-tree-and-scopes }
Vamos rever novamente essa árvore de dependência e os escopos.
@@ -223,7 +223,7 @@ Tudo depende dos `scopes` declarados em cada *operação de rota* e cada depend
///
-## Mais detalhes sobre `SecurityScopes`
+## Mais detalhes sobre `SecurityScopes` { #more-details-about-securityscopes }
Você pode utilizar `SecurityScopes` em qualquer lugar, e em diversos lugares. Ele não precisa estar na dependência "raiz".
@@ -233,9 +233,9 @@ Porque o `SecurityScopes` terá todos os escopos declarados por dependentes, voc
Todos eles serão validados independentemente para cada *operação de rota*.
-## Verifique
+## Verifique { #check-it }
-Se você abrir os documentos da API, você pode antenticar e especificar quais escopos você quer autorizar.
+Se você abrir os documentos da API, você pode autenticar e especificar quais escopos você quer autorizar.
@@ -245,9 +245,9 @@ E se você selecionar o escopo `me`, mas não o escopo `items`, você poderá ac
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
+## Sobre integrações de terceiros { #about-third-party-integrations }
-Neste exemplos nós estamos utilizando o fluxo de senha do OAuth2.
+Neste exemplo 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*".
@@ -269,6 +269,6 @@ 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`
+## `Security` em decoradores de `dependencies` { #security-in-decorator-dependencies }
-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á.
+Da mesma forma que você pode definir uma `list` de `Depends` no parâmetro `dependencies` 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 cdc6400ad..28411269b 100644
--- a/docs/pt/docs/advanced/settings.md
+++ b/docs/pt/docs/advanced/settings.md
@@ -1,148 +1,30 @@
-# Configurações e Variáveis de Ambiente
+# Configurações e Variáveis de Ambiente { #settings-and-environment-variables }
-Em muitos casos a sua aplicação pode precisar de configurações externas, como chaves secretas, credenciais de banco de dados, credenciais para serviços de email, etc.
+Em muitos casos, sua aplicação pode precisar de configurações externas, por exemplo chaves secretas, credenciais de banco de dados, credenciais para serviços de e-mail, etc.
-A maioria dessas configurações é variável (podem mudar), como URLs de bancos de dados. E muitas delas podem conter dados sensíveis, como tokens secretos.
+A maioria dessas configurações é variável (pode mudar), como URLs de banco de dados. E muitas podem ser sensíveis, como segredos.
-Por isso é comum prover essas configurações como variáveis de ambiente que são utilizidas pela aplicação.
-
-## Variáveis de Ambiente
+Por esse motivo, é comum fornecê-las em variáveis de ambiente lidas pela aplicação.
/// 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.
+Para entender variáveis de ambiente, você pode ler [Variáveis de Ambiente](../environment-variables.md){.internal-link target=_blank}.
///
-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:
+## Tipagem e validação { #types-and-validation }
-//// tab | Linux, macOS, Windows Bash
+Essas variáveis de ambiente só conseguem lidar com strings de texto, pois são externas ao Python e precisam ser compatíveis com outros programas e com o resto do sistema (e até com diferentes sistemas operacionais, como Linux, Windows, macOS).
-
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`
+### Detalhes Técnicos: `root_path` { #technical-details-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`.
+Quando você monta uma sub-aplicação como descrito acima, o FastAPI se encarrega de comunicar o path 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.
+Dessa forma, a sub-aplicação saberá usar esse prefixo de path 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.
diff --git a/docs/pt/docs/advanced/templates.md b/docs/pt/docs/advanced/templates.md
index 4d22bfbbf..eb64e72bb 100644
--- a/docs/pt/docs/advanced/templates.md
+++ b/docs/pt/docs/advanced/templates.md
@@ -1,4 +1,4 @@
-# Templates
+# Templates { #templates }
Você pode usar qualquer template engine com o **FastAPI**.
@@ -6,28 +6,30 @@ Uma escolha comum é o Jinja2, o mesmo usado pelo Flask e outras ferramentas.
Existem utilitários para configurá-lo facilmente que você pode usar diretamente em sua aplicação **FastAPI** (fornecidos pelo Starlette).
-## Instalação de dependências
+## Instalar dependências { #install-dependencies }
-Para instalar o `jinja2`, siga o código abaixo:
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativá-lo e instalar `jinja2`:
-## Lidando com desconexões e múltiplos clientes
+## Lidando com desconexões e múltiplos clientes { #handling-disconnections-and-multiple-clients }
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]*}
+{* ../../docs_src/websockets/tutorial003_py39.py hl[79:81] *}
Para testar:
-* Abrar o aplicativo com várias abas do navegador.
+* Abra o aplicativo com várias abas do navegador.
* Escreva mensagens a partir delas.
* Então feche uma das abas.
@@ -172,15 +172,15 @@ Client #1596980209979 left the chat
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.
+Mas tenha em mente que, como tudo é manipulado na memória, em uma única list, 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
+## Mais informações { #more-info }
Para aprender mais sobre as opções, verifique a documentação do Starlette para:
-* A classe `WebSocket`.
-* Manipulação de WebSockets baseada em classes.
+* 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 a36261e5e..c3c21d430 100644
--- a/docs/pt/docs/advanced/wsgi.md
+++ b/docs/pt/docs/advanced/wsgi.md
@@ -1,22 +1,22 @@
-# Adicionando WSGI - Flask, Django, entre outros
+# Adicionando WSGI - Flask, Django, entre outros { #including-wsgi-flask-django-others }
-Como você viu em [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank} e [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank}, você pode **"montar"** aplicações WSGI.
+Como você viu em [Subaplicações - Montagens](sub-applications.md){.internal-link target=_blank} e [Atrás de um Proxy](behind-a-proxy.md){.internal-link target=_blank}, você pode montar aplicações WSGI.
Para isso, você pode utilizar o `WSGIMiddleware` para encapsular a sua aplicação WSGI, como por exemplo Flask, Django, etc.
-## Usando o `WSGIMiddleware`
+## Usando `WSGIMiddleware` { #using-wsgimiddleware }
Você precisa importar o `WSGIMiddleware`.
-Em seguinda, encapsular a aplicação WSGI (e.g. Flask) com o middleware.
+Em seguida, encapsule a aplicação WSGI (e.g. Flask) com o middleware.
-E então **"montar"** em um caminho de rota.
+E então monte isso sob um path.
-{* ../../docs_src/wsgi/tutorial001.py hl[2:3,23] *}
+{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *}
-## Conferindo
+## Confira { #check-it }
-Agora todas as requisições sob o caminho `/v1/` serão manipuladas pela aplicação utilizando Flask.
+Agora, todas as requisições sob o path `/v1/` serão manipuladas pela aplicação Flask.
E o resto será manipulado pelo **FastAPI**.
diff --git a/docs/pt/docs/alternatives.md b/docs/pt/docs/alternatives.md
index 29c9693bb..fd992ec95 100644
--- a/docs/pt/docs/alternatives.md
+++ b/docs/pt/docs/alternatives.md
@@ -1,34 +1,34 @@
-# Alternativas, Inspiração e Comparações
+# Alternativas, Inspiração e Comparações { #alternatives-inspiration-and-comparisons }
-O que inspirou o **FastAPI**, como ele se compara às alternativas e o que FastAPI aprendeu delas.
+O que inspirou o **FastAPI**, como ele se compara às alternativas e o que ele aprendeu com elas.
-## Introdução
+## Introdução { #intro }
-**FastAPI** não poderia existir se não fosse pelos trabalhos anteriores de outras pessoas.
+**FastAPI** não existiria se não fosse pelo trabalho anterior de outras pessoas.
-Houveram tantas ferramentas criadas que ajudaram a inspirar sua criação.
+Houve muitas ferramentas criadas antes que ajudaram a inspirar sua criação.
-Tenho evitado criar um novo framework por anos. Primeiramente tentei resolver todos os recursos cobertos pelo **FastAPI** utilizando muitos frameworks diferentes, plug-ins e ferramentas.
+Tenho evitado criar um novo framework por vários anos. Primeiro tentei resolver todas as funcionalidades cobertas pelo **FastAPI** utilizando muitos frameworks, plug-ins e ferramentas diferentes.
-Mas em algum ponto, não houve outra opção senão criar algo que fornecesse todos esses recursos, pegando as melhores idéias de ferramentas anteriores, e combinando eles da melhor forma possível, utilizando recursos da linguagem que não estavam disponíveis antes (_Type Hints_ no Python 3.6+).
+Mas em algum momento, não havia outra opção senão criar algo que fornecesse todos esses recursos, pegando as melhores ideias de ferramentas anteriores e combinando-as da melhor maneira possível, usando funcionalidades da linguagem que nem sequer estavam disponíveis antes (anotações de tipo no Python 3.6+).
-## Ferramentas anteriores
+## Ferramentas anteriores { #previous-tools }
-### Django
+### Django { #django }
-É o framework mais popular e largamente confiável. É utilizado para construir sistemas como o _Instagram_.
+É o framework Python mais popular e amplamente confiável. É utilizado para construir sistemas como o Instagram.
-É bem acoplado com banco de dados relacional (como MySQL ou PostgreSQL), então, tendo um banco de dados NoSQL (como Couchbase, MongoDB, Cassandra etc) como a principal ferramenta de armazenamento não é muito fácil.
+É relativamente bem acoplado com bancos de dados relacionais (como MySQL ou PostgreSQL), então, ter um banco de dados NoSQL (como Couchbase, MongoDB, Cassandra, etc.) como mecanismo principal de armazenamento não é muito fácil.
-Foi criado para gerar HTML no _backend_, não para criar APIs utilizando um _frontend_ moderno (como React, Vue.js e Angular) ou por outros sistemas (como dispositivos IoT) comunicando com ele.
+Foi criado para gerar o HTML no backend, não para criar APIs usadas por um frontend moderno (como React, Vue.js e Angular) ou por outros sistemas (como dispositivos IoT) comunicando com ele.
-### Django REST Framework
+### Django REST Framework { #django-rest-framework }
-Django REST framework foi criado para ser uma caixa de ferramentas flexível para construção de APIs web utilizando Django por baixo, para melhorar suas capacidades de API.
+Django REST framework foi criado para ser uma caixa de ferramentas flexível para construção de APIs Web utilizando Django por baixo, para melhorar suas capacidades de API.
-Ele é utilizado por muitas companhias incluindo Mozilla, Red Hat e Eventbrite.
+Ele é utilizado por muitas empresas 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**.
+Foi um dos primeiros exemplos de **documentação automática de API**, e essa foi especificamente uma das primeiras ideias que inspirou "a busca por" **FastAPI**.
/// note | Nota
@@ -38,57 +38,57 @@ Django REST Framework foi criado por Tom Christie. O mesmo criador de Starlette
/// check | **FastAPI** inspirado para
-Ter uma documentação automática da API em interface web.
+Ter uma interface web de documentação automática da API.
///
-### Flask
+### Flask { #flask }
-Flask é um "microframework", não inclui integração com banco de dados nem muitas das coisas que vêm por padrão no Django.
+Flask é um "microframework", não inclui integrações com banco de dados nem muitas das coisas que vêm por padrão no Django.
-Sua simplicidade e flexibilidade permitem fazer coisas como utilizar bancos de dados NoSQL como principal sistema de armazenamento de dados.
+Essa simplicidade e flexibilidade permitem fazer coisas como utilizar bancos de dados NoSQL como o principal sistema de armazenamento de dados.
-Por ser tão simples, é relativamente intuitivo de aprender, embora a documentação esteja de forma mais técnica em alguns pontos.
+Por ser muito simples, é relativamente intuitivo de aprender, embora a documentação se torne um pouco técnica em alguns pontos.
-Ele é comumente utilizado por outras aplicações que não necessariamente precisam de banco de dados, gerenciamento de usuários, ou algum dos muitos recursos que já vem instalados no Django. Embora muitos desses recursos possam ser adicionados com plug-ins.
+Ele também é comumente utilizado por outras aplicações que não necessariamente precisam de banco de dados, gerenciamento de usuários, ou qualquer uma das muitas funcionalidades que já vêm prontas no Django. Embora muitas dessas funcionalidades possam ser adicionadas com plug-ins.
-Esse desacoplamento de partes, e sendo um "microframework" que pode ser extendido para cobrir exatamente o que é necessário era um recurso chave que eu queria manter.
+Esse desacoplamento de partes, e ser um "microframework" que pode ser estendido para cobrir exatamente o que é necessário era uma funcionalidade chave que eu queria manter.
-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.
+Dada a simplicidade do Flask, ele parecia uma boa opção para construção de APIs. A próxima coisa a encontrar 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.
+Ser um microframework. Tornar fácil misturar e combinar as ferramentas e partes necessárias.
-Ser simples e com sistema de roteamento fácil de usar.
+Ter um sistema de roteamento simples e fácil de usar.
///
-### Requests
+### Requests { #requests }
-**FastAPI** não é uma alternativa para **Requests**. O escopo deles é muito diferente.
+**FastAPI** na verdade não é uma alternativa ao **Requests**. O escopo deles é muito diferente.
-Na verdade é comum utilizar Requests *dentro* de uma aplicação FastAPI.
+Na verdade, é comum utilizar Requests dentro de uma aplicação FastAPI.
-Ainda assim, FastAPI pegou alguma inspiração do Requests.
+Ainda assim, o FastAPI tirou bastante inspiração do Requests.
-**Requests** é uma biblioteca para interagir com APIs (como um cliente), enquanto **FastAPI** é uma biblioteca para *construir* APIs (como um servidor).
+**Requests** é uma biblioteca para interagir com APIs (como um cliente), enquanto **FastAPI** é uma biblioteca para construir APIs (como um servidor).
-Eles estão, mais ou menos, em pontas opostas, um complementando o outro.
+Eles estão, mais ou menos, em pontas opostas, complementando-se.
-Requests tem um projeto muito simples e intuitivo, fácil de usar, com padrões sensíveis. Mas ao mesmo tempo, é muito poderoso e customizável.
+Requests tem um design muito simples e intuitivo, é muito fácil de usar, com padrões sensatos. Mas ao mesmo tempo, é muito poderoso e personalizável.
É por isso que, como dito no site oficial:
> Requests é um dos pacotes Python mais baixados de todos os tempos
-O jeito de usar é muito simples. Por exemplo, para fazer uma requisição `GET`, você deveria escrever:
+O jeito de usar é muito simples. Por exemplo, para fazer uma requisição `GET`, você escreveria:
```Python
response = requests.get("http://example.com/some/url")
```
-A contra-parte da aplicação FastAPI, *rota de operação*, poderia parecer como:
+A contra-parte na aplicação FastAPI, a operação de rota, poderia ficar assim:
```Python hl_lines="1"
@app.get("/some/url")
@@ -102,50 +102,50 @@ Veja as similaridades em `requests.get(...)` e `@app.get(...)`.
* 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.
+* Ter padrões sensatos, mas customizações poderosas.
///
-### Swagger / OpenAPI
+### Swagger / OpenAPI { #swagger-openapi }
-O principal recurso que eu queria do Django REST Framework era a documentação automática da API.
+A principal funcionalidade que eu queria do Django REST Framework era a documentação automática da API.
-Então eu descobri que existia um padrão para documentar APIs, utilizando JSON (ou YAML, uma extensão do JSON) chamado Swagger.
+Então descobri que existia um padrão para documentar APIs, utilizando JSON (ou YAML, uma extensão do JSON) chamado Swagger.
-E tinha uma interface web para APIs Swagger já criada. Então, sendo capaz de gerar documentação Swagger para uma API poderia permitir utilizar essa interface web automaticamente.
+E havia uma interface web para APIs Swagger já criada. Então, ser capaz de gerar documentação Swagger para uma API permitiria usar essa interface web automaticamente.
-Em algum ponto, Swagger foi dado para a Fundação Linux, e foi renomeado OpenAPI.
+Em algum ponto, Swagger foi doado para a Fundação Linux, para ser renomeado OpenAPI.
-Isso acontece porquê quando alguém fala sobre a versão 2.0 é comum dizer "Swagger", e para a versão 3+, "OpenAPI".
+É por isso que ao falar 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.
+Adotar e usar um padrão aberto para especificações de API, em vez de um schema personalizado.
-E integrar ferramentas de interface para usuários baseado nos padrões:
+E integrar ferramentas de interface para usuários baseadas nos padrões:
* 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**).
+Essas duas foram escolhidas por serem bem populares e estáveis, mas fazendo uma pesquisa rápida, você pode encontrar dúzias de interfaces alternativas adicionais para OpenAPI (que você pode utilizar com **FastAPI**).
///
-### Flask REST frameworks
+### Flask REST frameworks { #flask-rest-frameworks }
-Existem vários Flask REST frameworks, mas depois de investir tempo e trabalho investigando eles, eu descobri que muitos estão descontinuados ou abandonados, com alguns tendo questões que fizeram eles inadequados.
+Existem vários Flask REST frameworks, mas depois de investir tempo e trabalho investigando-os, descobri que muitos estão descontinuados ou abandonados, com diversas questões em aberto que os tornaram inadequados.
-### Marshmallow
+### Marshmallow { #marshmallow }
-Um dos principais recursos necessários em sistemas API é "serialização" de dados, que é pegar dados do código (Python) e converter eles em alguma coisa que possa ser enviado através da rede. Por exemplo, converter um objeto contendo dados de um banco de dados em um objeto JSON. Converter objetos `datetime` em strings etc.
+Uma das principais funcionalidades necessárias em sistemas de API é a "serialização" de dados, que é pegar dados do código (Python) e convertê-los em algo que possa ser enviado pela rede. Por exemplo, converter um objeto contendo dados de um banco de dados em um objeto JSON. Converter objetos `datetime` em strings, etc.
-Outro grande recurso necessário nas APIs é validação de dados, certificando que os dados são válidos, dados certos parâmetros. Por exemplo, algum campo é `int`, e não alguma string aleatória. Isso é especialmente útil para dados que estão chegando.
+Outra grande funcionalidade necessária pelas APIs é a validação de dados, garantindo que os dados são válidos, dados certos parâmetros. Por exemplo, que algum campo seja `int`, e não alguma string aleatória. Isso é especialmente útil para dados de entrada.
Sem um sistema de validação de dados, você teria que realizar todas as verificações manualmente, no código.
-Esses recursos são o que Marshmallow foi construído para fornecer. Ele é uma ótima biblioteca, e eu já utilizei muito antes.
+Essas funcionalidades são o que o Marshmallow foi construído para fornecer. É uma ótima biblioteca, e eu a utilizei bastante antes.
-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.
+Mas ele foi criado antes de existirem as anotações de tipo do Python. Então, para definir cada schema você precisa utilizar utilitários e classes específicos fornecidos pelo Marshmallow.
/// check | **FastAPI** inspirado para
@@ -153,17 +153,17 @@ Usar código para definir "schemas" que forneçam, automaticamente, tipos de dad
///
-### Webargs
+### Webargs { #webargs }
-Outro grande recurso necessário pelas APIs é a análise de dados vindos de requisições.
+Outra grande funcionalidade requerida pelas APIs é o parsing de dados vindos de requisições de entrada.
-Webargs é uma ferramente feita para fornecer o que está no topo de vários frameworks, inclusive Flask.
+Webargs é uma ferramenta feita para fornecer isso no topo de vários frameworks, inclusive Flask.
-Ele utiliza Marshmallow por baixo para validação de dados. E ele foi criado pelos mesmos desenvolvedores.
+Ele utiliza Marshmallow por baixo para a validação de dados. E foi criado pelos mesmos desenvolvedores.
-Ele é uma grande ferramenta e eu também a utilizei muito, antes de ter o **FastAPI**.
+É uma grande ferramenta e eu também a utilizei bastante, antes de ter o **FastAPI**.
-/// info
+/// info | Informação
Webargs foi criado pelos mesmos desenvolvedores do Marshmallow.
@@ -171,29 +171,29 @@ Webargs foi criado pelos mesmos desenvolvedores do Marshmallow.
/// check | **FastAPI** inspirado para
-Ter validação automática de dados vindos de requisições.
+Ter validação automática dos dados de requisições de entrada.
///
-### APISpec
+### APISpec { #apispec }
-Marshmallow e Webargs fornecem validação, análise e serialização como plug-ins.
+Marshmallow e Webargs fornecem validação, parsing e serialização como plug-ins.
-Mas a documentação ainda está faltando. Então APISpec foi criado.
+Mas a documentação ainda estava faltando. Então APISpec foi criado.
-APISpec tem plug-ins para muitos frameworks (e tem um plug-in para Starlette também).
+É um plug-in para muitos frameworks (e há um plug-in para Starlette também).
-O jeito como ele funciona é que você escreve a definição do _schema_ usando formato YAML dentro da _docstring_ de cada função controlando uma rota.
+O jeito como ele funciona é que você escreve a definição do schema usando formato YAML dentro da docstring de cada função que lida com uma rota.
-E ele gera _schemas_ OpenAPI.
+E ele gera schemas OpenAPI.
-É assim como funciona no Flask, Starlette, Responder etc.
+É assim como funciona no Flask, Starlette, Responder, etc.
-Mas então, nós temos novamente o problema de ter uma micro-sintaxe, dentro de uma string Python (um grande YAML).
+Mas então, temos novamente o problema de ter uma micro-sintaxe, dentro de uma string Python (um grande YAML).
-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.
+O editor não pode ajudar muito com isso. E se modificarmos parâmetros ou schemas do Marshmallow e esquecermos de também modificar aquela docstring em YAML, o schema gerado ficaria obsoleto.
-/// info
+/// info | Informação
APISpec foi criado pelos mesmos desenvolvedores do Marshmallow.
@@ -201,31 +201,31 @@ APISpec foi criado pelos mesmos desenvolvedores do Marshmallow.
/// check | **FastAPI** inspirado para
-Dar suporte a padrões abertos para APIs, OpenAPI.
+Dar suporte ao padrão aberto para APIs, OpenAPI.
///
-### Flask-apispec
+### Flask-apispec { #flask-apispec }
-É um plug-in Flask, que amarra junto Webargs, Marshmallow e APISpec.
+É um plug-in Flask, que amarra juntos Webargs, Marshmallow e APISpec.
-Ele utiliza a informação do Webargs e Marshmallow para gerar automaticamente _schemas_ OpenAPI, usando APISpec.
+Ele utiliza a informação do Webargs e Marshmallow para gerar automaticamente schemas OpenAPI, usando APISpec.
-É uma grande ferramenta, mas muito subestimada. Ela deveria ser um pouco mais popular do que muitos outros plug-ins Flask. É de ser esperado que sua documentação seja bem concisa e abstrata.
+É uma grande ferramenta, muito subestimada. Deveria ser bem mais popular do que muitos plug-ins Flask por aí. Pode ser devido à sua documentação ser concisa e abstrata demais.
-Isso resolveu o problema de ter que escrever YAML (outra sintaxe) dentro das _docstrings_ Python.
+Isso resolveu ter que escrever YAML (outra sintaxe) dentro das docstrings do Python.
-Essa combinação de Flask, Flask-apispec com Marshmallow e Webargs foi meu _backend stack_ favorito até construir o **FastAPI**.
+Essa combinação de Flask, Flask-apispec com Marshmallow e Webargs foi a minha stack de backend favorita 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:
+Usá-la levou à criação de vários geradores Flask full-stack. Estas são as principais stacks que eu (e várias equipes externas) tenho utilizado até agora:
* https://github.com/tiangolo/full-stack
* https://github.com/tiangolo/full-stack-flask-couchbase
* https://github.com/tiangolo/full-stack-flask-couchdb
-E esses mesmos geradores _full-stack_ foram a base dos [Geradores de Projetos **FastAPI**](project-generation.md){.internal-link target=_blank}.
+E esses mesmos geradores full-stack foram a base dos [Geradores de Projetos **FastAPI**](project-generation.md){.internal-link target=_blank}.
-/// info
+/// info | Informação
Flask-apispec foi criado pelos mesmos desenvolvedores do Marshmallow.
@@ -233,151 +233,149 @@ 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.
+Gerar o schema OpenAPI automaticamente, a partir do mesmo código que define serialização e validação.
///
-### NestJS (and Angular)
+### NestJS (e Angular) { #nestjs-and-angular }
-NestJS, que não é nem Python, é um framework NodeJS JavaScript (TypeScript) inspirado pelo Angular.
+Isso nem é Python, NestJS é um framework NodeJS em JavaScript (TypeScript) inspirado pelo Angular.
-Ele alcança de uma forma similar ao que pode ser feito com o Flask-apispec.
+Ele alcança algo um tanto similar ao que pode ser feito com Flask-apispec.
-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.
+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, adiciona 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.
+Como os parâmetros são descritos com tipos do TypeScript (similares às anotações de tipo do Python), o suporte do editor é muito bom.
-Mas como os dados TypeScript não são preservados após a compilação para o JavaScript, ele não pode depender dos tipos para definir a validação, serialização e documentação ao mesmo tempo. Devido a isso e a algumas decisões de projeto, para pegar a validação, serialização e geração automática do _schema_, é necessário adicionar decoradores em muitos lugares. Então, ele se torna muito verboso.
+Mas como os dados do TypeScript não são preservados após a compilação para JavaScript, ele não pode depender dos tipos para definir validação, serialização e documentação ao mesmo tempo. Devido a isso e a algumas decisões de projeto, para obter validação, serialização e geração automática de schema, é necessário adicionar decorators em muitos lugares. Então, ele se torna bastante verboso.
-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.
+Ele não consegue lidar muito bem com modelos aninhados. Então, se o corpo JSON na requisição for um objeto JSON que contém campos internos que por sua vez são objetos JSON aninhados, ele não consegue ser documentado e validado apropriadamente.
/// check | **FastAPI** inspirado para
-Usar tipos Python para ter um ótimo suporte do editor.
+Usar tipos do 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.
+Ter um sistema de injeção de dependência poderoso. Encontrar um jeito de minimizar repetição de código.
///
-### Sanic
+### Sanic { #sanic }
-Ele foi um dos primeiros frameworks Python extremamente rápido baseado em `asyncio`. Ele foi feito para ser muito similar ao Flask.
+Ele foi um dos primeiros frameworks Python extremamente rápidos baseados em `asyncio`. Ele foi feito para ser muito similar ao Flask.
-/// note | Detalhes técnicos
+/// 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.
+Ele utilizava `uvloop` em vez do loop `asyncio` padrão do Python. É isso que o deixava tão rápido.
-Ele claramente inspirou Uvicorn e Starlette, que são atualmente mais rápidos que o Sanic em testes de performance abertos.
+Ele claramente inspirou Uvicorn e Starlette, que atualmente são mais rápidos que o Sanic em benchmarks abertos.
///
/// check | **FastAPI** inspirado para
-Achar um jeito de ter uma performance insana.
+Encontrar 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).
+É por isso que o **FastAPI** é baseado em Starlette, pois ela é o framework mais rápido disponível (testado por benchmarks de terceiros).
///
-### Falcon
-
-Falcon é outro framework Python de alta performance, e é projetado para ser minimalista, e funciona como fundação de outros frameworks como Hug.
+### Falcon { #falcon }
-Ele usa o padrão anterior para frameworks web Python (WSGI) que é síncrono, então ele não pode controlar _WebSockets_ e outros casos de uso. No entanto, ele também tem uma boa performance.
+Falcon é outro framework Python de alta performance, projetado para ser minimalista, e servir como base para outros frameworks como Hug.
-Ele é projetado para ter funções que recebem dois parâmetros, uma "requisição" e uma "resposta". Então você "lê" as partes da requisição, e "escreve" partes para a resposta. Devido ao seu design, não é possível declarar parâmetros de requisição e corpos com _type hints_ Python padrão como parâmetros de funções.
+Ele é projetado para ter funções que recebem dois parâmetros, uma "request" e uma "response". Então você "lê" partes da requisição, e "escreve" partes para a resposta. Por causa desse design, não é possível declarar parâmetros de requisição e corpos com as anotações de tipo padrão do Python como parâmetros de função.
-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.
+Então, validação de dados, serialização e documentação têm que ser feitos no código, não automaticamente. Ou eles têm que ser implementados como um framework acima do Falcon, como o Hug. Essa mesma distinção acontece em outros frameworks inspirados pelo design do Falcon, de ter um objeto de request e um objeto de response como parâmetros.
/// check | **FastAPI** inspirado para
-Achar jeitos de conseguir melhor performance.
+Encontrar maneiras de obter uma ótima performance.
-Juntamente com Hug (como Hug é baseado no Falcon) inspirou **FastAPI** para declarar um parâmetro de `resposta` nas funções.
+Juntamente com Hug (como Hug é baseado no Falcon) inspirou **FastAPI** a declarar um parâmetro de `response` nas funções.
Embora no FastAPI seja opcional, é utilizado principalmente para configurar cabeçalhos, cookies e códigos de status alternativos.
///
-### Molten
+### Molten { #molten }
-Eu descobri Molten nos primeiros estágios da construção do **FastAPI**. E ele tem umas idéias bem similares:
+Eu descobri Molten nos primeiros estágios da construção do **FastAPI**. E ele tem ideias bastante similares:
-* Baseado em _type hints_ Python.
-* Validação e documentação desses tipos.
-* Sistema de injeção de dependência.
+* Baseado nas anotações de tipo do Python.
+* Validação e documentação a partir desses tipos.
+* Sistema de Injeção de Dependência.
-Ele não utiliza validação de dados, seriallização e documentação de bibliotecas de terceiros como o Pydantic, ele tem seu prórpio. Então, essas definições de tipo de dados não podem ser reutilizados tão facilmente.
+Ele não utiliza uma biblioteca de terceiros para validação de dados, serialização e documentação como o Pydantic, ele tem a sua própria. Então, essas definições de tipos de dados não seriam reutilizáveis tão facilmente.
-Ele exige um pouco mais de verbosidade nas configurações. E como é baseado no WSGI (ao invés de ASGI), ele não é projetado para ter a vantagem da alta performance fornecida por ferramentas como Uvicorn, Starlette e Sanic.
+Ele exige configurações um pouco mais verbosas. E como é baseado em WSGI (em vez de ASGI), ele não é projetado para tirar vantagem da alta performance fornecida por ferramentas como Uvicorn, Starlette e Sanic.
-O sistema de injeção de dependência exige pré-registro das dependências e as dependências são resolvidas baseadas nos tipos declarados. Então, não é possível declarar mais do que um "componente" que fornece um certo tipo.
+O sistema de injeção de dependência exige pré-registro das dependências e elas são resolvidas com base nos tipos declarados. Então, não é possível declarar mais de um "componente" que forneça um certo tipo.
-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.
+As rotas são declaradas em um único lugar, usando funções declaradas em outros lugares (em vez de usar decorators que possam ser colocados diretamente acima da função que lida com o endpoint). Isso é mais próximo de como o Django faz do que de como o Flask (e o Starlette) fazem. Separa no código coisas que são relativamente bem acopladas.
/// 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.
+Definir validações extras para tipos de dados usando o valor "padrão" de atributos dos modelos. Isso melhora o suporte do editor, e não estava disponível no Pydantic antes.
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 { #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.
+Hug foi um dos primeiros frameworks a implementar a declaração de tipos de parâmetros de API usando anotações de tipo do Python. Isso foi uma ótima ideia que inspirou outras ferramentas a fazer o mesmo.
-Ele usou tipos customizados em suas declarações ao invés dos tipos padrão Python, mas mesmo assim foi um grande passo.
+Ele usou tipos personalizados em suas declarações em vez dos tipos padrão do Python, mas mesmo assim foi um grande passo adiante.
-Ele também foi um dos primeiros frameworks a gerar um _schema_ customizado declarando a API inteira em JSON.
+Ele também foi um dos primeiros frameworks a gerar um schema personalizado declarando a API inteira em JSON.
-Ele não era baseado em um padrão como OpenAPI e JSON Schema. Então não poderia ter interação direta com outras ferramentas, como Swagger UI. Mas novamente, era uma idéia muito inovadora.
+Ele não era baseado em um padrão como OpenAPI e JSON Schema. Então não seria simples integrá-lo com outras ferramentas, como Swagger UI. Mas novamente, era uma ideia muito inovadora.
-Hug tinha um incomum, interessante recurso: usando o mesmo framework, é possível criar tanto APIs como CLIs.
+Ele tem um recurso interessante e incomum: usando o mesmo framework, é possível criar APIs e também CLIs.
-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.
+Como é baseado no padrão anterior para frameworks web Python síncronos (WSGI), ele não consegue lidar com Websockets e outras coisas, embora ainda tenha alta performance também.
-/// info
+/// info | Informação
-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 foi criado por Timothy Crosley, o mesmo criador do `isort`, uma ótima ferramenta para ordenar automaticamente imports em arquivos Python.
///
-/// check | Idéias inspiradas para o **FastAPI**
+/// check | Ideias que inspiraram o **FastAPI**
-Hug inspirou partes do APIStar, e foi uma das ferramentas que eu achei mais promissora, ao lado do APIStar.
+Hug inspirou partes do APIStar, e foi uma das ferramentas que achei mais promissoras, 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 ajudou a inspirar o **FastAPI** a usar anotações de tipo 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.
+Hug inspirou **FastAPI** a declarar um parâmetro de `response` em funções para definir cabeçalhos e cookies.
///
-### APIStar (<= 0.5)
+### APIStar (<= 0.5) { #apistar-0-5 }
-Antes de decidir construir **FastAPI** eu encontrei o servidor **APIStar**. Tinha quase tudo que eu estava procurando e tinha um grande projeto.
+Pouco antes de decidir construir o **FastAPI** eu encontrei o servidor **APIStar**. Ele tinha quase tudo o que eu estava procurando e tinha um ótimo design.
-Ele foi uma das primeiras implementações de um framework usando Python _type hints_ para declarar parâmetros e requisições que eu nunca vi (antes no NestJS e Molten). Eu encontrei ele mais ou menos na mesma época que o Hug. Mas o APIStar utilizava o padrão OpenAPI.
+Foi uma das primeiras implementações de um framework usando anotações de tipo do Python para declarar parâmetros e requisições que eu já vi (antes do NestJS e Molten). Eu o encontrei mais ou menos na mesma época que o Hug. Mas o APIStar utilizava o padrão OpenAPI.
-Ele tinha validação de dados automática, serialização de dados e geração de _schema_ OpenAPI baseado nos mesmos _type hints_ em vários locais.
+Ele tinha validação de dados automática, serialização de dados e geração de schema OpenAPI baseadas nas mesmas anotações de tipo em vários locais.
-Definições de _schema_ de corpo não utilizavam os mesmos Python _type hints_ como Pydantic, ele era um pouco mais similar ao Marshmallow, então, o suporte ao editor não seria tão bom, ainda assim, APIStar era a melhor opção disponível.
+As definições de schema de corpo não utilizavam as mesmas anotações de tipo do Python como o Pydantic, eram um pouco mais similares ao Marshmallow, então o suporte do editor não seria tão bom, ainda assim, APIStar era a melhor opção disponível.
-Ele obteve as melhores performances em testes na época (somente batido por Starlette).
+Ele obteve os melhores benchmarks de performance na época (somente ultrapassado por Starlette).
A princípio, ele não tinha uma interface web com documentação automática da API, mas eu sabia que poderia adicionar o Swagger UI a ele.
-Ele tinha um sistema de injeção de dependência. Ele exigia pré-registro dos componentes, como outras ferramentas já discutidas acima. Mas ainda era um grande recurso.
+Ele tinha um sistema de injeção de dependência. Exigia pré-registro dos componentes, como outras ferramentas já discutidas acima. Mas ainda assim era um grande recurso.
-Eu nunca fui capaz de usar ele num projeto inteiro, por não ter integração de segurança, então, eu não pude substituir todos os recursos que eu tinha com os geradores _full-stack_ baseados no Flask-apispec. Eu tive em minha gaveta de projetos a idéia de criar um _pull request_ adicionando essa funcionalidade.
+Eu nunca fui capaz de usá-lo em um projeto completo, pois ele não tinha integração de segurança, então, eu não pude substituir todos os recursos que eu tinha com os geradores full-stack baseados no Flask-apispec. Eu tinha no meu backlog de projetos criar um pull request adicionando essa funcionalidade.
Mas então, o foco do projeto mudou.
-Ele não era mais um framework web API, como o criador precisava focar no Starlette.
+Ele não era mais um framework web de API, pois o criador precisava focar no Starlette.
Agora APIStar é um conjunto de ferramentas para validar especificações OpenAPI, não um framework web.
-/// info
+/// info | Informação
APIStar foi criado por Tom Christie. O mesmo cara que criou:
@@ -391,98 +389,97 @@ APIStar foi criado por Tom Christie. O mesmo cara que criou:
Existir.
-A idéia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos Python, que ao mesmo tempo fornecesse grande suporte ao editor, era algo que eu considerava uma brilhante idéia.
+A ideia de declarar múltiplas coisas (validação de dados, serialização e documentação) com os mesmos tipos do Python, que ao mesmo tempo fornecessem grande suporte ao editor, era algo que eu considerava uma ideia brilhante.
-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.
+E após procurar por muito 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**.
+Então APIStar deixou de existir como servidor e o Starlette foi criado, sendo uma nova e melhor fundação para tal sistema. Essa foi a inspiração final para construir o **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.
+Eu considero o **FastAPI** um "sucessor espiritual" do APIStar, enquanto aprimora e amplia as funcionalidades, o sistema de tipagem e outras partes, baseado nos aprendizados de todas essas ferramentas anteriores.
///
-## Usados por **FastAPI**
+## Usados por **FastAPI** { #used-by-fastapi }
-### Pydantic
+### Pydantic { #pydantic }
-Pydantic é uma biblioteca para definir validação de dados, serialização e documentação (usando JSON Schema) baseado nos Python _type hints_.
+Pydantic é uma biblioteca para definir validação de dados, serialização e documentação (usando JSON Schema) com base nas anotações de tipo do Python.
-Isso faz dele extremamente intuitivo.
+Isso o torna 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.
+Ele é comparável ao Marshmallow. Embora seja mais rápido que o Marshmallow em benchmarks. E como é baseado nas mesmas anotações de tipo do Python, o suporte do 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).
+Controlar toda a validação de dados, serialização de dados e documentação automática de modelos (baseada 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.
+**FastAPI** então pega esses dados do JSON Schema e os coloca no OpenAPI, além de todas as outras coisas que faz.
///
-### Starlette
+### Starlette { #starlette }
-Starlette é um framework/caixa de ferramentas ASGI peso leve, o que é ideal para construir serviços assíncronos de alta performance.
+Starlette é um framework/caixa de ferramentas ASGI leve, o que é ideal para construir serviços asyncio de alta performance.
-Ele é muito simples e intuitivo. É projetado para ser extensível facilmente, e ter componentes modulares.
+Ele é muito simples e intuitivo. É projetado para ser facilmente extensível, e ter componentes modulares.
Ele tem:
* Performance seriamente impressionante.
* Suporte a WebSocket.
-* Suporte a GraphQL.
-* Tarefas de processamento interno por trás dos panos.
+* Tarefas em segundo plano dentro do processo.
* Eventos de inicialização e encerramento.
* Cliente de testes construído com HTTPX.
-* Respostas CORS, GZip, Arquivos Estáticos, Streaming.
+* CORS, GZip, Arquivos Estáticos, respostas Streaming.
* Suporte para Sessão e Cookie.
* 100% coberto por testes.
* Código base 100% anotado com tipagem.
-* Dependências complexas Zero.
+* Poucas dependências obrigatórias.
-Starlette é atualmente o mais rápido framework Python testado. Somente ultrapassado pelo Uvicorn, que não é um framework, mas um servidor.
+Starlette é atualmente o framework Python mais rápido testado. Somente ultrapassado pelo Uvicorn, que não é um framework, mas um servidor.
Starlette fornece toda a funcionalidade básica de um microframework web.
-Mas ele não fornece validação de dados automática, serialização e documentação.
+Mas ele não fornece validação de dados automática, serialização ou documentação.
-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.
+Essa é uma das principais coisas que o **FastAPI** adiciona por cima, tudo baseado nas anotações de tipo do Python (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.
+ASGI é um novo "padrão" sendo desenvolvido por membros do time central do Django. Ele ainda não é um "padrão Python" (uma PEP), embora eles estejam no processo de fazer isso.
-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`.
+No entanto, ele já está sendo utilizado como "padrão" por diversas ferramentas. Isso melhora enormemente a interoperabilidade, pois 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`.
///
/// check | **FastAPI** usa isso para
-Controlar todas as partes web centrais. Adiciona recursos no topo.
+Controlar todas as partes web centrais. Adiciona funcionalidades por cima.
-A classe `FastAPI` em si herda `Starlette`.
+A classe `FastAPI` em si herda diretamente da classe `Starlette`.
-Então, qualquer coisa que você faz com Starlette, você pode fazer diretamente com **FastAPI**, pois ele é basicamente um Starlette com esteróides.
+Então, qualquer coisa que você pode fazer com Starlette, você pode fazer diretamente com o **FastAPI**, pois ele é basicamente um Starlette com esteróides.
///
-### Uvicorn
+### Uvicorn { #uvicorn }
-Uvicorn é um servidor ASGI peso leve, construído com uvloop e httptools.
+Uvicorn é um servidor ASGI extremamente rápido, construído com uvloop e httptools.
-Ele não é um framework web, mas sim um servidor. Por exemplo, ele não fornece ferramentas para roteamento por rotas. Isso é algo que um framework como Starlette (ou **FastAPI**) poderia fornecer por cima.
+Ele não é um framework web, mas sim um servidor. Por exemplo, ele não fornece ferramentas para roteamento por paths. Isso é algo que um framework como Starlette (ou **FastAPI**) forneceria por cima.
Ele é o servidor recomendado para Starlette e **FastAPI**.
-/// check | **FastAPI** recomenda isso para
+/// check | **FastAPI** o recomenda como
O principal servidor web para rodar aplicações **FastAPI**.
-Você pode combinar ele com o Gunicorn, para ter um servidor multi-processos assíncrono.
+Você também pode usar a opção de linha de comando `--workers` para ter um servidor assíncrono multi-processos.
Verifique mais detalhes na seção [Deployment](deployment/index.md){.internal-link target=_blank}.
///
-## Performance e velocidade
+## Benchmarks e velocidade { #benchmarks-and-speed }
Para entender, comparar e ver a diferença entre Uvicorn, Starlette e FastAPI, verifique a seção sobre [Benchmarks](benchmarks.md){.internal-link target=_blank}.
diff --git a/docs/pt/docs/async.md b/docs/pt/docs/async.md
index c70924ea5..f01ff2315 100644
--- a/docs/pt/docs/async.md
+++ b/docs/pt/docs/async.md
@@ -1,10 +1,10 @@
-# Concorrência e async / await
+# Concorrência e async / await { #concurrency-and-async-await }
Detalhes sobre a sintaxe `async def` para *funções de operação de rota* e alguns conceitos de código assíncrono, concorrência e paralelismo.
-## Com pressa?
+## Com pressa? { #in-a-hurry }
-TL;DR:
+TL;DR:
Se você estiver utilizando bibliotecas de terceiros que dizem para você chamar as funções com `await`, como:
@@ -12,7 +12,7 @@ Se você estiver utilizando bibliotecas de terceiros que dizem para você chamar
results = await some_library()
```
-Então, declare sua *função de operação de rota* com `async def` como:
+Então, declare suas *funções de operação de rota* com `async def` como:
```Python hl_lines="2"
@app.get('/')
@@ -21,7 +21,7 @@ async def read_results():
return results
```
-/// note
+/// note | Nota
Você só pode usar `await` dentro de funções criadas com `async def`.
@@ -29,7 +29,7 @@ Você só pode usar `await` dentro de funções criadas com `async def`.
---
-Se você está usando biblioteca de terceiros que se comunica com alguma coisa (um banco de dados, uma API, sistema de arquivos etc) e não tem suporte para utilizar `await` (esse é atualmente o caso para a maioria das bibliotecas de banco de dados), então declare suas *funções de operação de rota* normalmente, com apenas `def`, como:
+Se você está usando uma biblioteca de terceiros que se comunica com alguma coisa (um banco de dados, uma API, o sistema de arquivos etc.) e não tem suporte para utilizar `await` (esse é atualmente o caso para a maioria das bibliotecas de banco de dados), então declare suas *funções de operação de rota* normalmente, com apenas `def`, como:
```Python hl_lines="2"
@app.get('/')
@@ -40,7 +40,7 @@ def results():
---
-Se sua aplicação (de alguma forma) não tem que se comunicar com nada mais e esperar que o respondam, use `async def`.
+Se sua aplicação (de alguma forma) não tem que se comunicar com nada mais e esperar que o respondam, use `async def`, mesmo que você não precise usar `await` dentro dela.
---
@@ -54,17 +54,17 @@ De qualquer forma, em ambos os casos acima, FastAPI irá trabalhar assincronamen
Mas, seguindo os passos acima, ele será capaz de fazer algumas otimizações de performance.
-## Detalhes Técnicos
+## Detalhes Técnicos { #technical-details }
-Versões modernas de Python tem suporte para **"código assíncrono"** usando algo chamado **"corrotinas"**, com sintaxe **`async` e `await`**.
+Versões modernas de Python têm suporte para **"código assíncrono"** usando algo chamado **"corrotinas"**, com sintaxe **`async` e `await`**.
-Vamos ver aquela frase por partes na seção abaixo:
+Vamos ver aquela frase por partes nas seções abaixo:
* **Código assíncrono**
* **`async` e `await`**
* **Corrotinas**
-## Código assíncrono
+## Código assíncrono { #asynchronous-code }
Código assíncrono apenas significa que a linguagem 💬 tem um jeito de dizer para o computador / programa 🤖 que em certo ponto do código, ele 🤖 terá que esperar *algo* finalizar em outro lugar. Vamos dizer que esse *algo* seja chamado "arquivo lento" 📝.
@@ -74,10 +74,10 @@ Então o computador / programa 🤖 irá voltar sempre que tiver uma chance, sej
Depois, ele 🤖 pega a primeira tarefa para finalizar (vamos dizer, nosso "arquivo lento" 📝) e continua o que tem que fazer com ela.
-Esse "esperar por algo" normalmente se refere a operações I/O que são relativamente "lentas" (comparadas à velocidade do processador e da memória RAM), como esperar por:
+Esse "esperar por algo" normalmente se refere a operações I/O que são relativamente "lentas" (comparadas à velocidade do processador e da memória RAM), como esperar por:
* dados do cliente para serem enviados através da rede
-* dados enviados pelo seu programa serem recebidos pelo clente através da rede
+* dados enviados pelo seu programa serem recebidos pelo cliente através da rede
* conteúdo de um arquivo no disco ser lido pelo sistema e entregue ao seu programa
* conteúdo que seu programa deu ao sistema para ser escrito no disco
* uma operação em uma API remota
@@ -85,7 +85,7 @@ Esse "esperar por algo" normalmente se refere a operações I/O, essas operações são chamadas operações "limitadas por I/O".
+Quanto o tempo de execução é consumido majoritariamente pela espera de operações I/O, essas operações são chamadas operações "limitadas por I/O".
Isso é chamado de "assíncrono" porque o computador / programa não tem que ser "sincronizado" com a tarefa lenta, esperando pelo momento exato em que a tarefa finaliza, enquanto não faz nada, para ser capaz de pegar o resultado da tarefa e dar continuidade ao trabalho.
@@ -93,9 +93,9 @@ Ao invés disso, sendo um sistema "assíncrono", uma vez finalizada, a tarefa po
Para "síncrono" (contrário de "assíncrono") também é utilizado o termo "sequencial", porquê o computador / programa segue todos os passos, em sequência, antes de trocar para uma tarefa diferente, mesmo se alguns passos envolvam esperar.
-### Concorrência e hambúrgueres
+### Concorrência e hambúrgueres { #concurrency-and-burgers }
-Essa idéia de código **assíncrono** descrita acima é às vezes chamado de **"concorrência"**. Isso é diferente de **"paralelismo"**.
+Essa ideia de código **assíncrono** descrita acima é às vezes chamada de **"concorrência"**. Isso é diferente de **"paralelismo"**.
**Concorrência** e **paralelismo** ambos são relacionados a "diferentes coisas acontecendo mais ou menos ao mesmo tempo".
@@ -103,31 +103,51 @@ Mas os detalhes entre *concorrência* e *paralelismo* são bem diferentes.
Para ver essa diferença, imagine a seguinte história sobre hambúrgueres:
-### Hambúrgueres concorrentes
+### Hambúrgueres concorrentes { #concurrent-burgers }
Você vai com seu _crush_ na lanchonete, e fica na fila enquanto o caixa pega os pedidos das pessoas na sua frente. 😍
+
+
Então chega a sua vez, você pede dois saborosos hambúrgueres para você e seu _crush_. 🍔🍔
-O caixa diz alguma coisa para o cozinheiro na cozinha para que eles saivam que têm que preparar seus hambúrgueres (mesmo que ele esteja atualmente preparando os lanches dos outros clientes).
+
+
+O caixa diz alguma coisa para o cozinheiro na cozinha para que eles saibam que têm que preparar seus hambúrgueres (mesmo que ele esteja atualmente preparando os lanches dos outros clientes).
+
+
Você paga. 💸
O caixa te entrega seu número de chamada.
+
+
Enquanto você espera, você vai com seu _crush_ e pega uma mesa, senta e conversa com seu _crush_ por um bom tempo (já que seus hambúrgueres são muito saborosos, e leva um tempo para serem preparados).
Já que você está sentado na mesa com seu _crush_, esperando os hambúrgueres, você pode passar esse tempo admirando o quão lindo, maravilhoso e esperto é seu _crush_ ✨😍✨.
+
+
Enquanto espera e conversa com seu _crush_, de tempos em tempos, você verifica o número da chamada exibido no balcão para ver se já é sua vez.
Então em algum momento, é finalmente sua vez. Você vai ao balcão, pega seus hambúrgueres e volta para a mesa.
+
+
Você e seu _crush_ comem os hambúrgueres e aproveitam o tempo. ✨
+
+
+/// info | Informação
+
+Belas ilustrações de Ketrina Thompson. 🎨
+
+///
+
---
-Imagine que você seja o computador / programa nessa história.
+Imagine que você seja o computador / programa 🤖 nessa história.
Enquanto você está na fila, você está somente ocioso 😴, esperando por sua vez, sem fazer nada muito "produtivo". Mas a fila é rápida porque o caixa só está pegando os pedidos (não os preparando), então está tudo bem.
@@ -139,13 +159,13 @@ Contudo, à medida que você se afasta do balcão e senta na mesa, com um númer
Então o caixa 💁 diz que "seus hambúrgueres estão prontos" colocando seu número no balcão, mas você não corre que nem um maluco imediatamente quando o número exibido é o seu. Você sabe que ninguém irá roubar seus hambúrgueres porque você tem o seu número da chamada, e os outros têm os deles.
-Então você espera seu _crush_ terminar a história que estava contando (terminar o trabalho atual ⏯ / tarefa sendo processada 🤓), sorri gentilmente e diz que você está indo buscar os hambúrgueres.
+Então você espera seu _crush_ terminar a história que estava contando (terminar o trabalho atual ⏯ / tarefa sendo processada 🤓), sorri gentilmente e diz que você está indo buscar os hambúrgueres ⏸.
-Então você vai ao balcão 🔀, para a tarefa inicial que agora está finalizada⏯, pega os hambúrgueres, agradece, e leva-os para a mesa. Isso finaliza esse passo / tarefa da interação com o balcão ⏹. Isso, por sua vez, cria uma nova tarefa, a de "comer hambúrgueres" 🔀 ⏯, mas a tarefa anterior de "pegar os hambúrgueres" já está finalizada ⏹.
+Então você vai ao balcão 🔀, para a tarefa inicial que agora está finalizada ⏯, pega os hambúrgueres, agradece, e leva-os para a mesa. Isso finaliza esse passo / tarefa da interação com o balcão ⏹. Isso, por sua vez, cria uma nova tarefa, a de "comer hambúrgueres" 🔀 ⏯, mas a tarefa anterior de "pegar os hambúrgueres" já está finalizada ⏹.
-### Hambúrgueres paralelos
+### Hambúrgueres paralelos { #parallel-burgers }
-Agora vamos imaginar que esses não são "Hambúrgueres Concorrentes", e sim "Hambúrgueres Paralelos"
+Agora vamos imaginar que esses não são "Hambúrgueres Concorrentes", e sim "Hambúrgueres Paralelos".
Você vai com seu _crush_ na lanchonete paralela.
@@ -153,29 +173,47 @@ Você fica na fila enquanto vários (vamos dizer 8) caixas que também são cozi
Todo mundo na sua frente está esperando seus hambúrgueres ficarem prontos antes de deixar o caixa porque cada um dos 8 caixas vai e prepara o hambúrguer logo após receber o pedido, antes de pegar o próximo pedido.
+
+
Então é finalmente sua vez, você pede 2 hambúrgueres muito saborosos para você e seu _crush_.
Você paga 💸.
+
+
O caixa vai para a cozinha.
Você espera, na frente do balcão 🕙, para que ninguém pegue seus hambúrgueres antes de você, já que não tem números de chamadas.
+
+
Como você e seu _crush_ estão ocupados não permitindo que ninguém passe na frente e pegue seus hambúrgueres assim que estiverem prontos, você não pode dar atenção ao seu _crush_. 😞
-Isso é trabalho "síncrono", você está "sincronizado" com o caixa / cozinheiro👨🍳. Você tem que esperar 🕙 e estar lá no exato momento que o caixa / cozinheiro 👨🍳 terminar os hambúrgueres e os der a você, ou então, outro alguém pode pegá-los.
+Isso é trabalho "síncrono", você está "sincronizado" com o caixa / cozinheiro 👨🍳. Você tem que esperar 🕙 e estar lá no exato momento que o caixa / cozinheiro 👨🍳 terminar os hambúrgueres e os der a você, ou então, outro alguém pode pegá-los.
+
+
Então seu caixa / cozinheiro 👨🍳 finalmente volta com seus hambúrgueres, depois de um longo tempo esperando 🕙 por eles em frente ao balcão.
+
+
Você pega seus hambúrgueres e vai para a mesa com seu _crush_.
Vocês comem os hambúrgueres, e o trabalho está terminado. ⏹
+
+
Não houve muita conversa ou flerte já que a maior parte do tempo foi gasto esperando 🕙 na frente do balcão. 😞
+/// info | Informação
+
+Belas ilustrações de Ketrina Thompson. 🎨
+
+///
+
---
-Nesse cenário dos hambúrgueres paralelos, você é um computador / programa com dois processadores (você e seu _crush_), ambos esperando 🕙 e dedicando sua atenção ⏯ "esperando no balcão" 🕙 por um bom tempo.
+Nesse cenário dos hambúrgueres paralelos, você é um computador / programa 🤖 com dois processadores (você e seu _crush_), ambos esperando 🕙 e dedicando sua atenção ⏯ "esperando no balcão" 🕙 por um bom tempo.
A lanchonete paralela tem 8 processadores (caixas / cozinheiros), enquanto a lanchonete dos hambúrgueres concorrentes tinha apenas 2 (um caixa e um cozinheiro).
@@ -183,7 +221,7 @@ Ainda assim, a experiência final não foi a melhor. 😞
---
-Essa seria o equivalente paralelo à histório dos hambúrgueres. 🍔
+Essa seria o equivalente paralelo à história dos hambúrgueres. 🍔
Para um exemplo "mais real", imagine um banco.
@@ -195,7 +233,7 @@ E você tinha que esperar 🕙 na fila por um longo tempo ou poderia perder a ve
Você provavelmente não gostaria de levar seu _crush_ 😍 com você para um rolezinho no banco 🏦.
-### Conclusão dos hambúrgueres
+### Conclusão dos hambúrgueres { #burger-conclusion }
Nesse cenário dos "hambúrgueres com seu _crush_", como tem muita espera, faz mais sentido ter um sistema concorrente ⏸🔀⏯.
@@ -215,7 +253,7 @@ E esse é o mesmo nível de performance que você tem com o **FastAPI**.
E como você pode ter paralelismo e assincronicidade ao mesmo tempo, você tem uma maior performance do que a maioria dos frameworks NodeJS testados e lado a lado com Go, que é uma linguagem compilada, mais próxima ao C (tudo graças ao Starlette).
-### Concorrência é melhor que paralelismo?
+### Concorrência é melhor que paralelismo? { #is-concurrency-better-than-parallelism }
Não! Essa não é a moral da história.
@@ -239,7 +277,7 @@ Mas nesse caso, se você trouxesse os 8 ex-caixas / cozinheiros / agora-faxineir
Nesse cenário, cada um dos faxineiros (incluindo você) poderia ser um processador, fazendo a sua parte do trabalho.
-E a maior parte do tempo de execução é tomada por trabalho real (ao invés de ficar esperando), e o trabalho em um computador é feito pela CPU. Eles chamam esses problemas de "limitados por CPU".
+E a maior parte do tempo de execução é tomada por trabalho real (ao invés de ficar esperando), e o trabalho em um computador é feito pela CPU. Eles chamam esses problemas de "limitados por CPU".
---
@@ -249,22 +287,20 @@ Por exemplo:
* **Processamento de áudio** ou **imagem**
* **Visão Computacional**: uma imagem é composta por milhões de pixels, cada pixel tem 3 valores / cores, processar isso normalmente exige alguma computação em todos esses pixels ao mesmo tempo
+* **Aprendizado de Máquina**: Normalmente exige muita multiplicação de matrizes e vetores. Pense numa grande planilha com números e em multiplicar todos eles juntos e ao mesmo tempo.
+* **Deep Learning**: Esse é um subcampo do Aprendizado de Máquina, então, o mesmo se aplica. A diferença é que não há apenas uma grande planilha com números para multiplicar, mas um grande conjunto delas, e em muitos casos, você utiliza um processador especial para construir e/ou usar esses modelos.
-* **Machine Learning**: Normalmente exige muita multiplicação de matrizes e vetores. Pense numa grande planilha com números e em multiplicar todos eles juntos e ao mesmo tempo.
-
-* **Deep Learning**: Esse é um subcampo do Machine Learning, então, o mesmo se aplica. A diferença é que não há apenas uma grande planilha com números para multiplicar, mas um grande conjunto delas, e em muitos casos, você utiliza um processador especial para construir e/ou usar esses modelos.
-
-### Concorrência + Paralelismo: Web + Machine learning
+### Concorrência + Paralelismo: Web + Aprendizado de Máquina { #concurrency-parallelism-web-machine-learning }
Com **FastAPI** você pode levar a vantagem da concorrência que é muito comum para desenvolvimento web (o mesmo atrativo de NodeJS).
-Mas você também pode explorar os benefícios do paralelismo e multiprocessamento (tendo múltiplos processadores rodando em paralelo) para trabalhos **limitados por CPU** como aqueles em sistemas de Machine Learning.
+Mas você também pode explorar os benefícios do paralelismo e multiprocessamento (tendo múltiplos processadores rodando em paralelo) para trabalhos **limitados por CPU** como aqueles em sistemas de Aprendizado de Máquina.
-Isso, somado ao simples fato que Python é a principal linguagem para **Data Science**, Machine Learning e especialmente Deep Learning, faz do FastAPI uma ótima escolha para APIs web e aplicações com Data Science / Machine Learning (entre muitas outras).
+Isso, somado ao simples fato que Python é a principal linguagem para **Data Science**, Aprendizado de Máquina e especialmente Deep Learning, faz do FastAPI uma ótima escolha para APIs web e aplicações com Data Science / Aprendizado de Máquina (entre muitas outras).
-Para ver como alcançar esse paralelismo em produção veja a seção sobre [Deployment](deployment/index.md){.internal-link target=_blank}.
+Para ver como alcançar esse paralelismo em produção veja a seção sobre [Implantação](deployment/index.md){.internal-link target=_blank}.
-## `async` e `await`
+## `async` e `await` { #async-and-await }
Versões modernas do Python têm um modo muito intuitivo para definir código assíncrono. Isso faz parecer do mesmo jeito do código normal "sequencial" e fazer a "espera" para você nos momentos certos.
@@ -274,7 +310,7 @@ Quando tem uma operação que exigirá espera antes de dar os resultados e tem s
burgers = await get_burgers(2)
```
-A chave aqui é o `await`. Ele diz ao Python que ele tem que esperar por `get_burgers(2)` finalizar suas coisas 🕙 antes de armazenar os resultados em `burgers`. Com isso, o Python saberá que ele pode ir e fazer outras coisas 🔀 ⏯ nesse meio tempo (como receber outra requisição).
+A chave aqui é o `await`. Ele diz ao Python que ele tem que esperar ⏸ por `get_burgers(2)` finalizar suas coisas 🕙 antes de armazenar os resultados em `burgers`. Com isso, o Python saberá que ele pode ir e fazer outras coisas 🔀 ⏯ nesse meio tempo (como receber outra requisição).
Para o `await` funcionar, tem que estar dentro de uma função que suporte essa assincronicidade. Para fazer isso, apenas declare a função com `async def`:
@@ -306,18 +342,18 @@ burgers = get_burgers(2)
Então, se você está usando uma biblioteca que diz que você pode chamá-la com `await`, você precisa criar as *funções de operação de rota* com `async def`, como em:
-```Python hl_lines="2 3"
+```Python hl_lines="2-3"
@app.get('/burgers')
async def read_burgers():
burgers = await get_burgers(2)
return burgers
```
-### Mais detalhes técnicos
+### Mais detalhes técnicos { #more-technical-details }
Você deve ter observado que `await` pode ser usado somente dentro de funções definidas com `async def`.
-Mas ao mesmo tempo, funções definidas com `async def` têm que ser "aguardadas". Então, funções com `async def` pdem ser chamadas somente dentro de funções definidas com `async def` também.
+Mas ao mesmo tempo, funções definidas com `async def` têm que ser "aguardadas". Então, funções com `async def` podem ser chamadas somente dentro de funções definidas com `async def` também.
Então, sobre o ovo e a galinha, como você chama a primeira função async?
@@ -325,7 +361,7 @@ Se você estivar trabalhando com **FastAPI** não terá que se preocupar com iss
Mas se você quiser usar `async` / `await` sem FastAPI, você também pode fazê-lo.
-### Escreva seu próprio código assíncrono
+### Escreva seu próprio código assíncrono { #write-your-own-async-code }
Starlette (e **FastAPI**) são baseados no AnyIO, o que o torna compatível com ambos o asyncio da biblioteca padrão do Python, e o Trio.
@@ -333,10 +369,9 @@ Em particular, você pode usar diretamente o AnyIO por ser altamente compatível e ganhar seus benefícios (e.g. *concorrência estruturada*).
-Eu criei outra biblioteca em cima do AnyIO, como uma fina camada acima, para melhorar um pouco as anotações de tipo e obter melhor **autocompletar**, **erros de linha**, etc. Ela também possui uma introdução amigável e um tutorial para ajudar você a **entender** e escrever **seu próprio código async**: Asyncer. Seria particularmente útil se você precisar **combinar código async com código regular** (bloqueador/síncrono).
-
+Eu criei outra biblioteca em cima do AnyIO, como uma fina camada acima, para melhorar um pouco as anotações de tipo e obter melhor **preenchimento automático**, **erros inline**, etc. Ela também possui uma introdução amigável e um tutorial para ajudar você a **entender** e escrever **seu próprio código async**: Asyncer. Seria particularmente útil se você precisar **combinar código async com código regular** (bloqueador/síncrono).
-### Outras formas de código assíncrono
+### Outras formas de código assíncrono { #other-forms-of-asynchronous-code }
Esse estilo de usar `async` e `await` é relativamente novo na linguagem.
@@ -346,17 +381,17 @@ Essa mesma sintaxe (ou quase a mesma) foi também incluída recentemente em vers
Mas antes disso, controlar código assíncrono era bem mais complexo e difícil.
-Nas versões anteriores do Python, você poderia utilizar threads ou Gevent. Mas o código é bem mais complexo de entender, debugar, e pensar sobre.
+Nas versões anteriores do Python, você poderia utilizar threads ou Gevent. Mas o código é bem mais complexo de entender, debugar, e pensar sobre.
Nas versões anteriores do NodeJS / Navegador JavaScript, você utilizaria "callbacks". O que leva ao "inferno do callback".
-## Corrotinas
+## Corrotinas { #coroutines }
**Corrotina** é apenas um jeito bonitinho para a coisa que é retornada de uma função `async def`. O Python sabe que é algo como uma função, que pode começar e que vai terminar em algum ponto, mas que pode ser pausada ⏸ internamente também, sempre que tiver um `await` dentro dela.
Mas toda essa funcionalidade de código assíncrono com `async` e `await` é muitas vezes resumida como usando "corrotinas". É comparável ao principal recurso chave do Go, a "Gorrotina".
-## Conclusão
+## Conclusão { #conclusion }
Vamos ver a mesma frase de cima:
@@ -366,9 +401,9 @@ Isso pode fazer mais sentido agora. ✨
Tudo isso é o que empodera o FastAPI (através do Starlette) e que o faz ter uma performance tão impressionante.
-## Detalhes muito técnicos
+## Detalhes muito técnicos { #very-technical-details }
-/// warning
+/// warning | Atenção
Você pode provavelmente pular isso.
@@ -378,23 +413,23 @@ Se você tem certo conhecimento técnico (corrotinas, threads, blocking etc) e e
///
-### Funções de operação de rota
+### Funções de operação de rota { #path-operation-functions }
Quando você declara uma *função de operação de rota* com `def` normal ao invés de `async def`, ela é rodada em uma threadpool externa que é então aguardada, ao invés de ser chamada diretamente (já que ela bloquearia o servidor).
-Se você está chegando de outro framework assíncrono que não funciona como descrito acima e você está acostumado a definir *funções de operação de rota* triviais somente de computação com simples `def` para ter um mínimo ganho de performance (cerca de 100 nanosegundos), por favor observe que no **FastAPI** o efeito pode ser bem o oposto. Nesses casos, é melhor usar `async def` a menos que suas *funções de operação de rota* utilizem código que performe bloqueamento IO.
+Se você está chegando de outro framework assíncrono que não funciona como descrito acima e você está acostumado a definir *funções de operação de rota* triviais somente de computação com simples `def` para ter um mínimo ganho de performance (cerca de 100 nanosegundos), por favor observe que no **FastAPI** o efeito pode ser bem o oposto. Nesses casos, é melhor usar `async def` a menos que suas *funções de operação de rota* utilizem código que performe bloqueamento I/O.
Ainda, em ambas as situações, as chances são que o **FastAPI** [ainda será mais rápido](index.md#performance){.internal-link target=_blank} do que (ou ao menos comparável a) seu framework anterior.
-### Dependências
+### Dependências { #dependencies }
O mesmo se aplica para as [dependências](tutorial/dependencies/index.md){.internal-link target=_blank}. Se uma dependência tem as funções com padrão `def` ao invés de `async def`, ela é rodada no threadpool externo.
-### Sub-dependências
+### Sub-dependências { #sub-dependencies }
Você pode ter múltiplas dependências e [sub-dependências](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} requisitando uma à outra (como parâmetros de definições de funções), algumas delas podem ser criadas com `async def` e algumas com `def` normal. Isso ainda funcionaria, e aquelas criadas com `def` normal seriam chamadas em uma thread externa (do threadpool) ao invés de serem "aguardadas".
-### Outras funções de utilidade
+### Outras funções de utilidade { #other-utility-functions }
Qualquer outra função de utilidade que você chame diretamente pode ser criada com `def` normal ou `async def` e o FastAPI não irá afetar o modo como você a chama.
diff --git a/docs/pt/docs/benchmarks.md b/docs/pt/docs/benchmarks.md
index 07461ce46..c0b0c4c46 100644
--- a/docs/pt/docs/benchmarks.md
+++ b/docs/pt/docs/benchmarks.md
@@ -1,10 +1,10 @@
-# Comparações
+# Benchmarks { #benchmarks }
-As comparações independentes da TechEmpower mostram as aplicações **FastAPI** rodando com Uvicorn como um dos _frameworks_ Python mais rápidos disponíveis, somente atrás dos próprios Starlette e Uvicorn (utilizados internamente pelo FastAPI). (*)
+Benchmarks independentes da TechEmpower mostram as aplicações **FastAPI** rodando com Uvicorn como um dos frameworks Python mais rápidos disponíveis, somente atrás dos próprios Starlette e Uvicorn (utilizados internamente pelo FastAPI).
Mas quando se checa _benchmarks_ e comparações você deveria ter o seguinte em mente.
-## Comparações e velocidade
+## Benchmarks e velocidade { #benchmarks-and-speed }
Ao verificar os _benchmarks_, é comum observar algumas ferramentas de diferentes tipos comparadas como equivalentes.
diff --git a/docs/pt/docs/deployment/cloud.md b/docs/pt/docs/deployment/cloud.md
index fc490db4d..419fd7626 100644
--- a/docs/pt/docs/deployment/cloud.md
+++ b/docs/pt/docs/deployment/cloud.md
@@ -1,13 +1,24 @@
-# Implantar FastAPI em provedores de nuvem
+# Implantar FastAPI em provedores de nuvem { #deploy-fastapi-on-cloud-providers }
Você pode usar praticamente **qualquer provedor de nuvem** para implantar seu aplicativo FastAPI.
-Na maioria dos casos, os principais provedores de nuvem têm guias para implantar o FastAPI com eles.
+Na maioria dos casos, os principais provedores de nuvem têm tutoriais para implantar o FastAPI com eles.
-## Provedores de Nuvem - Patrocinadores
+## FastAPI Cloud { #fastapi-cloud }
-Alguns provedores de nuvem ✨ [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, o que garante o **desenvolvimento** contínuo e saudável do FastAPI e seu **ecossistema**.
+**FastAPI Cloud** é desenvolvido pelo mesmo autor e equipe por trás do **FastAPI**.
-E isso mostra seu verdadeiro comprometimento com o FastAPI e sua **comunidade** (você), pois eles não querem apenas fornecer a você um **bom serviço**, mas também querem ter certeza de que você tenha uma **estrutura boa e saudável**, o FastAPI. 🙇
+Ele simplifica o processo de **criar**, **implantar** e **acessar** uma API com o mínimo de esforço.
-Talvez você queira experimentar os serviços deles e seguir os guias.
+Traz a mesma **experiência do desenvolvedor** de criar aplicações com FastAPI para **implantá-las** na nuvem. 🎉
+
+FastAPI Cloud é o patrocinador principal e provedor de financiamento dos projetos de código aberto *FastAPI and friends*. ✨
+
+## Provedores de Nuvem - Patrocinadores { #cloud-providers-sponsors }
+
+Alguns outros provedores de nuvem ✨ [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ também. 🙇
+
+Você também pode considerá-los para seguir seus tutoriais e experimentar seus serviços:
+
+* Render
+* Railway
diff --git a/docs/pt/docs/deployment/concepts.md b/docs/pt/docs/deployment/concepts.md
index 014ca3797..6af4b177a 100644
--- a/docs/pt/docs/deployment/concepts.md
+++ b/docs/pt/docs/deployment/concepts.md
@@ -1,4 +1,4 @@
-# Conceitos de Implantações
+# Conceitos de Implantações { #deployments-concepts }
Ao implantar um aplicativo **FastAPI**, ou na verdade, qualquer tipo de API da web, há vários conceitos com os quais você provavelmente se importa e, usando-os, você pode encontrar a maneira **mais apropriada** de **implantar seu aplicativo**.
@@ -23,7 +23,7 @@ Nos próximos capítulos, darei a você mais **receitas concretas** para implant
Mas por enquanto, vamos verificar essas importantes **ideias conceituais**. Esses conceitos também se aplicam a qualquer outro tipo de API da web. 💡
-## Segurança - HTTPS
+## Segurança - HTTPS { #security-https }
No [capítulo anterior sobre HTTPS](https.md){.internal-link target=_blank} aprendemos como o HTTPS fornece criptografia para sua API.
@@ -31,7 +31,7 @@ Também vimos que o HTTPS normalmente é fornecido por um componente **externo**
E tem que haver algo responsável por **renovar os certificados HTTPS**, pode ser o mesmo componente ou pode ser algo diferente.
-### Ferramentas de exemplo para HTTPS
+### Ferramentas de exemplo para HTTPS { #example-tools-for-https }
Algumas das ferramentas que você pode usar como um proxy de terminação TLS são:
@@ -55,11 +55,11 @@ Mostrarei alguns exemplos concretos nos próximos capítulos.
Os próximos conceitos a serem considerados são todos sobre o programa que executa sua API real (por exemplo, Uvicorn).
-## Programa e Processo
+## Programa e Processo { #program-and-process }
Falaremos muito sobre o "**processo**" em execução, então é útil ter clareza sobre o que ele significa e qual é a diferença com a palavra "**programa**".
-### O que é um Programa
+### O que é um Programa { #what-is-a-program }
A palavra **programa** é comumente usada para descrever muitas coisas:
@@ -67,7 +67,7 @@ A palavra **programa** é comumente usada para descrever muitas coisas:
* O **arquivo** que pode ser **executado** pelo sistema operacional, por exemplo: `python`, `python.exe` ou `uvicorn`.
* Um programa específico enquanto está **em execução** no sistema operacional, usando a CPU e armazenando coisas na memória. Isso também é chamado de **processo**.
-### O que é um Processo
+### O que é um Processo { #what-is-a-process }
A palavra **processo** normalmente é usada de forma mais específica, referindo-se apenas ao que está sendo executado no sistema operacional (como no último ponto acima):
@@ -88,11 +88,11 @@ E, por exemplo, você provavelmente verá que há vários processos executando o
Agora que sabemos a diferença entre os termos **processo** e **programa**, vamos continuar falando sobre implantações.
-## Executando na inicialização
+## Executando na inicialização { #running-on-startup }
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
+### Em um servidor remoto { #in-a-remote-server }
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.
@@ -102,15 +102,15 @@ Mas se sua conexão com o servidor for perdida, o **processo em execução** pro
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
+### Executar automaticamente na inicialização { #run-automatically-on-startup }
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
+### Programa separado { #separate-program }
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
+### Ferramentas de exemplo para executar na inicialização { #example-tools-to-run-at-startup }
Alguns exemplos de ferramentas que podem fazer esse trabalho são:
@@ -125,29 +125,29 @@ Alguns exemplos de ferramentas que podem fazer esse trabalho são:
Darei exemplos mais concretos nos próximos capítulos.
-## Reinicializações
+## Reinicializações { #restarts }
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 cometemos erros { #we-make-mistakes }
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
+### Pequenos erros são tratados automaticamente { #small-errors-automatically-handled }
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
+### Erros maiores - Travamentos { #bigger-errors-crashes }
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
+### Reiniciar após falha { #restart-after-crash }
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...
@@ -161,7 +161,7 @@ Então, vamos nos concentrar nos casos principais, onde ele pode travar completa
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
+### Ferramentas de exemplo para reiniciar automaticamente { #example-tools-to-restart-automatically }
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.
@@ -176,19 +176,19 @@ Por exemplo, isso poderia ser resolvido por:
* Gerenciado internamente por um provedor de nuvem como parte de seus serviços
* Outros...
-## Replicação - Processos e Memória
+## Replicação - Processos e Memória { #replication-processes-and-memory }
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
+### Processos Múltiplos - Trabalhadores { #multiple-processes-workers }
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
+### Processos do Trabalhador e Portas { #worker-processes-and-ports }
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?
@@ -196,19 +196,19 @@ 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
+### Memória por Processo { #memory-per-process }
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
+### Memória do servidor { #server-memory }
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
+### Processos Múltiplos - Um Exemplo { #multiple-processes-an-example }
Neste exemplo, há um **Processo Gerenciador** que inicia e controla dois **Processos de Trabalhadores**.
@@ -224,7 +224,7 @@ Um detalhe interessante é que a porcentagem da **CPU usada** por cada processo
Se você tiver uma API que faz uma quantidade comparável de cálculos todas as vezes e tiver muitos clientes, então a **utilização da CPU** provavelmente *também será estável* (em vez de ficar constantemente subindo e descendo rapidamente).
-### Exemplos de ferramentas e estratégias de replicação
+### Exemplos de ferramentas e estratégias de replicação { #examples-of-replication-tools-and-strategies }
Pode haver várias abordagens para conseguir isso, e falarei mais sobre estratégias específicas nos próximos capítulos, por exemplo, ao falar sobre Docker e contêineres.
@@ -247,7 +247,7 @@ Falarei mais sobre imagens de contêiner, Docker, Kubernetes, etc. em um capítu
///
-## Etapas anteriores antes de começar
+## Etapas anteriores antes de começar { #previous-steps-before-starting }
Há muitos casos em que você deseja executar algumas etapas **antes de iniciar** sua aplicação.
@@ -269,7 +269,7 @@ Nesse caso, você não precisaria se preocupar com nada disso. 🤷
///
-### Exemplos de estratégias de etapas anteriores
+### Exemplos de estratégias de etapas anteriores { #examples-of-previous-steps-strategies }
Isso **dependerá muito** da maneira como você **implanta seu sistema** e provavelmente estará conectado à maneira como você inicia programas, lida com reinicializações, etc.
@@ -285,7 +285,7 @@ Darei exemplos mais concretos de como fazer isso com contêineres em um capítul
///
-## Utilização de recursos
+## Utilização de recursos { #resource-utilization }
Seu(s) servidor(es) é(são) um **recurso** que você pode consumir ou **utilizar**, com seus programas, o tempo de computação nas CPUs e a memória RAM disponível.
@@ -305,7 +305,7 @@ Você poderia colocar um **número arbitrário** para atingir, por exemplo, algo
Você pode usar ferramentas simples como `htop` para ver a CPU e a RAM usadas no seu servidor ou a quantidade usada por cada processo. Ou você pode usar ferramentas de monitoramento mais complexas, que podem ser distribuídas entre servidores, etc.
-## Recapitular
+## Recapitular { #recap }
Você leu aqui alguns dos principais conceitos que provavelmente precisa ter em mente ao decidir como implantar seu aplicativo:
diff --git a/docs/pt/docs/deployment/docker.md b/docs/pt/docs/deployment/docker.md
index cf18bb153..b26a69b54 100644
--- a/docs/pt/docs/deployment/docker.md
+++ b/docs/pt/docs/deployment/docker.md
@@ -1,4 +1,4 @@
-# FastAPI em contêineres - Docker
+# FastAPI em contêineres - Docker { #fastapi-in-containers-docker }
Ao fazer o deploy de aplicações FastAPI uma abordagem comum é construir uma **imagem de contêiner Linux**. Isso normalmente é feito usando o **Docker**. Você pode a partir disso fazer o deploy dessa imagem de algumas maneiras.
@@ -6,7 +6,7 @@ Usando contêineres Linux você tem diversas vantagens incluindo **segurança**,
/// tip | Dica
-Está com pressa e já sabe dessas coisas? Pode ir direto para [`Dockerfile` abaixo 👇](#construindo-uma-imagem-docker-para-fastapi).
+Está com pressa e já sabe dessas coisas? Pode ir direto para o [`Dockerfile` abaixo 👇](#build-a-docker-image-for-fastapi).
///
@@ -24,25 +24,25 @@ RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
COPY ./app /code/app
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
-# If running behind a proxy like Nginx or Traefik add --proxy-headers
-# CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80", "--proxy-headers"]
+# Se estiver executando atrás de um proxy como Nginx ou Traefik, adicione --proxy-headers
+# CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]
```
-## O que é um Contêiner
+## O que é um Contêiner { #what-is-a-container }
-Contêineres (especificamente contêineres Linux) são um jeito muito **leve** de empacotar aplicações contendo todas as dependências e arquivos necessários enquanto os mantém isolados de outros contêineres (outras aplicações ou componentes) no mesmo sistema.
+Contêineres (principalmente contêineres Linux) são um jeito muito **leve** de empacotar aplicações contendo todas as dependências e arquivos necessários enquanto os mantém isolados de outros contêineres (outras aplicações ou componentes) no mesmo sistema.
Contêineres Linux rodam usando o mesmo kernel Linux do hospedeiro (máquina, máquina virtual, servidor na nuvem, etc). Isso simplesmente significa que eles são muito leves (comparados com máquinas virtuais emulando um sistema operacional completo).
Dessa forma, contêineres consomem **poucos recursos**, uma quantidade comparável com rodar os processos diretamente (uma máquina virtual consumiria muito mais).
-Contêineres também possuem seus próprios processos (comumente um único processo), sistema de arquivos e rede **isolados** simplificando deploy, segurança, desenvolvimento, etc.
+Contêineres também possuem seus próprios processos em execução (comumente **um único processo**), sistema de arquivos e rede **isolados**, simplificando deploy, segurança, desenvolvimento, etc.
-## O que é uma Imagem de Contêiner
+## O que é uma Imagem de Contêiner { #what-is-a-container-image }
Um **contêiner** roda a partir de uma **imagem de contêiner**.
@@ -56,7 +56,7 @@ Uma imagem de contêiner é comparável ao arquivo de **programa** e seus conte
E o **contêiner** em si (em contraste à **imagem de contêiner**) é a própria instância da imagem rodando, comparável a um **processo**. Na verdade, um contêiner está rodando somente quando há um **processo rodando** (e normalmente é somente um processo). O contêiner finaliza quando não há um processo rodando nele.
-## Imagens de contêiner
+## Imagens de contêiner { #container-images }
Docker tem sido uma das principais ferramentas para criar e gerenciar **imagens de contêiner** e **contêineres**.
@@ -71,15 +71,15 @@ E existe muitas outras imagens para diferentes coisas, como bancos de dados, por
* MongoDB
* Redis, etc.
-Usando imagens de contêiner pré-prontas é muito fácil **combinar** e usar diferentes ferramentas. Por exemplo, para testar um novo banco de dados. Em muitos casos, você pode usar as **imagens oficiais** precisando somente de variáveis de ambiente para configurá-las.
+Usando imagens de contêiner pré-prontas é muito fácil **combinar** e usar diferentes ferramentas. Por exemplo, para testar um novo banco de dados. Em muitos casos, você pode usar as **imagens oficiais**, precisando somente de variáveis de ambiente para configurá-las.
-Dessa forma, em muitos casos você pode aprender sobre contêineres e Docker e re-usar essa experiência com diversos componentes e ferramentas.
+Dessa forma, em muitos casos você pode aprender sobre contêineres e Docker e reusar essa experiência com diversos componentes e ferramentas.
Então, você rodaria **vários contêineres** com coisas diferentes, como um banco de dados, uma aplicação Python, um servidor web com uma aplicação frontend React, e conectá-los juntos via sua rede interna.
Todos os sistemas de gerenciamento de contêineres (como Docker ou Kubernetes) possuem essas funcionalidades de rede integradas a eles.
-## Contêineres e Processos
+## Contêineres e Processos { #containers-and-processes }
Uma **imagem de contêiner** normalmente inclui em seus metadados o programa padrão ou comando que deve ser executado quando o **contêiner** é iniciado e os parâmetros a serem passados para esse programa. Muito similar ao que seria se estivesse na linha de comando.
@@ -91,11 +91,11 @@ Um contêiner normalmente tem um **único processo**, mas também é possível i
Mas não é possível ter um contêiner rodando sem **pelo menos um processo rodando**. Se o processo principal parar, o contêiner também para.
-## Construindo uma Imagem Docker para FastAPI
+## Construir uma Imagem Docker para FastAPI { #build-a-docker-image-for-fastapi }
Okay, vamos construir algo agora! 🚀
-Eu vou mostrar como construir uma **imagem Docker** para FastAPI **do zero**, baseado na **imagem oficial do Python**.
+Eu vou mostrar como construir uma **imagem Docker** para FastAPI **do zero**, baseada na imagem **oficial do Python**.
Isso é o que você quer fazer na **maioria dos casos**, por exemplo:
@@ -103,22 +103,21 @@ Isso é o que você quer fazer na **maioria dos casos**, por exemplo:
* Quando rodando em uma **Raspberry Pi**
* Usando um serviço em nuvem que irá rodar uma imagem de contêiner para você, etc.
-### O Pacote Requirements
+### Requisitos de Pacotes { #package-requirements }
-Você normalmente teria os **requisitos do pacote** para sua aplicação em algum arquivo.
+Você normalmente teria os **requisitos de pacotes** da sua aplicação em algum arquivo.
Isso pode depender principalmente da ferramenta que você usa para **instalar** esses requisitos.
-O caminho mais comum de fazer isso é ter um arquivo `requirements.txt` com os nomes dos pacotes e suas versões, um por linha.
+A forma mais comum de fazer isso é ter um arquivo `requirements.txt` com os nomes dos pacotes e suas versões, um por linha.
-Você, naturalmente, usaria as mesmas ideias que você leu em [Sobre Versões do FastAPI](versions.md){.internal-link target=_blank} para definir os intervalos de versões.
+Você, naturalmente, usaria as mesmas ideias que você leu em [Sobre versões do FastAPI](versions.md){.internal-link target=_blank} para definir os intervalos de versões.
Por exemplo, seu `requirements.txt` poderia parecer com:
```
-fastapi>=0.68.0,<0.69.0
-pydantic>=1.8.0,<2.0.0
-uvicorn>=0.15.0,<0.16.0
+fastapi[standard]>=0.113.0,<0.114.0
+pydantic>=2.7.0,<3.0.0
```
E você normalmente instalaria essas dependências de pacote com `pip`, por exemplo:
@@ -128,27 +127,25 @@ E você normalmente instalaria essas dependências de pacote com `pip`, por exem
```console
$ pip install -r requirements.txt
---> 100%
-Successfully installed fastapi pydantic uvicorn
+Successfully installed fastapi pydantic
```
-### Início do Handshake TLS
+### Início do Handshake TLS { #tls-handshake-start }
-O navegador então irá comunicar-se com esse endereço IP na **porta 443** (a porta HTTPS).
+O navegador então irá comunicar-se com esse endereço IP na porta 443 (a porta HTTPS).
A primeira parte dessa comunicação é apenas para estabelecer a conexão entre o cliente e o servidor e para decidir as chaves criptográficas a serem utilizadas, etc.
-Esse interação entre o cliente e o servidor para estabelecer uma conexão TLS é chamada de **Handshake TLS**.
+Esse interação entre o cliente e o servidor para estabelecer uma conexão TLS é chamada de Handshake TLS.
-### TLS com a Extensão SNI
+### TLS com a Extensão SNI { #tls-with-sni-extension }
-**Apenas um processo** no servidor pode se conectar a uma **porta** em um **endereço IP**. Poderiam existir outros processos conectados em outras portas desse mesmo endereço IP, mas apenas um para cada combinação de endereço IP e porta.
+Apenas um processo no servidor pode se conectar a uma porta em um endereço IP. Poderiam existir outros processos conectados em outras portas desse mesmo endereço IP, mas apenas um para cada combinação de endereço IP e porta.
TLS (HTTPS) usa a porta `443` por padrão. Então essa é a porta que precisamos.
-Como apenas um único processo pode se comunicar com essa porta, o processo que faria isso seria o **Proxy de Terminação TLS**.
+Como apenas um único processo pode se comunicar com essa porta, o processo que faria isso seria o Proxy de Terminação TLS.
-O Proxy de Terminação TLS teria acesso a um ou mais **certificados TLS** (certificados HTTPS).
+O Proxy de Terminação TLS teria acesso a um ou mais certificados TLS (certificados HTTPS).
-Utilizando a **extensão SNI** discutida acima, o Proxy de Terminação TLS iria checar qual dos certificados TLS (HTTPS) disponíveis deve ser usado para essa conexão, utilizando o que corresponda ao domínio esperado pelo cliente.
+Utilizando a extensão SNI discutida acima, o Proxy de Terminação TLS iria checar qual dos certificados TLS (HTTPS) disponíveis deve ser usado para essa conexão, utilizando o que corresponda ao domínio esperado pelo cliente.
Nesse caso, ele usaria o certificado para `someapp.example.com`.
-O cliente já **confia** na entidade que gerou o certificado TLS (nesse caso, o Let's Encrypt, mas veremos sobre isso mais tarde), então ele pode **verificar** que o certificado é válido.
+O cliente já confia na entidade que gerou o certificado TLS (nesse caso, o Let's Encrypt, mas veremos sobre isso mais tarde), então ele pode verificar que o certificado é válido.
-Então, utilizando o certificado, o cliente e o Proxy de Terminação TLS **decidem como encriptar** o resto da **comunicação TCP**. Isso completa a parte do **Handshake TLS**.
+Então, utilizando o certificado, o cliente e o Proxy de Terminação TLS decidem como encriptar o resto da comunicação TCP. Isso completa a parte do Handshake TLS.
-Após isso, o cliente e o servidor possuem uma **conexão TCP encriptada**, que é provida pelo TLS. E então eles podem usar essa conexão para começar a **comunicação HTTP** propriamente dita.
+Após isso, o cliente e o servidor possuem uma conexão TCP encriptada, que é provida pelo TLS. E então eles podem usar essa conexão para começar a comunicação HTTP propriamente dita.
-E isso resume o que é **HTTPS**, apenas **HTTP** simples dentro de uma **conexão TLS segura** em vez de uma conexão TCP pura (não encriptada).
+E isso resume o que é HTTPS, apenas HTTP simples dentro de uma conexão TLS segura em vez de uma conexão TCP pura (não encriptada).
/// tip | Dica
-Percebe que a encriptação da comunicação acontece no **nível do TCP**, não no nível do HTTP.
+Percebe que a encriptação da comunicação acontece no nível do TCP, não no nível do HTTP.
///
-### Solicitação HTTPS
+### Solicitação HTTPS { #https-request }
-Agora que o cliente e servidor (especialmente o navegador e o Proxy de Terminação TLS) possuem uma **conexão TCP encriptada**, eles podem iniciar a **comunicação HTTP**.
+Agora que o cliente e servidor (especialmente o navegador e o Proxy de Terminação TLS) possuem uma conexão TCP encriptada, eles podem iniciar a comunicação HTTP.
-Então, o cliente envia uma **solicitação HTTPS**. Que é apenas uma solicitação HTTP sobre uma conexão TLS encriptada.
+Então, o cliente envia uma solicitação HTTPS. Que é apenas uma solicitação HTTP sobre uma conexão TLS encriptada.
-### Desencriptando a Solicitação
+### Desencriptando a Solicitação { #decrypt-the-request }
-O Proxy de Terminação TLS então usaria a encriptação combinada para **desencriptar a solicitação**, e transmitiria a **solicitação básica (desencriptada)** para o processo executando a aplicação (por exemplo, um processo com Uvicorn executando a aplicação FastAPI).
+O Proxy de Terminação TLS então usaria a encriptação combinada para desencriptar a solicitação, e transmitiria a solicitação básica (desencriptada) para o processo executando a aplicação (por exemplo, um processo com Uvicorn executando a aplicação FastAPI).
-### Resposta HTTP
+### Resposta HTTP { #http-response }
-A aplicação processaria a solicitação e retornaria uma **resposta HTTP básica (não encriptada)** para o Proxy de Terminação TLS.
+A aplicação processaria a solicitação e retornaria uma resposta HTTP básica (não encriptada) para o Proxy de Terminação TLS.
-### Resposta HTTPS
+### Resposta HTTPS { #https-response }
-O Proxy de Terminação TLS iria **encriptar a resposta** utilizando a criptografia combinada anteriormente (que foi definida com o certificado para `someapp.example.com`), e devolveria para o navegador.
+O Proxy de Terminação TLS iria encriptar a resposta utilizando a criptografia combinada anteriormente (que foi definida com o certificado para `someapp.example.com`), e devolveria para o navegador.
-No próximo passo, o navegador verifica que a resposta é válida e encriptada com a chave criptográfica correta, etc. E depois **desencripta a resposta** e a processa.
+No próximo passo, o navegador verifica que a resposta é válida e encriptada com a chave criptográfica correta, etc. E depois desencripta a resposta e a processa.
-O cliente (navegador) saberá que a resposta vem do servidor correto por que ela usa a criptografia que foi combinada entre eles usando o **certificado HTTPS** anterior.
+O cliente (navegador) saberá que a resposta vem do servidor correto por que ela usa a criptografia que foi combinada entre eles usando o certificado HTTPS anterior.
-### Múltiplas Aplicações
+### Múltiplas Aplicações { #multiple-applications }
-Podem existir **múltiplas aplicações** em execução no mesmo servidor (ou servidores), por exemplo: outras APIs ou um banco de dados.
+Podem existir múltiplas aplicações em execução no mesmo servidor (ou servidores), por exemplo: outras APIs ou um banco de dados.
-Apenas um processo pode estar vinculado a um IP e porta (o Proxy de Terminação TLS, por exemplo), mas outras aplicações/processos também podem estar em execução no(s) servidor(es), desde que não tentem usar a mesma **combinação de IP público e porta**.
+Apenas um processo pode estar vinculado a um IP e porta (o Proxy de Terminação TLS, por exemplo), mas outras aplicações/processos também podem estar em execução no(s) servidor(es), desde que não tentem usar a mesma combinação de IP público e porta.
-Dessa forma, o Proxy de Terminação TLS pode gerenciar o HTTPS e os certificados de **múltiplos domínios**, para múltiplas aplicações, e então transmitir as requisições para a aplicação correta em cada caso.
+Dessa forma, o Proxy de Terminação TLS pode gerenciar o HTTPS e os certificados de múltiplos domínios, para múltiplas aplicações, e então transmitir as requisições para a aplicação correta em cada caso.
-### Renovação de Certificados
+### Renovação de Certificados { #certificate-renewal }
-Em algum momento futuro, cada certificado irá **expirar** (aproximadamente 3 meses após a aquisição).
+Em algum momento futuro, cada certificado irá expirar (aproximadamente 3 meses após a aquisição).
E então, haverá outro programa (em alguns casos pode ser o próprio Proxy de Terminação TLS) que irá interagir com o Let's Encrypt e renovar o(s) certificado(s).
-Os **certificados TLS** são **associados com um nome de domínio**, e não a um endereço IP.
+Os certificados TLS são associados com um nome de domínio, e não a um endereço IP.
-Então para renovar os certificados, o programa de renovação precisa **provar** para a autoridade (Let's Encrypt) que ele realmente **possui e controla esse domínio**>
+Então para renovar os certificados, o programa de renovação precisa provar para a autoridade (Let's Encrypt) que ele realmente "possui" e controla esse domínio.
Para fazer isso, e acomodar as necessidades de diferentes aplicações, existem diferentes opções para esse programa. Algumas escolhas populares são:
-* **Modificar alguns registros DNS**
- * Para isso, o programa de renovação precisa ter suporte as APIs do provedor DNS, então, dependendo do provedor DNS que você utilize, isso pode ou não ser uma opção viável.
-* **Executar como um servidor** (ao menos durante o processo de aquisição do certificado) no endereço IP público associado com o domínio.
+* Modificar alguns registros DNS
+ * Para isso, o programa de renovação precisa ter suporte às APIs do provedor DNS, então, dependendo do provedor DNS que você utilize, isso pode ou não ser uma opção viável.
+* Executar como um servidor (ao menos durante o processo de aquisição do certificado) no endereço IP público associado com o domínio.
* Como dito anteriormente, apenas um processo pode estar ligado a uma porta e IP específicos.
* Essa é uma dos motivos que fazem utilizar o mesmo Proxy de Terminação TLS para gerenciar a renovação de certificados ser tão útil.
* Caso contrário, você pode ter que parar a execução do Proxy de Terminação TLS momentaneamente, inicializar o programa de renovação para renovar os certificados, e então reiniciar o Proxy de Terminação TLS. Isso não é o ideal, já que sua(s) aplicação(ões) não vão estar disponíveis enquanto o Proxy de Terminação TLS estiver desligado.
-Todo esse processo de renovação, enquanto o aplicativo ainda funciona, é uma das principais razões para preferir um **sistema separado para gerenciar HTTPS** com um Proxy de Terminação TLS em vez de usar os certificados TLS no servidor da aplicação diretamente (e.g. com o Uvicorn).
+Todo esse processo de renovação, enquanto o aplicativo ainda funciona, é uma das principais razões para preferir um sistema separado para gerenciar HTTPS com um Proxy de Terminação TLS em vez de usar os certificados TLS no servidor da aplicação diretamente (e.g. com o Uvicorn).
-## Recapitulando
+## Cabeçalhos encaminhados por Proxy { #proxy-forwarded-headers }
-Possuir **HTTPS** habilitado na sua aplicação é bastante importante, e até **crítico** na maioria dos casos. A maior parte do esforço que você tem que colocar sobre o HTTPS como desenvolvedor está em **entender esses conceitos** e como eles funcionam.
+Ao usar um proxy para lidar com HTTPS, seu servidor de aplicação (por exemplo, Uvicorn via FastAPI CLI) não sabe nada sobre o processo de HTTPS; ele se comunica com HTTP simples com o Proxy de Terminação TLS.
-Mas uma vez que você saiba o básico de **HTTPS para desenvolvedores**, você pode combinar e configurar diferentes ferramentas facilmente para gerenciar tudo de uma forma simples.
+Esse proxy normalmente define alguns cabeçalhos HTTP dinamicamente antes de transmitir a requisição para o servidor de aplicação, para informar ao servidor de aplicação que a requisição está sendo encaminhada pelo proxy.
-Em alguns dos próximos capítulos, eu mostrarei para você vários exemplos concretos de como configurar o **HTTPS** para aplicações **FastAPI**. 🔒
+/// note | Detalhes Técnicos
+
+Os cabeçalhos do proxy são:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+No entanto, como o servidor de aplicação não sabe que está atrás de um proxy confiável, por padrão ele não confiaria nesses cabeçalhos.
+
+Mas você pode configurar o servidor de aplicação para confiar nos cabeçalhos encaminhados enviados pelo proxy. Se você estiver usando o FastAPI CLI, pode usar a opção de CLI `--forwarded-allow-ips` para dizer de quais IPs ele deve confiar nesses cabeçalhos encaminhados.
+
+Por exemplo, se o servidor de aplicação só estiver recebendo comunicação do proxy confiável, você pode defini-lo como `--forwarded-allow-ips="*"` para fazê-lo confiar em todos os IPs de entrada, já que ele só receberá requisições de seja lá qual for o IP usado pelo proxy.
+
+Dessa forma, a aplicação seria capaz de saber qual é sua própria URL pública, se está usando HTTPS, o domínio, etc.
+
+Isso seria útil, por exemplo, para lidar corretamente com redirecionamentos.
+
+/// tip | Dica
+
+Você pode saber mais sobre isso na documentação em [Atrás de um Proxy - Habilitar cabeçalhos encaminhados pelo proxy](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank}
+
+///
+
+## Recapitulando { #recap }
+
+Possuir HTTPS habilitado na sua aplicação é bastante importante, e até crítico na maioria dos casos. A maior parte do esforço que você tem que colocar sobre o HTTPS como desenvolvedor está em entender esses conceitos e como eles funcionam.
+
+Mas uma vez que você saiba o básico de HTTPS para desenvolvedores, você pode combinar e configurar diferentes ferramentas facilmente para gerenciar tudo de uma forma simples.
+
+Em alguns dos próximos capítulos, eu mostrarei para você vários exemplos concretos de como configurar o HTTPS para aplicações FastAPI. 🔒
diff --git a/docs/pt/docs/deployment/index.md b/docs/pt/docs/deployment/index.md
index 6b4290d1d..6a6c21804 100644
--- a/docs/pt/docs/deployment/index.md
+++ b/docs/pt/docs/deployment/index.md
@@ -1,7 +1,23 @@
-# Implantação
+# Implantação { #deployment }
-A implantação de uma aplicação **FastAPI** é relativamente simples.
+Implantar uma aplicação **FastAPI** é relativamente fácil.
-Existem várias maneiras para fazer isso, dependendo do seu caso específico e das ferramentas que você utiliza.
+## O que significa Implantação { #what-does-deployment-mean }
-Você verá mais detalhes para se ter em mente e algumas das técnicas para a implantação nas próximas seções.
+Implantar uma aplicação significa executar as etapas necessárias para torná-la disponível para os usuários.
+
+Para uma **web API**, isso normalmente envolve colocá-la em uma **máquina remota**, com um **programa de servidor** que ofereça bom desempenho, estabilidade, etc., de modo que seus **usuários** possam **acessar** a aplicação com eficiência e sem interrupções ou problemas.
+
+Isso contrasta com as fases de **desenvolvimento**, em que você está constantemente alterando o código, quebrando e consertando, parando e reiniciando o servidor de desenvolvimento, etc.
+
+## Estratégias de Implantação { #deployment-strategies }
+
+Há várias maneiras de fazer isso, dependendo do seu caso de uso específico e das ferramentas que você utiliza.
+
+Você pode **implantar um servidor** por conta própria usando uma combinação de ferramentas, pode usar um **serviço em nuvem** que faça parte do trabalho por você, entre outras opções.
+
+Por exemplo, nós, a equipe por trás do FastAPI, criamos **FastAPI Cloud**, para tornar a implantação de aplicações FastAPI na nuvem o mais simples possível, com a mesma experiência de desenvolvimento de trabalhar com o FastAPI.
+
+Vou mostrar alguns dos principais conceitos que você provavelmente deve ter em mente ao implantar uma aplicação **FastAPI** (embora a maior parte se aplique a qualquer outro tipo de aplicação web).
+
+Você verá mais detalhes para ter em mente e algumas das técnicas para fazer isso nas próximas seções. ✨
diff --git a/docs/pt/docs/deployment/manually.md b/docs/pt/docs/deployment/manually.md
index 46e580807..21d0f44cd 100644
--- a/docs/pt/docs/deployment/manually.md
+++ b/docs/pt/docs/deployment/manually.md
@@ -1,6 +1,6 @@
-# Execute um Servidor Manualmente
+# Execute um Servidor Manualmente { #run-a-server-manually }
-## Utilize o comando `fastapi run`
+## Utilize o comando `fastapi run` { #use-the-fastapi-run-command }
Em resumo, utilize o comando `fastapi run` para inicializar sua aplicação FastAPI:
@@ -42,23 +42,23 @@ Isto deve funcionar para a maioria dos casos. 😎
Você pode utilizar esse comando, por exemplo, para iniciar sua aplicação **FastAPI** em um contêiner, em um servidor, etc.
-## Servidores ASGI
+## Servidores ASGI { #asgi-servers }
Vamos nos aprofundar um pouco mais em detalhes.
-FastAPI utiliza um padrão para construir frameworks e servidores web em Python chamado ASGI. FastAPI é um framework web ASGI.
+FastAPI utiliza um padrão para construir frameworks e servidores web em Python chamado ASGI. FastAPI é um framework web ASGI.
A principal coisa que você precisa para executar uma aplicação **FastAPI** (ou qualquer outra aplicação ASGI) em uma máquina de servidor remoto é um programa de servidor ASGI como o **Uvicorn**, que é o que vem por padrão no comando `fastapi`.
Existem diversas alternativas, incluindo:
-* Uvicorn: um servidor ASGI de alta performance.
-* Hypercorn: um servidor ASGI compátivel com HTTP/2, Trio e outros recursos.
+* Uvicorn: um servidor ASGI de alta performance.
+* Hypercorn: um servidor ASGI compatível com HTTP/2, Trio e outros recursos.
* Daphne: servidor ASGI construído para Django Channels.
* Granian: um servidor HTTP Rust para aplicações Python.
* NGINX Unit: NGINX Unit é um runtime de aplicação web leve e versátil.
-## Máquina Servidora e Programa Servidor
+## Máquina Servidora e Programa Servidor { #server-machine-and-server-program }
Existe um pequeno detalhe sobre estes nomes para se manter em mente. 💡
@@ -68,7 +68,7 @@ Apenas tenha em mente que quando você ler "servidor" em geral, isso pode se ref
Quando se refere à máquina remota, é comum chamá-la de **servidor**, mas também de **máquina**, **VM** (máquina virtual), **nó**. Todos esses termos se referem a algum tipo de máquina remota, normalmente executando Linux, onde você executa programas.
-## Instale o Programa Servidor
+## Instale o Programa Servidor { #install-the-server-program }
Quando você instala o FastAPI, ele vem com um servidor de produção, o Uvicorn, e você pode iniciá-lo com o comando `fastapi run`.
@@ -100,7 +100,7 @@ Quando você instala o FastAPI com algo como `pip install "fastapi[standard]"`,
///
-## Execute o Programa Servidor
+## Execute o Programa Servidor { #run-the-server-program }
Se você instalou um servidor ASGI manualmente, normalmente precisará passar uma string de importação em um formato especial para que ele importe sua aplicação FastAPI:
@@ -131,7 +131,7 @@ from main import app
Cada programa de servidor ASGI alternativo teria um comando semelhante, você pode ler mais na documentação respectiva.
-/// warning | Aviso
+/// warning | Atenção
Uvicorn e outros servidores suportam a opção `--reload` que é útil durante o desenvolvimento.
@@ -141,7 +141,7 @@ Ela ajuda muito durante o **desenvolvimento**, mas você **não deve** usá-la e
///
-## Conceitos de Implantação
+## Conceitos de Implantação { #deployment-concepts }
Esses exemplos executam o programa do servidor (por exemplo, Uvicorn), iniciando **um único processo**, ouvindo em todos os IPs (`0.0.0.0`) em uma porta predefinida (por exemplo, `80`).
diff --git a/docs/pt/docs/deployment/server-workers.md b/docs/pt/docs/deployment/server-workers.md
index a0db1bea4..bfb1e6687 100644
--- a/docs/pt/docs/deployment/server-workers.md
+++ b/docs/pt/docs/deployment/server-workers.md
@@ -1,4 +1,4 @@
-# Trabalhadores do Servidor - Uvicorn com Trabalhadores
+# Trabalhadores do Servidor - Uvicorn com Trabalhadores { #server-workers-uvicorn-with-workers }
Vamos rever os conceitos de implantação anteriores:
@@ -25,7 +25,7 @@ Em particular, ao executar no **Kubernetes** você provavelmente **não** vai qu
///
-## Vários trabalhadores
+## Vários trabalhadores { #multiple-workers }
Você pode iniciar vários trabalhadores com a opção de linha de comando `--workers`:
@@ -111,7 +111,7 @@ A única opção nova aqui é `--workers` informando ao Uvicorn para iniciar 4 p
Você também pode ver que ele mostra o **PID** de cada processo, `27365` para o processo pai (este é o **gerenciador de processos**) e um para cada processo de trabalho: `27368`, `27369`, `27370` e `27367`.
-## Conceitos de Implantação
+## Conceitos de Implantação { #deployment-concepts }
Aqui você viu como usar vários **trabalhadores** para **paralelizar** a execução do aplicativo, aproveitar **vários núcleos** na CPU e conseguir atender **mais solicitações**.
@@ -124,13 +124,13 @@ Da lista de conceitos de implantação acima, o uso de trabalhadores ajudaria pr
* **Memória**
* **Etapas anteriores antes de iniciar**
-## Contêineres e Docker
+## Contêineres e Docker { #containers-and-docker }
No próximo capítulo sobre [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}, explicarei algumas estratégias que você pode usar para lidar com os outros **conceitos de implantação**.
Vou mostrar como **construir sua própria imagem do zero** para executar um único processo Uvicorn. É um processo simples e provavelmente é o que você gostaria de fazer ao usar um sistema de gerenciamento de contêineres distribuídos como o **Kubernetes**.
-## Recapitular
+## Recapitular { #recap }
Você pode usar vários processos de trabalho com a opção CLI `--workers` com os comandos `fastapi` ou `uvicorn` para aproveitar as vantagens de **CPUs multi-core** e executar **vários processos em paralelo**.
diff --git a/docs/pt/docs/deployment/versions.md b/docs/pt/docs/deployment/versions.md
index 323ddbd45..a2aca5a17 100644
--- a/docs/pt/docs/deployment/versions.md
+++ b/docs/pt/docs/deployment/versions.md
@@ -1,46 +1,46 @@
-# Sobre as versões do FastAPI
+# Sobre as versões do FastAPI { #about-fastapi-versions }
-**FastAPI** já está sendo usado em produção em diversas aplicações e sistemas, a cobertura de testes é mantida em 100%, mas seu desenvolvimento está avançando rapidamente.
+**FastAPI** já está sendo usado em produção em muitas aplicações e sistemas. E a cobertura de testes é mantida em 100%. Mas seu desenvolvimento ainda está avançando rapidamente.
-Novos recursos são adicionados com frequência, bugs são corrigidos regularmente e o código está sempre melhorando.
+Novas funcionalidades são adicionadas com frequência, bugs são corrigidos regularmente e o código continua melhorando continuamente.
-Esse é o motivo das versões atuais estarem em `0.x.x`, significando que em cada versão pode haver mudanças significativas, tudo isso seguindo as convenções de controle de versão semântica.
+É por isso que as versões atuais ainda são `0.x.x`, isso reflete que cada versão pode potencialmente ter mudanças significativas. Isso segue as convenções de Versionamento Semântico.
-Já é possível criar aplicativos de produção com **FastAPI** (e provavelmente você já faz isso há algum tempo), apenas precisando ter certeza de usar uma versão que funcione corretamente com o resto do seu código.
+Você pode criar aplicações de produção com **FastAPI** agora mesmo (e provavelmente já vem fazendo isso há algum tempo), apenas certifique-se de usar uma versão que funcione corretamente com o resto do seu código.
-## Fixe a sua versão de `fastapi`
+## Fixe a sua versão de `fastapi` { #pin-your-fastapi-version }
-A primeira coisa que você deve fazer é "fixar" a versão do **FastAPI** que você está utilizando na mais atual, na qual você sabe que funciona corretamente para o seu aplicativo.
+A primeira coisa que você deve fazer é "fixar" a versão do **FastAPI** que você está utilizando na versão mais recente específica que você sabe que funciona corretamente para a sua aplicação.
-Por exemplo, supondo que você está usando a versão `0.45.0` em sua aplicação.
+Por exemplo, suponha que você esteja usando a versão `0.112.0` em sua aplicação.
-Caso você utilize o arquivo `requirements.txt`, você poderia especificar a versão com:
+Se você usa um arquivo `requirements.txt`, você poderia especificar a versão com:
```txt
-fastapi==0.45.0
+fastapi[standard]==0.112.0
```
-Isso significa que você conseguiria utilizar a versão exata `0.45.0`.
+isso significaria que você usaria exatamente a versão `0.112.0`.
-Ou, você poderia fixá-la com:
+Ou você também poderia fixá-la com:
```txt
-fastapi>=0.45.0,<0.46.0
+fastapi[standard]>=0.112.0,<0.113.0
```
-isso significa que você iria usar as versões `0.45.0` ou acima, mas inferiores à `0.46.0`, por exemplo, a versão `0.45.2` ainda seria aceita.
+isso significaria que você usaria as versões `0.112.0` ou superiores, mas menores que `0.113.0`, por exemplo, a versão `0.112.2` ainda seria aceita.
-Se você usar qualquer outra ferramenta para gerenciar suas instalações, como Poetry, Pipenv ou outras, todas elas têm uma maneira que você pode usar para definir as versões específicas dos seus pacotes.
+Se você usa qualquer outra ferramenta para gerenciar suas instalações, como `uv`, Poetry, Pipenv ou outras, todas elas têm uma forma de definir versões específicas para seus pacotes.
-## Versões disponíveis
+## Versões disponíveis { #available-versions }
-Você pode ver as versões disponíveis (por exemplo, para verificar qual é a versão atual) em [Release Notes](../release-notes.md){.internal-link target=\_blank}.
+Você pode ver as versões disponíveis (por exemplo, para verificar qual é a mais recente) nas [Release Notes](../release-notes.md){.internal-link target=_blank}.
-## Sobre versões
+## Sobre versões { #about-versions }
-Seguindo as convenções de controle de versão semântica, qualquer versão abaixo de `1.0.0` pode adicionar mudanças significativas.
+Seguindo as convenções de Versionamento Semântico, qualquer versão abaixo de `1.0.0` pode potencialmente adicionar mudanças significativas.
-FastAPI também segue a convenção de que qualquer alteração de versão "PATCH" é para correção de bugs e alterações não significativas.
+FastAPI também segue a convenção de que qualquer alteração de versão "PATCH" é para correções de bugs e mudanças que não quebram compatibilidade.
/// tip | Dica
@@ -54,40 +54,40 @@ Logo, você deveria conseguir fixar a versão, como:
fastapi>=0.45.0,<0.46.0
```
-Mudanças significativas e novos recursos são adicionados em versões "MINOR".
+Mudanças significativas e novas funcionalidades são adicionadas em versões "MINOR".
/// tip | Dica
-O "MINOR" é o número que está no meio, por exemplo, em `0.2.3`, a versão MINOR é `2`.
+O "MINOR" é o número do meio, por exemplo, em `0.2.3`, a versão MINOR é `2`.
///
-## Atualizando as versões do FastAPI
+## Atualizando as versões do FastAPI { #upgrading-the-fastapi-versions }
Você deve adicionar testes para a sua aplicação.
-Com **FastAPI** isso é muito fácil (graças a Starlette), verifique a documentação: [Testing](../tutorial/testing.md){.internal-link target=\_blank}
+Com **FastAPI** isso é muito fácil (graças ao Starlette), veja a documentação: [Testing](../tutorial/testing.md){.internal-link target=_blank}
-Após a criação dos testes, você pode atualizar a sua versão do **FastAPI** para uma mais recente, execute os testes para se certificar de que todo o seu código está funcionando corretamente.
+Depois que você tiver testes, você pode atualizar a sua versão do **FastAPI** para uma mais recente e se certificar de que todo o seu código está funcionando corretamente executando seus testes.
-Se tudo estiver funcionando, ou após você realizar as alterações necessárias e todos os testes estiverem passando, então você pode fixar sua versão de `FastAPI` para essa mais nova.
+Se tudo estiver funcionando, ou após você realizar as alterações necessárias e todos os testes estiverem passando, então você pode fixar sua versão de `fastapi` para essa versão mais recente.
-## Sobre Starlette
+## Sobre Starlette { #about-starlette }
Não é recomendado fixar a versão de `starlette`.
Versões diferentes de **FastAPI** utilizarão uma versão específica e mais recente de Starlette.
-Então, você pode deixar **FastAPI** escolher a versão compatível e correta de Starlette.
+Então, você pode deixar **FastAPI** usar a versão correta do Starlette.
-## Sobre Pydantic
+## Sobre Pydantic { #about-pydantic }
-Pydantic incluí os testes para **FastAPI** em seus próprios testes, então as novas versões de Pydantic (acima da `1.0.0`) sempre serão compatíveis com FastAPI.
+Pydantic inclui os testes para **FastAPI** em seus próprios testes, então novas versões do Pydantic (acima de `1.0.0`) são sempre compatíveis com FastAPI.
-Você pode fixar qualquer versão de Pydantic que desejar, desde que seja acima da `1.0.0` e abaixo da `2.0.0`.
+Você pode fixar o Pydantic em qualquer versão acima de `1.0.0` que funcione para você.
Por exemplo:
```txt
-pydantic>=1.2.0,<2.0.0
+pydantic>=2.7.0,<3.0.0
```
diff --git a/docs/pt/docs/environment-variables.md b/docs/pt/docs/environment-variables.md
index 432f78af0..342361b91 100644
--- a/docs/pt/docs/environment-variables.md
+++ b/docs/pt/docs/environment-variables.md
@@ -1,4 +1,4 @@
-# Variáveis de Ambiente
+# Variáveis de Ambiente { #environment-variables }
/// tip | Dica
@@ -10,7 +10,7 @@ Uma variável de ambiente (também conhecida como "**env var**") é uma variáve
Variáveis de ambiente podem ser úteis para lidar com **configurações** do aplicativo, como parte da **instalação** do Python, etc.
-## Criar e Usar Variáveis de Ambiente
+## Criar e Usar Variáveis de Ambiente { #create-and-use-env-vars }
Você pode **criar** e usar variáveis de ambiente no **shell (terminal)**, sem precisar do Python:
@@ -50,7 +50,7 @@ Hello Wade Wilson
////
-## Ler Variáveis de Ambiente no Python
+## Ler Variáveis de Ambiente no Python { #read-env-vars-in-python }
Você também pode criar variáveis de ambiente **fora** do Python, no terminal (ou com qualquer outro método) e depois **lê-las no Python**.
@@ -157,7 +157,7 @@ Você pode ler mais sobre isso em
```console
-$ fastapi dev 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 - Development mode ───────────╮
- │ │
- │ Serving at: http://127.0.0.1:8000 │
- │ │
- │ API docs: http://127.0.0.1:8000/docs │
- │ │
- │ Running in development mode, for production use: │
- │ │
- │ fastapi run │
- │ │
- ╰─────────────────────────────────────────────────────╯
-
-INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
-INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
-INFO: Started reloader process [2265862] using WatchFiles
-INFO: Started server process [2265873]
-INFO: Waiting for application startup.
-INFO: Application startup complete.
-```
+$ fastapi dev main.py
-
-## Alterar o tema
+## Alterar o tema { #change-the-theme }
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] *}
+{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *}
Essa configuração alteraria o tema de cores de destaque de sintaxe:
-## Alterar parâmetros de UI padrão do Swagger
+## Alterar parâmetros de UI padrão do Swagger { #change-default-swagger-ui-parameters }
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] *}
+{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}
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] *}
+{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *}
-## Outros parâmetros da UI do Swagger
+## Outros parâmetros da UI do Swagger { #other-swagger-ui-parameters }
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
+## Configurações somente JavaScript { #javascript-only-settings }
-A interface do usuário do Swagger também permite que outras configurações sejam objetos **somente JavaScript** (por exemplo, funções JavaScript).
+A UI 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:
+O FastAPI também inclui estas configurações `presets` somente para JavaScript:
```JavaScript
presets: [
@@ -67,4 +67,4 @@ presets: [
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.
+Se você precisar usar configurações somente JavaScript como essas, você pode usar um dos métodos acima. Substitua toda a *operação de rota* 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
index b7de6c8bd..adda9eca5 100644
--- a/docs/pt/docs/how-to/custom-docs-ui-assets.md
+++ b/docs/pt/docs/how-to/custom-docs-ui-assets.md
@@ -1,26 +1,26 @@
-# Recursos Estáticos Personalizados para a UI de Documentação (Hospedagem Própria)
+# Recursos Estáticos Personalizados para a UI de Documentação (Hospedagem Própria) { #custom-docs-ui-static-assets-self-hosting }
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.
+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
+## CDN Personalizado para JavaScript e CSS { #custom-cdn-for-javascript-and-css }
-Vamos supor que você deseja usar um CDN diferente, por exemplo, você deseja usar `https://unpkg.com/`.
+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
+### Desativar a documentação automática { #disable-the-automatic-docs }
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`:
+Para desativá-los, defina suas URLs como `None` ao criar sua aplicação FastAPI:
-{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *}
-### Incluir a documentação personalizada
+### Incluir a documentação personalizada { #include-the-custom-docs }
Agora você pode criar as *operações de rota* para a documentação personalizada.
@@ -34,7 +34,7 @@ Você pode reutilizar as funções internas do FastAPI para criar as páginas HT
E de forma semelhante para o ReDoc...
-{* ../../docs_src/custom_docs_ui/tutorial001.py hl[2:6,11:19,22:24,27:33] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *}
/// tip | Dica
@@ -46,23 +46,23 @@ Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse aux
///
-### Criar uma *operação de rota* para testar
+### Criar uma *operação de rota* para testar { #create-a-path-operation-to-test-it }
Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
-{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *}
-### Teste
+### Teste { #test-it }
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
+## Hospedagem Própria de JavaScript e CSS para a documentação { #self-hosting-javascript-and-css-for-docs }
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.
+Aqui você verá como providenciar esses arquivos você mesmo, na mesma aplicação FastAPI, e configurar a documentação para usá-los.
-### Estrutura de Arquivos do Projeto
+### Estrutura de Arquivos do Projeto { #project-file-structure }
Vamos supor que a estrutura de arquivos do seu projeto se pareça com isso:
@@ -85,7 +85,7 @@ Sua nova estrutura de arquivos poderia se parecer com isso:
└── static/
```
-### Baixe os arquivos
+### Baixe os arquivos { #download-the-files }
Baixe os arquivos estáticos necessários para a documentação e coloque-os no diretório `static/`.
@@ -96,7 +96,7 @@ Você provavelmente pode clicar com o botão direito em cada link e selecionar u
* `swagger-ui-bundle.js`
* `swagger-ui.css`
-E o **ReDoc** usa os arquivos:
+E o **ReDoc** usa o arquivo:
* `redoc.standalone.js`
@@ -113,14 +113,14 @@ Depois disso, sua estrutura de arquivos deve se parecer com:
└── swagger-ui.css
```
-### Prover os arquivos estáticos
+### Prover os arquivos estáticos { #serve-the-static-files }
* Importe `StaticFiles`.
* "Monte" a instância `StaticFiles()` em um caminho específico.
-{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *}
-### Teste os arquivos estáticos
+### Teste os arquivos estáticos { #test-the-static-files }
Inicialize seu aplicativo e vá para http://127.0.0.1:8000/static/redoc.standalone.js.
@@ -138,15 +138,15 @@ Isso confirma que você está conseguindo fornecer arquivos estáticos do seu ap
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
+### Desativar a documentação automática para arquivos estáticos { #disable-the-automatic-docs-for-static-files }
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`:
+Para desativá-los, defina suas URLs como `None` ao criar sua aplicação FastAPI:
-{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *}
-### Incluir a documentação personalizada para arquivos estáticos
+### Incluir a documentação personalizada para arquivos estáticos { #include-the-custom-docs-for-static-files }
E da mesma forma que com um CDN personalizado, agora você pode criar as *operações de rota* para a documentação personalizada.
@@ -155,12 +155,12 @@ Novamente, você pode reutilizar as funções internas do FastAPI para criar as
* `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_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 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] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[2:6,14:22,25:27,30:36] *}
/// tip | Dica
@@ -172,13 +172,13 @@ Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse aux
///
-### Criar uma *operação de rota* para testar arquivos estáticos
+### Criar uma *operação de rota* para testar arquivos estáticos { #create-a-path-operation-to-test-static-files }
Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
-{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[39:41] *}
-### Teste a UI de Arquivos Estáticos
+### Teste a UI de Arquivos Estáticos { #test-static-files-ui }
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.
diff --git a/docs/pt/docs/how-to/custom-request-and-route.md b/docs/pt/docs/how-to/custom-request-and-route.md
index 8f432f6fe..b4ea1c282 100644
--- a/docs/pt/docs/how-to/custom-request-and-route.md
+++ b/docs/pt/docs/how-to/custom-request-and-route.md
@@ -1,12 +1,12 @@
-# Requisições Personalizadas e Classes da APIRoute
+# Request e classe APIRoute personalizadas { #custom-request-and-apiroute-class }
-Em algum casos, você pode querer sobreescrever a lógica usada pelas classes `Request`e `APIRoute`.
+Em alguns casos, você pode querer sobrescrever a lógica usada pelas classes `Request` e `APIRoute`.
-Em particular, isso pode ser uma boa alternativa para uma lógica em um middleware
+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
+/// danger | Cuidado
Isso é um recurso "avançado".
@@ -14,7 +14,7 @@ Se você for um iniciante em **FastAPI** você deve considerar pular essa seçã
///
-## Casos de Uso
+## Casos de Uso { #use-cases }
Alguns casos de uso incluem:
@@ -22,13 +22,13 @@ Alguns casos de uso incluem:
* 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
+## Manipulando codificações de corpo de requisição personalizadas { #handling-custom-request-body-encodings }
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
+### Criar uma classe `GzipRequest` personalizada { #create-a-custom-gziprequest-class }
/// tip | Dica
@@ -42,9 +42,9 @@ 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] *}
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}
-### Criar uma classe `GzipRoute` personalizada
+### Criar uma classe `GzipRoute` personalizada { #create-a-custom-gziproute-class }
Em seguida, criamos uma subclasse personalizada de `fastapi.routing.APIRoute` que fará uso do `GzipRequest`.
@@ -54,11 +54,11 @@ Esse método retorna uma função. E essa função é o que irá receber uma req
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] *}
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *}
/// 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` tem um atributo `request.scope`, que é apenas um `dict` do Python contendo os metadados relacionados à requisição.
Um `Request` também tem um `request.receive`, que é uma função para "receber" o corpo da requisição.
@@ -66,7 +66,7 @@ O dicionário `scope` e a função `receive` são ambos parte da especificação
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.
+Para aprender mais sobre o `Request` confira a documentação do Starlette sobre Requests.
///
@@ -78,7 +78,7 @@ 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
+## Acessando o corpo da requisição em um manipulador de exceção { #accessing-the-request-body-in-an-exception-handler }
/// tip | Dica
@@ -92,18 +92,18 @@ Também podemos usar essa mesma abordagem para acessar o corpo da requisição e
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] *}
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *}
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] *}
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *}
-## Classe `APIRoute` personalizada em um router
+## Classe `APIRoute` personalizada em um router { #custom-apiroute-class-in-a-router }
-você também pode definir o parametro `route_class` de uma `APIRouter`;
+Você também pode definir o parâmetro `route_class` de uma `APIRouter`:
-{* ../../docs_src/custom_request_and_route/tutorial003.py hl[26] *}
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.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] *}
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *}
diff --git a/docs/pt/docs/how-to/extending-openapi.md b/docs/pt/docs/how-to/extending-openapi.md
index b4785edc1..b1b50ce65 100644
--- a/docs/pt/docs/how-to/extending-openapi.md
+++ b/docs/pt/docs/how-to/extending-openapi.md
@@ -1,10 +1,10 @@
-# Extendendo o OpenAPI
+# Extendendo o OpenAPI { #extending-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 { #the-normal-process }
O processo normal (padrão) é o seguinte:
@@ -33,31 +33,31 @@ O parâmetro `summary` está disponível no OpenAPI 3.1.0 e superior, suportado
///
-## Sobrescrevendo os padrões
+## Sobrescrevendo os padrões { #overriding-the-defaults }
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
+### **FastAPI** Normal { #normal-fastapi }
Primeiro, escreva toda a sua aplicação **FastAPI** normalmente:
-{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[1,4,7:9] *}
-### Gerar o esquema OpenAPI
+### Gerar o esquema OpenAPI { #generate-the-openapi-schema }
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[2,15:21] *}
-### Modificar o esquema OpenAPI
+### Modificar o esquema OpenAPI { #modify-the-openapi-schema }
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[22:24] *}
-### Armazenar em cache o esquema OpenAPI
+### Armazenar em cache o esquema OpenAPI { #cache-the-openapi-schema }
Você pode usar a propriedade `.openapi_schema` como um "cache" para armazenar o esquema gerado.
@@ -65,16 +65,16 @@ Dessa forma, sua aplicação não precisará gerar o esquema toda vez que um usu
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] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[13:14,25:26] *}
-### Sobrescrever o método
+### Sobrescrever o método { #override-the-method }
Agora, você pode substituir o método `.openapi()` pela sua nova função.
-{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[29] *}
-### Verificar
+### Verificar { #check-it }
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/general.md b/docs/pt/docs/how-to/general.md
index 4f21463b2..7f9146862 100644
--- a/docs/pt/docs/how-to/general.md
+++ b/docs/pt/docs/how-to/general.md
@@ -1,39 +1,38 @@
-# Geral - Como Fazer - Receitas
+# Geral - Como Fazer - Receitas { #general-how-to-recipes }
Aqui estão vários links para outros locais na documentação, para perguntas gerais ou frequentes
-## Filtro de dados- Segurança
+## Filtro de dados- Segurança { #filter-data-security }
-Para assegurar que você não vai retornar mais dados do que deveria, leia a seção [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank}.
+Para assegurar que você não vai retornar mais dados do que deveria, leia a seção [Tutorial - Modelo de Resposta - Tipo de Retorno](../tutorial/response-model.md){.internal-link target=_blank}.
-## Tags de Documentação - OpenAPI
-Para adicionar tags às suas *rotas* e agrupá-las na UI da documentação, leia a seção [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
+## Tags de Documentação - OpenAPI { #documentation-tags-openapi }
+Para adicionar tags às suas *operações de rota* e agrupá-las na UI da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
-## Resumo e Descrição da documentação - OpenAPI
+## Resumo e Descrição da documentação - OpenAPI { #documentation-summary-and-description-openapi }
-Para adicionar um resumo e uma descrição às suas *rotas* e exibi-los na UI da documentação, leia a seção [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
+Para adicionar um resumo e uma descrição às suas *operações de rota* e exibi-los na UI da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Resumo e Descrição](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
-## Documentação das Descrições de Resposta - OpenAPI
+## Documentação das Descrições de Resposta - OpenAPI { #documentation-response-description-openapi }
-Para definir a descrição de uma resposta exibida na interface da documentação, leia a seção [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
+Para definir a descrição de uma resposta exibida na interface da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Descrição da Resposta](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
-## Documentação para Depreciar uma *Operação de Rota* - OpenAPI
+## Documentação para Depreciar uma *Operação de Rota* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
-Para depreciar uma *operação de rota* e exibi-la na interface da documentação, leia a seção [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
+Para depreciar uma *operação de rota* e exibi-la na interface da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Depreciação](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
-## Converter qualquer dado para JSON
+## Converter qualquer dado para compatível com JSON { #convert-any-data-to-json-compatible }
+Para converter qualquer dado para um formato compatível com JSON, leia a seção [Tutorial - Codificador Compatível com JSON](../tutorial/encoder.md){.internal-link target=_blank}.
-Para converter qualquer dado para um formato compatível com JSON, leia a seção [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
+## OpenAPI Metadata - Docs { #openapi-metadata-docs }
-## OpenAPI Metadata - Docs
+Para adicionar metadados ao seu esquema OpenAPI, incluindo licensa, versão, contato, etc, leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md){.internal-link target=_blank}.
-Para adicionar metadados ao seu esquema OpenAPI, incluindo licensa, versão, contato, etc, leia a seção [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank}.
+## OpenAPI com URL customizada { #openapi-custom-url }
-## OpenAPI com URL customizada
+Para customizar a URL do OpenAPI (ou removê-la), leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
-Para customizar a URL do OpenAPI (ou removê-la), leia a seção [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
+## URLs de documentação do OpenAPI { #openapi-docs-urls }
-## URLs de documentação do OpenAPI
-
-Para alterar as URLs usadas para as interfaces de usuário da documentação gerada automaticamente, leia a seção [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
+Para alterar as URLs usadas para as interfaces de usuário da documentação gerada automaticamente, leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
diff --git a/docs/pt/docs/how-to/graphql.md b/docs/pt/docs/how-to/graphql.md
index ef0bad7f6..98266cc28 100644
--- a/docs/pt/docs/how-to/graphql.md
+++ b/docs/pt/docs/how-to/graphql.md
@@ -1,4 +1,4 @@
-# GraphQL
+# GraphQL { #graphql }
Como o **FastAPI** é baseado no padrão **ASGI**, é muito fácil integrar qualquer biblioteca **GraphQL** também compatível com ASGI.
@@ -14,7 +14,7 @@ Certifique-se de avaliar se os **benefícios** para o seu caso de uso compensam
///
-## Bibliotecas GraphQL
+## Bibliotecas GraphQL { #graphql-libraries }
Aqui estão algumas das bibliotecas **GraphQL** que têm suporte **ASGI**. Você pode usá-las com **FastAPI**:
@@ -27,21 +27,21 @@ Aqui estão algumas das bibliotecas **GraphQL** que têm suporte **ASGI**. Você
* Graphene
* Com starlette-graphene3
-## GraphQL com Strawberry
+## GraphQL com Strawberry { #graphql-with-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**.
+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 **anotações de tipo**.
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] *}
+{* ../../docs_src/graphql_/tutorial001_py39.py hl[3,22,25] *}
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
+## Antigo `GraphQLApp` do Starlette { #older-graphqlapp-from-starlette }
Versões anteriores do Starlette incluiam uma classe `GraphQLApp` para integrar com Graphene.
@@ -49,11 +49,11 @@ Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, vo
/// 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.
+Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no Strawberry, pois ele é baseado em anotações de tipo em vez de classes e tipos personalizados.
///
-## Saiba Mais
+## Saiba Mais { #learn-more }
Você pode aprender mais sobre **GraphQL** na documentação oficial do GraphQL.
diff --git a/docs/pt/docs/how-to/index.md b/docs/pt/docs/how-to/index.md
index 6747b01c7..a3d16380f 100644
--- a/docs/pt/docs/how-to/index.md
+++ b/docs/pt/docs/how-to/index.md
@@ -1,12 +1,12 @@
-# Como Fazer - Exemplos Práticos
+# Como Fazer - Receitas { #how-to-recipes }
-Aqui você encontrará diferentes exemplos práticos ou tutoriais de "como fazer" para vários tópicos.
+Aqui você encontrará diferentes exemplos práticos ou tutoriais de "como fazer" para **vários tópicos**.
A maioria dessas ideias será mais ou menos **independente**, e na maioria dos casos você só precisará estudá-las se elas se aplicarem diretamente ao **seu projeto**.
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 | Dica
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/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
new file mode 100644
index 000000000..0995e1028
--- /dev/null
+++ b/docs/pt/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
@@ -0,0 +1,135 @@
+# Migrar do Pydantic v1 para o Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }
+
+Se você tem uma aplicação FastAPI antiga, pode estar usando o Pydantic versão 1.
+
+O FastAPI versão 0.100.0 tinha suporte ao Pydantic v1 ou v2. Ele usaria aquele que você tivesse instalado.
+
+O FastAPI versão 0.119.0 introduziu suporte parcial ao Pydantic v1 a partir de dentro do Pydantic v2 (como `pydantic.v1`), para facilitar a migração para o v2.
+
+O FastAPI 0.126.0 removeu o suporte ao Pydantic v1, enquanto ainda oferece suporte a `pydantic.v1` por mais algum tempo.
+
+/// warning | Atenção
+
+A equipe do Pydantic interrompeu o suporte ao Pydantic v1 para as versões mais recentes do Python, a partir do **Python 3.14**.
+
+Isso inclui `pydantic.v1`, que não é mais suportado no Python 3.14 e superiores.
+
+Se quiser usar as funcionalidades mais recentes do Python, você precisará garantir que usa o Pydantic v2.
+
+///
+
+Se você tem uma aplicação FastAPI antiga com Pydantic v1, aqui vou mostrar como migrá-la para o Pydantic v2, e as **funcionalidades no FastAPI 0.119.0** para ajudar em uma migração gradual.
+
+## Guia oficial { #official-guide }
+
+O Pydantic tem um Guia de Migração oficial do v1 para o v2.
+
+Ele também inclui o que mudou, como as validações agora são mais corretas e rigorosas, possíveis ressalvas, etc.
+
+Você pode lê-lo para entender melhor o que mudou.
+
+## Testes { #tests }
+
+Garanta que você tenha [testes](../tutorial/testing.md){.internal-link target=_blank} para sua aplicação e que os execute na integração contínua (CI).
+
+Assim, você pode fazer a atualização e garantir que tudo continua funcionando como esperado.
+
+## `bump-pydantic` { #bump-pydantic }
+
+Em muitos casos, quando você usa modelos Pydantic regulares sem personalizações, será possível automatizar a maior parte do processo de migração do Pydantic v1 para o Pydantic v2.
+
+Você pode usar o `bump-pydantic` da própria equipe do Pydantic.
+
+Essa ferramenta ajuda a alterar automaticamente a maior parte do código que precisa ser modificado.
+
+Depois disso, você pode rodar os testes e verificar se tudo funciona. Se funcionar, está concluído. 😎
+
+## Pydantic v1 no v2 { #pydantic-v1-in-v2 }
+
+O Pydantic v2 inclui tudo do Pydantic v1 como um submódulo `pydantic.v1`. Mas isso não é mais suportado em versões acima do Python 3.13.
+
+Isso significa que você pode instalar a versão mais recente do Pydantic v2 e importar e usar os componentes antigos do Pydantic v1 a partir desse submódulo, como se tivesse o Pydantic v1 antigo instalado.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *}
+
+### Suporte do FastAPI ao Pydantic v1 no v2 { #fastapi-support-for-pydantic-v1-in-v2 }
+
+Desde o FastAPI 0.119.0, há também suporte parcial ao Pydantic v1 a partir de dentro do Pydantic v2, para facilitar a migração para o v2.
+
+Assim, você pode atualizar o Pydantic para a versão 2 mais recente e alterar os imports para usar o submódulo `pydantic.v1`, e em muitos casos tudo simplesmente funcionará.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *}
+
+/// warning | Atenção
+
+Tenha em mente que, como a equipe do Pydantic não oferece mais suporte ao Pydantic v1 nas versões recentes do Python, a partir do Python 3.14, o uso de `pydantic.v1` também não é suportado no Python 3.14 e superiores.
+
+///
+
+### Pydantic v1 e v2 na mesma aplicação { #pydantic-v1-and-v2-on-the-same-app }
+
+Não é **suportado** pelo Pydantic ter um modelo do Pydantic v2 com campos próprios definidos como modelos do Pydantic v1, ou vice-versa.
+
+```mermaid
+graph TB
+ subgraph "❌ Not Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+...mas, você pode ter modelos separados usando Pydantic v1 e v2 na mesma aplicação.
+
+```mermaid
+graph TB
+ subgraph "✅ Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+Em alguns casos, é até possível ter modelos Pydantic v1 e v2 na mesma **operação de rota** na sua aplicação FastAPI:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *}
+
+No exemplo acima, o modelo de entrada é um modelo Pydantic v1, e o modelo de saída (definido em `response_model=ItemV2`) é um modelo Pydantic v2.
+
+### Parâmetros do Pydantic v1 { #pydantic-v1-parameters }
+
+Se você precisar usar algumas das ferramentas específicas do FastAPI para parâmetros como `Body`, `Query`, `Form` etc. com modelos do Pydantic v1, pode importá-las de `fastapi.temp_pydantic_v1_params` enquanto conclui a migração para o Pydantic v2:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *}
+
+### Migre em etapas { #migrate-in-steps }
+
+/// tip | Dica
+
+Primeiro tente com o `bump-pydantic`, se seus testes passarem e isso funcionar, então você concluiu tudo com um único comando. ✨
+
+///
+
+Se o `bump-pydantic` não funcionar para o seu caso, você pode usar o suporte a modelos Pydantic v1 e v2 na mesma aplicação para fazer a migração para o Pydantic v2 gradualmente.
+
+Você poderia primeiro atualizar o Pydantic para usar a versão 2 mais recente e alterar os imports para usar `pydantic.v1` para todos os seus modelos.
+
+Depois, você pode começar a migrar seus modelos do Pydantic v1 para o v2 em grupos, em etapas graduais. 🚶
diff --git a/docs/pt/docs/how-to/separate-openapi-schemas.md b/docs/pt/docs/how-to/separate-openapi-schemas.md
index 291b0e163..f757025a0 100644
--- a/docs/pt/docs/how-to/separate-openapi-schemas.md
+++ b/docs/pt/docs/how-to/separate-openapi-schemas.md
@@ -1,26 +1,26 @@
-# Esquemas OpenAPI Separados para Entrada e Saída ou Não
+# Esquemas OpenAPI Separados para Entrada e Saída ou Não { #separate-openapi-schemas-for-input-and-output-or-not }
-Ao usar **Pydantic v2**, o OpenAPI gerado é um pouco mais exato e **correto** do que antes. 😎
+Desde que o **Pydantic v2** foi lançado, 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**.
+De fato, 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
+## Modelos Pydantic para Entrada e Saída { #pydantic-models-for-input-and-output }
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
+### Modelo para Entrada { #model-for-input }
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`.
+... 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
+### Modelo de Entrada na Documentação { #input-model-in-docs }
Você pode confirmar que na documentação, o campo `description` não tem um **asterisco vermelho**, não é marcado como obrigatório:
@@ -28,7 +28,7 @@ Você pode confirmar que na documentação, o campo `description` não tem um **
-
+
Framework FastAPI, alta performance, fácil de aprender, fácil de codar, pronto para produção
@@ -27,7 +27,7 @@
---
-**Documentação**: https://fastapi.tiangolo.com
+**Documentação**: https://fastapi.tiangolo.com
**Código fonte**: https://github.com/fastapi/fastapi
@@ -40,34 +40,40 @@ Os recursos chave são:
* **Rápido**: alta performance, equivalente a **NodeJS** e **Go** (graças ao Starlette e Pydantic). [Um dos frameworks mais rápidos disponíveis](#performance).
* **Rápido para codar**: Aumenta a velocidade para desenvolver recursos entre 200% a 300%. *
* **Poucos bugs**: Reduz cerca de 40% de erros induzidos por humanos (desenvolvedores). *
-* **Intuitivo**: Grande suporte a _IDEs_. _Auto-Complete_ em todos os lugares. Menos tempo debugando.
-* **Fácil**: Projetado para ser fácil de aprender e usar. Menos tempo lendo documentação.
-* **Enxuto**: Minimize duplicação de código. Múltiplos recursos para cada declaração de parâmetro. Menos bugs.
+* **Intuitivo**: Grande suporte a editores. Completação em todos os lugares. Menos tempo debugando.
+* **Fácil**: Projetado para ser fácil de aprender e usar. Menos tempo lendo docs.
+* **Enxuto**: Minimize duplicação de código. Múltiplas funcionalidades para cada declaração de parâmetro. Menos bugs.
* **Robusto**: Tenha código pronto para produção. E com documentação interativa automática.
-* **Baseado em padrões**: Baseado em (e totalmente compatível com) os padrões abertos para APIs: OpenAPI (anteriormente conhecido como Swagger) e _JSON Schema_.
+* **Baseado em padrões**: Baseado em (e totalmente compatível com) os padrões abertos para APIs: OpenAPI (anteriormente conhecido como Swagger) e JSON Schema.
* estimativas baseadas em testes realizados com equipe interna de desenvolvimento, construindo aplicações em produção.
-## Patrocinadores Ouro
+## Patrocinadores { #sponsors }
-{% if sponsors %}
+### Patrocinador Keystone { #keystone-sponsor }
+
+{% for sponsor in sponsors.keystone -%}
+
+{% endfor -%}
+
+### Patrocinadores Ouro e Prata { #gold-and-silver-sponsors }
+
{% for sponsor in sponsors.gold -%}
{% endfor -%}
{%- for sponsor in sponsors.silver -%}
{% endfor %}
-{% endif %}
-Outros patrocinadores
+Outros patrocinadores
-## Opiniões
+## Opiniões { #opinions }
-"*[...] Estou usando **FastAPI** muito esses dias. [...] Estou na verdade planejando utilizar ele em todos os times de **serviços _Machine Learning_ na Microsoft**. Alguns deles estão sendo integrados no _core_ do produto **Windows** e alguns produtos **Office**.*"
+"_[...] Estou usando **FastAPI** muito esses dias. [...] Estou na verdade planejando utilizar ele em todos os times de **serviços ML na Microsoft**. Alguns deles estão sendo integrados no _core_ do produto **Windows** e alguns produtos **Office**._"
+
+## **Typer**, o FastAPI das interfaces de linhas de comando { #typer-the-fastapi-of-clis }
-Se você estiver construindo uma aplicação _CLI_ para ser utilizada em um terminal ao invés de uma aplicação web, dê uma olhada no **Typer**.
+Se você estiver construindo uma aplicação CLI para ser utilizada no terminal ao invés de uma API web, dê uma olhada no **Typer**.
-**Typer** é o irmão menor do FastAPI. E seu propósito é ser o **FastAPI das _CLIs_**. ⌨️ 🚀
+**Typer** é o irmão menor do FastAPI. E seu propósito é ser o **FastAPI das CLIs**. ⌨️ 🚀
-## Requisitos
+## Requisitos { #requirements }
FastAPI está nos ombros de gigantes:
-* Starlette para as partes web.
+* Starlette para as partes web.
* Pydantic para a parte de dados.
-## Instalação
+## Instalação { #installation }
-Crie e ative um ambiente virtual, e então instale o FastAPI:
+Crie e ative um ambiente virtual e então instale o FastAPI:
fastapi dev main.py...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()`.
+* python-multipart - Obrigatório se você deseja suporte a "parsing" de formulário, com `request.form()`.
-Utilizado pelo FastAPI / Starlette:
+Utilizado pelo FastAPI:
-* 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`.
+* 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[standard]` - que disponibiliza o comando `fastapi`.
+ * Isso inclui `fastapi-cloud-cli`, que permite implantar sua aplicação FastAPI na FastAPI Cloud.
-### Sem as dependências `standard`
+### Sem as dependências `standard` { #without-standard-dependencies }
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
+### Sem o `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
+
+Se você quiser instalar o FastAPI com as dependências padrão, mas sem o `fastapi-cloud-cli`, você pode instalar com `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
+
+### Dependências opcionais adicionais { #additional-optional-dependencies }
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.
+* pydantic-extra-types - para tipos extras a 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
+## Licença { #license }
Esse projeto é licenciado sob os termos da licença MIT.
diff --git a/docs/pt/docs/learn/index.md b/docs/pt/docs/learn/index.md
index b9a7f5972..1f04929f7 100644
--- a/docs/pt/docs/learn/index.md
+++ b/docs/pt/docs/learn/index.md
@@ -1,5 +1,5 @@
-# Aprender
+# Aprender { #learn }
-Nesta parte da documentação encontramos as seções introdutórias e os tutoriais para aprendermos como usar o **FastAPI**.
+Aqui estão as seções introdutórias e os tutoriais para aprender o **FastAPI**.
-Nós poderíamos considerar isto um **livro**, **curso**, a maneira **oficial** e recomendada de aprender o FastAPI. 😎
+Pode considerar isto um **livro**, um **curso**, a forma **oficial** e recomendada de aprender o FastAPI. 😎
diff --git a/docs/pt/docs/project-generation.md b/docs/pt/docs/project-generation.md
index e337ad762..419a39879 100644
--- a/docs/pt/docs/project-generation.md
+++ b/docs/pt/docs/project-generation.md
@@ -1,4 +1,4 @@
-# Full Stack FastAPI Template
+# Full Stack FastAPI Template { #full-stack-fastapi-template }
_Templates_, embora tipicamente venham com alguma configuração específica, são desenhados para serem flexíveis e customizáveis. Isso permite que você os modifique e adapte para as especificações do seu projeto, fazendo-os um excelente ponto de partida. 🏁
@@ -6,15 +6,15 @@ Você pode usar esse _template_ para começar, já que ele inclui várias config
Repositório GitHub: Full Stack FastAPI Template
-## Full Stack FastAPI Template - Pilha de Tecnologias e Recursos
+## Full Stack FastAPI Template - Pilha de Tecnologias e Recursos { #full-stack-fastapi-template-technology-stack-and-features }
-- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) para a API do backend em Python.
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/pt) para a API do backend em Python.
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com) para as interações do Python com bancos de dados SQL (ORM).
- 🔍 [Pydantic](https://docs.pydantic.dev), usado pelo FastAPI, para validação de dados e gerenciamento de configurações.
- 💾 [PostgreSQL](https://www.postgresql.org) como banco de dados SQL.
- 🚀 [React](https://react.dev) para o frontend.
- - 💃 Usando TypeScript, hooks, [Vite](https://vitejs.dev), e outras partes de uma _stack_ frontend moderna.
- - 🎨 [Chakra UI](https://chakra-ui.com) para os componentes de frontend.
+ - 💃 Usando TypeScript, hooks, Vite, e outras partes de uma _stack_ frontend moderna.
+ - 🎨 [Tailwind CSS](https://tailwindcss.com) e [shadcn/ui](https://ui.shadcn.com) para os componentes de frontend.
- 🤖 Um cliente frontend automaticamente gerado.
- 🧪 [Playwright](https://playwright.dev) para testes Ponta-a-Ponta.
- 🦇 Suporte para modo escuro.
diff --git a/docs/pt/docs/python-types.md b/docs/pt/docs/python-types.md
index 90a361f40..fc983d1df 100644
--- a/docs/pt/docs/python-types.md
+++ b/docs/pt/docs/python-types.md
@@ -1,4 +1,4 @@
-# Introdução aos tipos Python
+# Introdução aos tipos Python { #python-types-intro }
O Python possui suporte para "dicas de tipo" ou "type hints" (também chamado de "anotações de tipo" ou "type annotations")
@@ -18,11 +18,11 @@ Se você é um especialista em Python e já sabe tudo sobre type hints, pule par
///
-## Motivação
+## Motivação { #motivation }
Vamos começar com um exemplo simples:
-{* ../../docs_src/python_types/tutorial001.py *}
+{* ../../docs_src/python_types/tutorial001_py39.py *}
A chamada deste programa gera:
@@ -36,9 +36,9 @@ A função faz o seguinte:
* Converte a primeira letra de cada uma em maiúsculas com `title()`.
* Concatena com um espaço no meio.
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
-### Edite-o
+### Edite-o { #edit-it }
É um programa muito simples.
@@ -58,7 +58,7 @@ Mas, infelizmente, você não obtém nada útil:
-### Adicionar tipos
+### Adicionar tipos { #add-types }
Vamos modificar uma única linha da versão anterior.
@@ -78,7 +78,7 @@ para:
Esses são os "type hints":
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
Isso não é o mesmo que declarar valores padrão como seria com:
@@ -102,11 +102,11 @@ Com isso, você pode rolar, vendo as opções, até encontrar o que "soa familia
-## Mais motivação
+## Mais motivação { #more-motivation }
Verifique esta função, ela já possui type hints:
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
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:
@@ -114,15 +114,15 @@ Como o editor conhece os tipos de variáveis, você não obtém apenas o preench
Agora você sabe que precisa corrigí-lo, converta `age` em uma string com `str(age)`:
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
-## Declarando Tipos
+## Declarando Tipos { #declaring-types }
Você acabou de ver o local principal para declarar type hints. Como parâmetros de função.
Este também é o principal local em que você os usaria com o **FastAPI**.
-### Tipos simples
+### Tipos simples { #simple-types }
Você pode declarar todos os tipos padrão de Python, não apenas `str`.
@@ -133,9 +133,9 @@ Você pode usar, por exemplo:
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
-### Tipos genéricos com parâmetros de tipo
+### Tipos genéricos com parâmetros de tipo { #generic-types-with-type-parameters }
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.
@@ -143,7 +143,7 @@ Estes tipos que possuem tipos internos são chamados de tipos "**genéricos**".
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.
-#### Versões mais recentes do Python
+#### Versões mais recentes do Python { #newer-versions-of-python }
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.
@@ -157,60 +157,28 @@ Por exemplo, "**Python 3.6+**" significa que é compatível com o Python 3.6 ou
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
+#### List { #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_py39.py!}
-```
-
-////
+Declare a variável, com a mesma sintaxe com dois pontos (`:`).
-//// tab | Python 3.8+
+Como o tipo, coloque `list`.
-De `typing`, importe `List` (com o `L` maiúsculo):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
+Como a lista é um tipo que contém tipos internos, você os coloca entre colchetes:
-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_py39.py hl[1] *}
/// info | Informação
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).
+Neste caso, `str` é o parâmetro de tipo passado para `list`.
///
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:
@@ -221,32 +189,18 @@ 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 { #tuple-and-set }
Você faria o mesmo para declarar `tuple`s e `set`s:
-//// 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
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 { #dict }
Para definir um `dict`, você passa 2 parâmetros de tipo, separados por vírgulas.
@@ -254,35 +208,21 @@ O primeiro parâmetro de tipo é para as chaves do `dict`.
O segundo parâmetro de tipo é para os valores do `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_py39.py hl[1] *}
Isso significa que:
-* A variável `prices` é um dict`:
+* 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).
-#### Union
+#### Union { #union }
Você pode declarar que uma variável pode ser de qualquer um dentre **diversos tipos**. Por exemplo, um `int` ou um `str`.
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 (`|`).
+No Python 3.10 também existe uma **nova sintaxe** onde você pode colocar os possíveis tipos separados por uma barra vertical (`|`).
//// tab | Python 3.10+
@@ -292,25 +232,24 @@ No Python 3.10 também existe uma **nova sintaxe** onde você pode colocar os po
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
```
////
Em ambos os casos, isso significa que `item` poderia ser um `int` ou um `str`.
-
-#### Possívelmente `None`
+#### Possivelmente `None` { #possibly-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!}
+{!../../docs_src/python_types/tutorial009_py39.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`.
@@ -327,23 +266,23 @@ Isso também significa que no Python 3.10, você pode utilizar `Something | None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
////
-//// tab | Python 3.8+ alternative
+//// tab | Python 3.9+ alternativa
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
```
////
-#### Utilizando `Union` ou `Optional`
+#### Utilizando `Union` ou `Optional` { #using-union-or-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**:
@@ -358,15 +297,15 @@ Isso é apenas sobre palavras e nomes. Mas estas palavras podem afetar como os s
Por exemplo, vamos pegar esta função:
-{* ../../docs_src/python_types/tutorial009c.py hl[1,4] *}
+{* ../../docs_src/python_types/tutorial009c_py39.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:
+O parâ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:
+O parâmetro `name` **ainda é obrigatório** (não *opcional*) 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 🎉
@@ -378,7 +317,7 @@ A boa notícia é, quando você estiver no Python 3.10 você não precisará se
E então você não precisará mais se preocupar com nomes como `Optional` e `Union`. 😎
-#### Tipos genéricos
+#### Tipos genéricos { #generic-types }
Esses tipos que usam parâmetros de tipo entre colchetes são chamados **tipos genéricos** ou **genéricos**. Por exemplo:
@@ -391,11 +330,11 @@ Você pode utilizar os mesmos tipos internos como genéricos (com colchetes e ti
* `set`
* `dict`
-E o mesmo como no Python 3.8, do módulo `typing`:
+E o mesmo que com versões anteriores do Python, do módulo `typing`:
* `Union`
-* `Optional` (o mesmo que com o 3.8)
-* ...entro outros.
+* `Optional`
+* ...entre 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.
@@ -410,39 +349,27 @@ Você pode utilizar os mesmos tipos internos como genéricos (com colchetes e ti
* `set`
* `dict`
-E o mesmo como no Python 3.8, do módulo `typing`:
-
-* `Union`
-* `Optional`
-* ...entro outros.
-
-////
-
-//// tab | Python 3.8+
+E genéricos do módulo `typing`:
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
* `Union`
* `Optional`
-* ...entro outros.
+* ...entre outros.
////
-### Classes como tipos
+### Classes como tipos { #classes-as-types }
Você também pode declarar uma classe como o tipo de uma variável.
Digamos que você tenha uma classe `Person`, com um nome:
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
Então você pode declarar que uma variável é do tipo `Person`:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
-E então, novamente, você recebe todo o suporte do editor:
+E então, novamente, você recebe todo o apoio do editor:
@@ -450,7 +377,7 @@ Perceba que isso significa que "`one_person` é uma **instância** da classe `Pe
Isso não significa que "`one_person` é a **classe** chamada `Person`".
-## Modelos Pydantic
+## Modelos Pydantic { #pydantic-models }
O Pydantic é uma biblioteca Python para executar a validação de dados.
@@ -462,31 +389,9 @@ Em seguida, você cria uma instância dessa classe com alguns valores e ela os v
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_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!}
-```
+Um exemplo da documentação oficial do Pydantic:
-////
+{* ../../docs_src/python_types/tutorial011_py310.py *}
/// info | Informação
@@ -504,32 +409,13 @@ O Pydantic tem um comportamento especial quando você usa `Optional` ou `Union[S
///
-
-## Type Hints com Metadados de Anotações
+## Type Hints com Metadados de Anotações { #type-hints-with-metadata-annotations }
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`.
+Desde o Python 3.9, `Annotated` faz 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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
O Python em si não faz nada com este `Annotated`. E para editores e outras ferramentas, o tipo ainda é `str`.
@@ -549,8 +435,7 @@ E também que o seu código será muito compatível com diversas outras ferramen
///
-
-## Type hints no **FastAPI**
+## Type hints no **FastAPI** { #type-hints-in-fastapi }
O **FastAPI** aproveita esses type hints para fazer várias coisas.
@@ -574,6 +459,6 @@ O importante é que, usando tipos padrão de Python, em um único local (em vez
/// info | Informação
-Se você já passou por todo o tutorial e voltou para ver mais sobre os tipos, um bom recurso é a "cheat sheet" do `mypy` .
+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/resources/index.md b/docs/pt/docs/resources/index.md
index 6eff8f9e7..24cea9564 100644
--- a/docs/pt/docs/resources/index.md
+++ b/docs/pt/docs/resources/index.md
@@ -1,3 +1,3 @@
-# Recursos
+# Recursos { #resources }
-Material complementar, links externos, artigos e muito mais. ✈️
+Material complementar, links externos e mais. ✈️
diff --git a/docs/pt/docs/tutorial/background-tasks.md b/docs/pt/docs/tutorial/background-tasks.md
index 0f3796371..34805364b 100644
--- a/docs/pt/docs/tutorial/background-tasks.md
+++ b/docs/pt/docs/tutorial/background-tasks.md
@@ -1,84 +1,85 @@
-# Tarefas em segundo plano
+# Tarefas em segundo plano { #background-tasks }
-Você pode definir tarefas em segundo plano a serem executadas _ após _ retornar uma resposta.
+Você pode definir tarefas em segundo plano para serem executadas *após* retornar uma resposta.
-Isso é útil para operações que precisam acontecer após uma solicitação, mas que o cliente realmente não precisa esperar a operação ser concluída para receber a resposta.
+Isso é útil para operações que precisam acontecer após uma request, mas que o cliente não precisa realmente esperar a operação terminar antes de receber a resposta.
Isso inclui, por exemplo:
-- Envio de notificações por email após a realização de uma ação:
- - Como conectar-se a um servidor de e-mail e enviar um e-mail tende a ser "lento" (vários segundos), você pode retornar a resposta imediatamente e enviar a notificação por e-mail em segundo plano.
-- Processando dados:
- - Por exemplo, digamos que você receba um arquivo que deve passar por um processo lento, você pode retornar uma resposta de "Aceito" (HTTP 202) e processá-lo em segundo plano.
+* Notificações por e-mail enviadas após realizar uma ação:
+ * Como conectar-se a um servidor de e-mail e enviar um e-mail tende a ser “lento” (vários segundos), você pode retornar a resposta imediatamente e enviar a notificação por e-mail em segundo plano.
+* Processamento de dados:
+ * Por exemplo, digamos que você receba um arquivo que precisa passar por um processo lento; você pode retornar uma resposta “Accepted” (HTTP 202) e processar o arquivo em segundo plano.
-## Usando `BackgroundTasks`
+## Usando `BackgroundTasks` { #using-backgroundtasks }
-Primeiro, importe `BackgroundTasks` e defina um parâmetro em sua _função de operação de caminho_ com uma declaração de tipo de `BackgroundTasks`:
+Primeiro, importe `BackgroundTasks` e defina um parâmetro na sua *função de operação de rota* com uma declaração de tipo `BackgroundTasks`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
O **FastAPI** criará o objeto do tipo `BackgroundTasks` para você e o passará como esse parâmetro.
-## Criar uma função de tarefa
+## Crie uma função de tarefa { #create-a-task-function }
-Crie uma função a ser executada como tarefa em segundo plano.
+Crie uma função para ser executada como a tarefa em segundo plano.
É apenas uma função padrão que pode receber parâmetros.
-Pode ser uma função `async def` ou `def` normal, o **FastAPI** saberá como lidar com isso corretamente.
+Pode ser uma função `async def` ou um `def` normal, o **FastAPI** saberá como lidar com isso corretamente.
-Nesse caso, a função de tarefa gravará em um arquivo (simulando o envio de um e-mail).
+Neste caso, a função da tarefa escreverá em um arquivo (simulando o envio de um e-mail).
-E como a operação de gravação não usa `async` e `await`, definimos a função com `def` normal:
+E como a operação de escrita não usa `async` e `await`, definimos a função com um `def` normal:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
-## Adicionar a tarefa em segundo plano
+## Adicione a tarefa em segundo plano { #add-the-background-task }
-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()`:
+Dentro da sua *função de operação de rota*, passe sua função de tarefa para o objeto de *tarefas em segundo plano* com o método `.add_task()`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
-`.add_task()` recebe como argumentos:
+O `.add_task()` recebe como argumentos:
-- Uma função de tarefa a ser executada em segundo plano (`write_notification`).
-- Qualquer sequência de argumentos que deve ser passada para a função de tarefa na ordem (`email`).
-- Quaisquer argumentos nomeados que devem ser passados para a função de tarefa (`mensagem = "alguma notificação"`).
+* Uma função de tarefa a ser executada em segundo plano (`write_notification`).
+* Qualquer sequência de argumentos que deve ser passada para a função de tarefa na ordem (`email`).
+* Quaisquer argumentos nomeados que devem ser passados para a função de tarefa (`message="some notification"`).
-## Injeção de dependência
+## Injeção de dependências { #dependency-injection }
-Usar `BackgroundTasks` também funciona com o sistema de injeção de dependência, você pode declarar um parâmetro do tipo `BackgroundTasks` em vários níveis: em uma _função de operação de caminho_, em uma dependência (confiável), em uma subdependência, etc.
+Usar `BackgroundTasks` também funciona com o sistema de injeção de dependências; você pode declarar um parâmetro do tipo `BackgroundTasks` em vários níveis: em uma *função de operação de rota*, em uma dependência (dependable), em uma subdependência, etc.
-O **FastAPI** sabe o que fazer em cada caso e como reutilizar o mesmo objeto, de forma que todas as tarefas em segundo plano sejam mescladas e executadas em segundo plano posteriormente:
+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 combinadas e executadas em segundo plano depois:
-{* ../../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.
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
-Se houver uma consulta na solicitação, ela será gravada no log em uma tarefa em segundo plano.
+Neste exemplo, as mensagens serão escritas no arquivo `log.txt` *após* o envio da resposta.
-E então outra tarefa em segundo plano gerada na _função de operação de caminho_ escreverá uma mensagem usando o parâmetro de caminho `email`.
+Se houver uma query na request, ela será registrada em uma tarefa em segundo plano.
-## Detalhes técnicos
+E então outra tarefa em segundo plano gerada na *função de operação de rota* escreverá uma mensagem usando o parâmetro de path `email`.
-A classe `BackgroundTasks` vem diretamente de `starlette.background`.
+## Detalhes técnicos { #technical-details }
-Ela é importada/incluída diretamente no FastAPI para que você possa importá-la do `fastapi` e evitar a importação acidental da alternativa `BackgroundTask` (sem o `s` no final) de `starlette.background`.
+A classe `BackgroundTasks` vem diretamente de `starlette.background`.
-Usando apenas `BackgroundTasks` (e não `BackgroundTask`), é então possível usá-la como um parâmetro de _função de operação de caminho_ e deixar o **FastAPI** cuidar do resto para você, assim como ao usar o objeto `Request` diretamente.
+Ela é importada/incluída diretamente no FastAPI para que você possa importá-la de `fastapi` e evitar importar acidentalmente a alternativa `BackgroundTask` (sem o `s` no final) de `starlette.background`.
-Ainda é possível usar `BackgroundTask` sozinho no FastAPI, mas você deve criar o objeto em seu código e retornar uma Starlette `Response` incluindo-o.
+Usando apenas `BackgroundTasks` (e não `BackgroundTask`), é possível usá-la como um parâmetro de *função de operação de rota* e deixar o **FastAPI** cuidar do resto para você, assim como ao usar o objeto `Request` diretamente.
-Você pode ver mais detalhes na documentação oficiais da Starlette para tarefas em segundo plano .
+Ainda é possível usar `BackgroundTask` sozinho no FastAPI, mas você precisa criar o objeto no seu código e retornar uma `Response` da Starlette incluindo-o.
-## Ressalva
+Você pode ver mais detalhes na documentação oficial da Starlette para tarefas em segundo plano.
-Se você precisa realizar cálculos pesados em segundo plano e não necessariamente precisa que seja executado pelo mesmo processo (por exemplo, você não precisa compartilhar memória, variáveis, etc), você pode se beneficiar do uso de outras ferramentas maiores, como Celery .
+## Ressalva { #caveat }
-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.
+Se você precisar realizar computação pesada em segundo plano e não necessariamente precisar que seja executada pelo mesmo processo (por exemplo, você não precisa compartilhar memória, variáveis, etc.), pode se beneficiar do uso de outras ferramentas maiores, como o Celery.
-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`.
+Elas tendem a exigir configurações mais complexas, um gerenciador de fila de mensagens/tarefas, como RabbitMQ ou Redis, mas permitem executar tarefas em segundo plano em vários processos e, especialmente, em vários servidores.
-## Recapitulando
+Mas se você precisa acessar variáveis e objetos da mesma aplicação **FastAPI**, ou precisa realizar pequenas tarefas em segundo plano (como enviar uma notificação por e-mail), você pode simplesmente usar `BackgroundTasks`.
-Importe e use `BackgroundTasks` com parâmetros em _funções de operação de caminho_ e dependências para adicionar tarefas em segundo plano.
+## Recapitulando { #recap }
+
+Importe e use `BackgroundTasks` com parâmetros em *funções de operação de rota* e dependências para adicionar tarefas em segundo plano.
diff --git a/docs/pt/docs/tutorial/bigger-applications.md b/docs/pt/docs/tutorial/bigger-applications.md
index b621f3c72..87bd13375 100644
--- a/docs/pt/docs/tutorial/bigger-applications.md
+++ b/docs/pt/docs/tutorial/bigger-applications.md
@@ -1,4 +1,4 @@
-# Aplicações Maiores - Múltiplos Arquivos
+# Aplicações Maiores - Múltiplos Arquivos { #bigger-applications-multiple-files }
Se você está construindo uma aplicação ou uma API web, é raro que você possa colocar tudo em um único arquivo.
@@ -10,7 +10,7 @@ Se você vem do Flask, isso seria o equivalente aos Blueprints do Flask.
///
-## Um exemplo de estrutura de arquivos
+## Um exemplo de estrutura de arquivos { #an-example-file-structure }
Digamos que você tenha uma estrutura de arquivos como esta:
@@ -31,7 +31,7 @@ Digamos que você tenha uma estrutura de arquivos como esta:
/// tip | Dica
-Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório.
+Existem vários arquivos `__init__.py`: um em cada diretório ou subdiretório.
Isso permite a importação de código de um arquivo para outro.
@@ -43,35 +43,35 @@ 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`.
+* O diretório `app` contém tudo. E possui um arquivo vazio `app/__init__.py`, então ele é um "pacote Python" (uma coleção de "módulos Python"): `app`.
+* Ele contém um arquivo `app/main.py`. Como está dentro de um pacote Python (um diretório com um arquivo `__init__.py`), ele é um "módulo" desse pacote: `app.main`.
+* Existe também um arquivo `app/dependencies.py`, assim como `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`.
+* 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`.
A mesma estrutura de arquivos com comentários:
-```
+```bash
.
-├── app # "app" é um pacote Python
-│ ├── __init__.py # este arquivo torna "app" um "pacote Python"
-│ ├── main.py # "main" módulo, e.g. import app.main
-│ ├── dependencies.py # "dependencies" módulo, e.g. import app.dependencies
-│ └── routers # "routers" é um "subpacote Python"
-│ │ ├── __init__.py # torna "routers" um "subpacote Python"
-│ │ ├── items.py # "items" submódulo, e.g. import app.routers.items
-│ │ └── users.py # "users" submódulo, e.g. import app.routers.users
-│ └── internal # "internal" é um "subpacote Python"
-│ ├── __init__.py # torna "internal" um "subpacote Python"
-│ └── admin.py # "admin" submódulo, e.g. import app.internal.admin
+├── app # "app" is a Python package
+│ ├── __init__.py # this file makes "app" a "Python package"
+│ ├── main.py # "main" module, e.g. import app.main
+│ ├── dependencies.py # "dependencies" module, e.g. import app.dependencies
+│ └── routers # "routers" is a "Python subpackage"
+│ │ ├── __init__.py # makes "routers" a "Python subpackage"
+│ │ ├── items.py # "items" submodule, e.g. import app.routers.items
+│ │ └── users.py # "users" submodule, e.g. import app.routers.users
+│ └── internal # "internal" is a "Python subpackage"
+│ ├── __init__.py # makes "internal" a "Python subpackage"
+│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
```
-## `APIRouter`
+## `APIRouter` { #apirouter }
Vamos supor que o arquivo dedicado a lidar apenas com usuários seja o submódulo em `/app/routers/users.py`.
@@ -79,25 +79,21 @@ Você quer manter as *operações de rota* relacionadas aos seus usuários separ
Mas ele ainda faz parte da mesma aplicação/web API **FastAPI** (faz parte do mesmo "pacote Python").
-Você pode criar as *operações de rotas* para esse módulo usando o `APIRouter`.
+Você pode criar as *operações de rota* para esse módulo usando o `APIRouter`.
-### Importar `APIRouter`
+### Importe `APIRouter` { #import-apirouter }
-você o importa e cria uma "instância" da mesma maneira que faria com a classe `FastAPI`:
+Você o importa e cria uma "instância" da mesma maneira que faria com a classe `FastAPI`:
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
-### *Operações de Rota* com `APIRouter`
+### *Operações de Rota* com `APIRouter` { #path-operations-with-apirouter }
E então você o utiliza para declarar suas *operações de rota*.
-Utilize-o da mesma maneira que utilizaria a classe `FastAPI`:
+Utilize-o da mesma maneira que utilizaria a classe `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_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
Você pode pensar em `APIRouter` como uma classe "mini `FastAPI`".
@@ -113,7 +109,7 @@ Neste exemplo, a variável é chamada de `router`, mas você pode nomeá-la como
Vamos incluir este `APIRouter` na aplicação principal `FastAPI`, mas primeiro, vamos verificar as dependências e outro `APIRouter`.
-## Dependências
+## Dependências { #dependencies }
Vemos que precisaremos de algumas dependências usadas em vários lugares da aplicação.
@@ -121,35 +117,7 @@ Então, as colocamos em seu próprio módulo de `dependencies` (`app/dependencie
Agora usaremos uma dependência simples para ler um cabeçalho `X-Token` personalizado:
-//// 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 | Dica
-
-Prefira usar a versão `Annotated` se possível.
-
-///
-
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!> ../../docs_src/bigger_applications/app/dependencies.py!}
-```
-
-////
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
/// tip | Dica
@@ -159,7 +127,7 @@ Mas em casos reais, você obterá melhores resultados usando os [Utilitários de
///
-## Outro módulo com `APIRouter`
+## Outro módulo com `APIRouter` { #another-module-with-apirouter }
Digamos que você também tenha os endpoints dedicados a manipular "itens" do seu aplicativo no módulo em `app/routers/items.py`.
@@ -177,15 +145,13 @@ Sabemos que todas as *operações de rota* neste módulo têm o mesmo:
* Path `prefix`: `/items`.
* `tags`: (apenas uma tag: `items`).
* Extra `responses`.
-* `dependências`: todas elas precisam da dependência `X-Token` que criamos.
+* `dependencies`: todas elas precisam da dependência `X-Token` que criamos.
Então, em vez de adicionar tudo isso a cada *operação de rota*, podemos adicioná-lo ao `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_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
-Como o caminho de cada *operação de rota* deve começar com `/`, como em:
+Como o path de cada *operação de rota* tem que começar com `/`, como em:
```Python hl_lines="1"
@router.get("/{item_id}")
@@ -197,9 +163,9 @@ async def read_item(item_id: str):
Então, o prefixo neste caso é `/items`.
-Também podemos adicionar uma lista de `tags` e `responses` extras que serão aplicadas a todas as *operações de rota* incluídas neste roteador.
+Também podemos adicionar uma list de `tags` e `responses` extras que serão aplicadas a todas as *operações de rota* incluídas neste router.
-E podemos adicionar uma lista de `dependencies` que serão adicionadas a todas as *operações de rota* no roteador e serão executadas/resolvidas para cada solicitação feita a elas.
+E podemos adicionar uma list de `dependencies` que serão adicionadas a todas as *operações de rota* no router e serão executadas/resolvidas para cada request feita a elas.
/// tip | Dica
@@ -207,7 +173,7 @@ Observe que, assim como [dependências em *decoradores de operação de rota*](d
///
-O resultado final é que os caminhos dos itens agora são:
+O resultado final é que os paths dos itens agora são:
* `/items/`
* `/items/{item_id}`
@@ -217,24 +183,24 @@ O resultado final é que os caminhos dos itens agora são:
* Elas serão marcadas com uma lista de tags que contêm uma única string `"items"`.
* Essas "tags" são especialmente úteis para os sistemas de documentação interativa automática (usando OpenAPI).
* Todas elas incluirão as `responses` predefinidas.
-* Todas essas *operações de rota* terão a lista de `dependencies` avaliada/executada antes delas.
+* Todas essas *operações de rota* terão a list de `dependencies` avaliada/executada antes delas.
* Se você também declarar dependências em uma *operação de rota* específica, **elas também serão executadas**.
- * As dependências do roteador são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} e, em seguida, as dependências de parâmetros normais.
+ * As dependências do router são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} e, em seguida, as dependências de parâmetros normais.
* Você também pode adicionar [dependências de `Segurança` com `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
/// tip | Dica
-Ter `dependências` no `APIRouter` pode ser usado, por exemplo, para exigir autenticação para um grupo inteiro de *operações de rota*. Mesmo que as dependências não sejam adicionadas individualmente a cada uma delas.
+Ter `dependencies` no `APIRouter` pode ser usado, por exemplo, para exigir autenticação para um grupo inteiro de *operações de rota*. Mesmo que as dependências não sejam adicionadas individualmente a cada uma delas.
///
-/// check
+/// check | Verifique
Os parâmetros `prefix`, `tags`, `responses` e `dependencies` são (como em muitos outros casos) apenas um recurso do **FastAPI** para ajudar a evitar duplicação de código.
///
-### Importar as dependências
+### Importe as dependências { #import-the-dependencies }
Este código reside no módulo `app.routers.items`, o arquivo `app/routers/items.py`.
@@ -242,11 +208,9 @@ E precisamos obter a função de dependência do módulo `app.dependencies`, o a
Então usamos uma importação relativa com `..` para as dependências:
-```Python hl_lines="3" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
-#### Como funcionam as importações relativas
+#### Como funcionam as importações relativas { #how-relative-imports-work }
/// tip | Dica
@@ -282,7 +246,7 @@ from ..dependencies import get_token_header
significa:
-* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) reside (o diretório `app/routers/`)...
+* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) vive (o diretório `app/routers/`)...
* vá para o pacote pai (o diretório `app/`)...
* e lá, encontre o módulo `dependencies` (o arquivo em `app/dependencies.py`)...
* e dele, importe a função `get_token_header`.
@@ -309,25 +273,23 @@ Isso se referiria a algum pacote acima de `app/`, com seu próprio arquivo `__in
Mas agora você sabe como funciona, então você pode usar importações relativas em seus próprios aplicativos, não importa o quão complexos eles sejam. 🤓
-### Adicione algumas `tags`, `respostas` e `dependências` personalizadas
+### Adicione algumas `tags`, `responses` e `dependencies` personalizadas { #add-some-custom-tags-responses-and-dependencies }
Não estamos adicionando o prefixo `/items` nem `tags=["items"]` a cada *operação de rota* porque os adicionamos ao `APIRouter`.
-Mas ainda podemos adicionar _mais_ `tags` que serão aplicadas a uma *operação de rota* específica, e também algumas `respostas` extras específicas para essa *operação de rota*:
+Mas ainda podemos adicionar _mais_ `tags` que serão aplicadas a uma *operação de rota* específica, e também algumas `responses` extras específicas para essa *operação de rota*:
-```Python hl_lines="30-31" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
/// tip | Dica
-Esta última operação de caminho terá a combinação de tags: `["items", "custom"]`.
+Esta última operação de rota terá a combinação de tags: `["items", "custom"]`.
-E também terá ambas as respostas na documentação, uma para `404` e uma para `403`.
+E também terá ambas as responses na documentação, uma para `404` e uma para `403`.
///
-## O principal `FastAPI`
+## O principal `FastAPI` { #the-main-fastapi }
Agora, vamos ver o módulo em `app/main.py`.
@@ -337,27 +299,23 @@ Este será o arquivo principal em seu aplicativo que une tudo.
E como a maior parte de sua lógica agora viverá em seu próprio módulo específico, o arquivo principal será bem simples.
-### Importar `FastAPI`
+### Importe o `FastAPI` { #import-fastapi }
Você importa e cria uma classe `FastAPI` normalmente.
E podemos até declarar [dependências globais](dependencies/global-dependencies.md){.internal-link target=_blank} que serão combinadas com as dependências para cada `APIRouter`:
-```Python hl_lines="1 3 7" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
-### Importe o `APIRouter`
+### Importe o `APIRouter` { #import-the-apirouter }
Agora importamos os outros submódulos que possuem `APIRouter`s:
-```Python hl_lines="4-5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *}
Como os arquivos `app/routers/users.py` e `app/routers/items.py` são submódulos que fazem parte do mesmo pacote Python `app`, podemos usar um único ponto `.` para importá-los usando "importações relativas".
-### Como funciona a importação
+### Como funciona a importação { #how-the-importing-works }
A seção:
@@ -367,7 +325,7 @@ from .routers import items, users
significa:
-* Começando no mesmo pacote em que este módulo (o arquivo `app/main.py`) reside (o diretório `app/`)...
+* Começando no mesmo pacote em que este módulo (o arquivo `app/main.py`) vive (o diretório `app/`)...
* procure o subpacote `routers` (o diretório em `app/routers/`)...
* e dele, importe o submódulo `items` (o arquivo em `app/routers/items.py`) e `users` (o arquivo em `app/routers/users.py`)...
@@ -399,7 +357,7 @@ Para saber mais sobre pacotes e módulos Python, leia
```console
-$ uvicorn app.main:app --reload
+$ fastapi dev app/main.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
-## Incluir o mesmo roteador várias vezes com `prefixos` diferentes
+## Inclua o mesmo router várias vezes com `prefix` diferentes { #include-the-same-router-multiple-times-with-different-prefix }
-Você também pode usar `.include_router()` várias vezes com o *mesmo* roteador usando prefixos diferentes.
+Você também pode usar `.include_router()` várias vezes com o *mesmo* router 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
+## Inclua um `APIRouter` em outro { #include-an-apirouter-in-another }
-Da mesma forma que você pode incluir um `APIRouter` em um aplicativo `FastAPI`, você pode incluir um `APIRouter` em outro `APIRouter` usando:
+Da mesma forma que você pode incluir um `APIRouter` em uma aplicação `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.
+Certifique-se de fazer isso antes de incluir `router` na aplicação `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 e7dfb07f2..25e11189e 100644
--- a/docs/pt/docs/tutorial/body-fields.md
+++ b/docs/pt/docs/tutorial/body-fields.md
@@ -1,28 +1,28 @@
-# Corpo - Campos
+# Corpo - Campos { #body-fields }
-Da mesma forma que você pode declarar validações adicionais e metadados nos parâmetros de *funções de operações de rota* com `Query`, `Path` e `Body`, você pode declarar validações e metadados dentro de modelos do Pydantic usando `Field` do Pydantic.
+Da mesma forma que você pode declarar validações adicionais e metadados nos parâmetros de uma *função de operação de rota* com `Query`, `Path` e `Body`, você pode declarar validações e metadados dentro de modelos do Pydantic usando `Field` do Pydantic.
-## Importe `Field`
+## Importe `Field` { #import-field }
Primeiro, você tem que importá-lo:
-{* ../../docs_src/body_fields/tutorial001.py hl[4] *}
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
-/// warning | Aviso
+/// warning | Atenção
Note que `Field` é importado diretamente do `pydantic`, não do `fastapi` como todo o resto (`Query`, `Path`, `Body`, etc).
///
-## Declare atributos do modelo
+## Declare atributos do modelo { #declare-model-attributes }
Você pode então utilizar `Field` com atributos do modelo:
-{* ../../docs_src/body_fields/tutorial001.py hl[11:14] *}
+{* ../../docs_src/body_fields/tutorial001_an_py310.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
+/// 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.
@@ -40,13 +40,20 @@ Note como cada atributo do modelo com um tipo, valor padrão e `Field` possuem a
///
-## Adicione informações extras
+## Adicione informações extras { #add-extra-information }
Você pode declarar informação extra em `Field`, `Query`, `Body`, etc. E isso será incluído no JSON Schema gerado.
Você irá aprender mais sobre adicionar informações extras posteriormente nessa documentação, quando estiver aprendendo a declarar exemplos.
-## Recapitulando
+/// warning | Atenção
+
+Chaves extras passadas para `Field` também estarão presentes no schema OpenAPI resultante da sua aplicação.
+Como essas chaves podem não fazer necessariamente parte da especificação OpenAPI, algumas ferramentas de OpenAPI, por exemplo [o validador do OpenAPI](https://validator.swagger.io/), podem não funcionar com o schema gerado.
+
+///
+
+## Recapitulando { #recap }
Você pode usar `Field` do Pydantic para declarar validações extras e metadados para atributos do modelo.
diff --git a/docs/pt/docs/tutorial/body-multiple-params.md b/docs/pt/docs/tutorial/body-multiple-params.md
index eda9b4dff..3cba04912 100644
--- a/docs/pt/docs/tutorial/body-multiple-params.md
+++ b/docs/pt/docs/tutorial/body-multiple-params.md
@@ -1,14 +1,14 @@
-# Corpo - Múltiplos parâmetros
+# Corpo - Múltiplos parâmetros { #body-multiple-parameters }
Agora que nós vimos como usar `Path` e `Query`, veremos usos mais avançados de declarações no corpo da requisição.
-## Misture `Path`, `Query` e parâmetros de corpo
+## Misture `Path`, `Query` e parâmetros de corpo { #mix-path-query-and-body-parameters }
Primeiro, é claro, você pode misturar `Path`, `Query` e declarações de parâmetro no corpo da requisição livremente e o **FastAPI** saberá o que fazer.
E você também pode declarar parâmetros de corpo como opcionais, definindo o valor padrão com `None`:
-{* ../../docs_src/body_multiple_params/tutorial001_py310.py hl[17:19] *}
+{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
/// note | Nota
@@ -16,7 +16,7 @@ Repare que, neste caso, o `item` que seria capturado a partir do corpo é opcion
///
-## Múltiplos parâmetros de corpo
+## Múltiplos parâmetros de corpo { #multiple-body-parameters }
No exemplo anterior, as *operações de rota* esperariam um JSON no corpo contendo os atributos de um `Item`, exemplo:
@@ -62,7 +62,7 @@ O **FastAPI** fará a conversão automática a partir da requisição, assim ess
Ele executará a validação dos dados compostos e irá documentá-los de maneira compatível com o esquema OpenAPI e documentação automática.
-## Valores singulares no corpo
+## Valores singulares no corpo { #singular-values-in-body }
Assim como existem uma `Query` e uma `Path` para definir dados adicionais para parâmetros de consulta e de rota, o **FastAPI** provê o equivalente para `Body`.
@@ -72,7 +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`:
-{* ../../docs_src/body_multiple_params/tutorial003.py hl[22] *}
+{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
Neste caso, o **FastAPI** esperará um corpo como:
@@ -94,7 +94,7 @@ Neste caso, o **FastAPI** esperará um corpo como:
Mais uma vez, ele converterá os tipos de dados, validar, documentar, etc.
-## Múltiplos parâmetros de corpo e consulta
+## Múltiplos parâmetros de corpo e consulta { #multiple-body-params-and-query }
Obviamente, você também pode declarar parâmetros de consulta assim que você precisar, de modo adicional a quaisquer parâmetros de corpo.
@@ -112,7 +112,7 @@ q: str | None = None
Por exemplo:
-{* ../../docs_src/body_multiple_params/tutorial004_py310.py hl[26] *}
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
/// info | Informação
@@ -120,7 +120,7 @@ Por exemplo:
///
-## Declare um único parâmetro de corpo indicando sua chave
+## Declare um único parâmetro de corpo indicando sua chave { #embed-a-single-body-parameter }
Suponha que você tem um único parâmetro de corpo `item`, a partir de um modelo Pydantic `Item`.
@@ -134,7 +134,7 @@ item: Item = Body(embed=True)
como em:
-{* ../../docs_src/body_multiple_params/tutorial005_py310.py hl[15] *}
+{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
Neste caso o **FastAPI** esperará um corpo como:
@@ -160,7 +160,7 @@ ao invés de:
}
```
-## Recapitulando
+## Recapitulando { #recap }
Você pode adicionar múltiplos parâmetros de corpo para sua *função de operação de rota*, mesmo que a requisição possa ter somente um único corpo.
diff --git a/docs/pt/docs/tutorial/body-nested-models.md b/docs/pt/docs/tutorial/body-nested-models.md
index 2954ae3db..f2bec19a2 100644
--- a/docs/pt/docs/tutorial/body-nested-models.md
+++ b/docs/pt/docs/tutorial/body-nested-models.md
@@ -1,36 +1,26 @@
-# Corpo - Modelos aninhados
+# Corpo - Modelos aninhados { #body-nested-models }
-Com o **FastAPI**, você pode definir, validar, documentar e usar modelos profundamente aninhados de forma arbitrária (graças ao Pydantic).
+Com o **FastAPI**, você pode definir, validar, documentar e usar modelos arbitrariamente e profundamente aninhados (graças ao Pydantic).
-## Campos do tipo Lista
+## Campos do tipo Lista { #list-fields }
Você pode definir um atributo como um subtipo. Por exemplo, uma `list` do Python:
-{* ../../docs_src/body_nested_models/tutorial001.py hl[14] *}
+{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
Isso fará com que tags seja uma lista de itens mesmo sem declarar o tipo dos elementos desta lista.
-## Campos do tipo Lista com um parâmetro de tipo
+## Campos do tipo Lista com um parâmetro de tipo { #list-fields-with-type-parameter }
Mas o Python tem uma maneira específica de declarar listas com tipos internos ou "parâmetros de tipo":
-### Importe `List` do typing
+### Declare uma `list` com um parâmetro de tipo { #declare-a-list-with-a-type-parameter }
-Primeiramente, importe `List` do módulo `typing` que já vem por padrão no Python:
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
-### Declare a `List` com um parâmetro de tipo
-
-Para declarar tipos que têm parâmetros de tipo(tipos internos), como `list`, `dict`, `tuple`:
-
-* Importe os do modulo `typing`
-* Passe o(s) tipo(s) interno(s) como "parâmetros de tipo" usando colchetes: `[` e `]`
+Para declarar tipos que têm parâmetros de tipo (tipos internos), como `list`, `dict`, `tuple`,
+passe o(s) tipo(s) interno(s) como "parâmetros de tipo" usando colchetes: `[` e `]`
```Python
-from typing import List
-
-my_list: List[str]
+my_list: list[str]
```
Essa é a sintaxe padrão do Python para declarações de tipo.
@@ -39,20 +29,17 @@ 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":
+{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-{* ../../docs_src/body_nested_models/tutorial002.py hl[14] *}
-
-## Tipo "set"
-
+## Tipos "set" { #set-types }
Mas então, quando nós pensamos mais, percebemos que as tags não devem se repetir, elas provavelmente devem ser strings únicas.
E que o Python tem um tipo de dados especial para conjuntos de itens únicos, o `set`.
-Então podemos importar `Set` e declarar `tags` como um `set` de `str`s:
+Então podemos declarar `tags` como um conjunto de strings:
-
-{* ../../docs_src/body_nested_models/tutorial003.py hl[1,14] *}
+{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
Com isso, mesmo que você receba uma requisição contendo dados duplicados, ela será convertida em um conjunto de itens exclusivos.
@@ -60,7 +47,7 @@ E sempre que você enviar esses dados como resposta, mesmo se a fonte tiver dupl
E também teremos anotações/documentação em conformidade.
-## Modelos aninhados
+## Modelos aninhados { #nested-models }
Cada atributo de um modelo Pydantic tem um tipo.
@@ -70,17 +57,17 @@ Portanto, você pode declarar "objects" JSON profundamente aninhados com nomes,
Tudo isso, aninhado arbitrariamente.
-### Defina um sub-modelo
+### Defina um sub-modelo { #define-a-submodel }
Por exemplo, nós podemos definir um modelo `Image`:
-{* ../../docs_src/body_nested_models/tutorial004.py hl[9:11] *}
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### Use o sub-modelo como um tipo
+### Use o sub-modelo como um tipo { #use-the-submodel-as-a-type }
E então podemos usa-lo como o tipo de um atributo:
-{* ../../docs_src/body_nested_models/tutorial004.py hl[20] *}
+{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[18] *}
Isso significa que o **FastAPI** vai esperar um corpo similar à:
@@ -100,28 +87,28 @@ Isso significa que o **FastAPI** vai esperar um corpo similar à:
Novamente, apenas fazendo essa declaração, com o **FastAPI**, você ganha:
-* Suporte do editor de texto (compleção, etc), inclusive para modelos aninhados
+* Suporte do editor (preenchimento automático, etc.), inclusive para modelos aninhados
* Conversão de dados
* Validação de dados
* Documentação automatica
-## Tipos especiais e validação
+## Tipos especiais e validação { #special-types-and-validation }
Além dos tipos singulares normais como `str`, `int`, `float`, etc. Você também pode usar tipos singulares mais complexos que herdam de `str`.
-Para ver todas as opções possíveis, cheque a documentação para ostipos exoticos do Pydantic. Você verá alguns exemplos no próximo capitulo.
+Para ver todas as opções possíveis, consulte a Visão geral dos tipos do Pydantic. Você verá alguns exemplos no próximo capítulo.
Por exemplo, no modelo `Image` nós temos um campo `url`, nós podemos declara-lo como um `HttpUrl` do Pydantic invés de como uma `str`:
-{* ../../docs_src/body_nested_models/tutorial005.py hl[4,10] *}
+{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
-A string será verificada para se tornar uma URL válida e documentada no esquema JSON/1OpenAPI como tal.
+A string será verificada para se tornar uma URL válida e documentada no JSON Schema / OpenAPI como tal.
-## Atributos como listas de submodelos
+## Atributos como listas de submodelos { #attributes-with-lists-of-submodels }
Você também pode usar modelos Pydantic como subtipos de `list`, `set`, etc:
-{* ../../docs_src/body_nested_models/tutorial006.py hl[20] *}
+{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
Isso vai esperar(converter, validar, documentar, etc) um corpo JSON tal qual:
@@ -149,38 +136,37 @@ Isso vai esperar(converter, validar, documentar, etc) um corpo JSON tal qual:
}
```
-/// info | informação
+/// info | Informação
-Note como o campo `images` agora tem uma lista de objetos de image.
+Observe como a chave `images` agora tem uma lista de objetos de imagem.
///
-## Modelos profundamente aninhados
+## Modelos profundamente aninhados { #deeply-nested-models }
Você pode definir modelos profundamente aninhados de forma arbitrária:
-{* ../../docs_src/body_nested_models/tutorial007.py hl[9,14,20,23,27] *}
+{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
-/// info | informação
+/// info | Informação
-Note como `Offer` tem uma lista de `Item`s, que por sua vez possui opcionalmente uma lista `Image`s
+Observe como `Offer` tem uma lista de `Item`s, que por sua vez têm uma lista opcional de `Image`s
///
-## Corpos de listas puras
+## Corpos de listas puras { #bodies-of-pure-lists }
Se o valor de primeiro nível do corpo JSON que você espera for um `array` do JSON (uma` lista` do Python), você pode declarar o tipo no parâmetro da função, da mesma forma que nos modelos do Pydantic:
-
```Python
-images: List[Image]
+images: list[Image]
```
como em:
-{* ../../docs_src/body_nested_models/tutorial008.py hl[15] *}
+{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## Suporte de editor em todo canto
+## Suporte de editor em todo canto { #editor-support-everywhere }
E você obtém suporte do editor em todos os lugares.
@@ -192,7 +178,7 @@ Você não conseguiria este tipo de suporte de editor se estivesse trabalhando d
Mas você também não precisa se preocupar com eles, os dicts de entrada são convertidos automaticamente e sua saída é convertida automaticamente para JSON também.
-## Corpos de `dict`s arbitrários
+## Corpos de `dict`s arbitrários { #bodies-of-arbitrary-dicts }
Você também pode declarar um corpo como um `dict` com chaves de algum tipo e valores de outro tipo.
@@ -208,7 +194,7 @@ Outro caso útil é quando você deseja ter chaves de outro tipo, por exemplo, `
Neste caso, você aceitaria qualquer `dict`, desde que tenha chaves` int` com valores `float`:
-{* ../../docs_src/body_nested_models/tutorial009.py hl[9] *}
+{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
/// tip | Dica
@@ -222,14 +208,14 @@ E o `dict` que você recebe como `weights` terá, na verdade, chaves `int` e val
///
-## Recapitulação
+## Recapitulação { #recap }
Com **FastAPI** você tem a flexibilidade máxima fornecida pelos modelos Pydantic, enquanto seu código é mantido simples, curto e elegante.
Mas com todos os benefícios:
-* Suporte do editor (compleção em todo canto!)
-* Conversão de dados (leia-se parsing/serialização)
+* Suporte do editor (preenchimento automático em todo canto!)
+* Conversão de dados (parsing/serialização)
* Validação de dados
* Documentação dos esquemas
* Documentação automática
diff --git a/docs/pt/docs/tutorial/body-updates.md b/docs/pt/docs/tutorial/body-updates.md
index bf38aeb9e..95f89c8d2 100644
--- a/docs/pt/docs/tutorial/body-updates.md
+++ b/docs/pt/docs/tutorial/body-updates.md
@@ -1,6 +1,6 @@
-# Corpo - Atualizações
+# Corpo - Atualizações { #body-updates }
-## Atualização de dados existentes com `PUT`
+## Atualização substituindo com `PUT` { #update-replacing-with-put }
Para atualizar um item, você pode usar a operação HTTP `PUT`.
@@ -10,7 +10,7 @@ Você pode usar `jsonable_encoder` para converter os dados de entrada em dados q
`PUT` é usado para receber dados que devem substituir os dados existentes.
-### Aviso sobre a substituição
+### Aviso sobre a substituição { #warning-about-replacing }
Isso significa que, se você quiser atualizar o item `bar` usando `PUT` com um corpo contendo:
@@ -22,13 +22,13 @@ Isso significa que, se você quiser atualizar o item `bar` usando `PUT` com um c
}
```
-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`.
+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`
+## Atualizações parciais com `PATCH` { #partial-updates-with-patch }
-Você também pode usar a operação HTTP `PATCH` para *atualizar* parcialmente os dados.
+Você também pode usar a operação HTTP `PATCH` para atualizar dados *parcialmente*.
Isso significa que você pode enviar apenas os dados que deseja atualizar, deixando o restante intacto.
@@ -40,59 +40,43 @@ 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.
+Mas este guia mostra, mais ou menos, como eles são destinados a serem usados.
///
-### Usando o parâmetro `exclude_unset` do Pydantic
+### Usando o parâmetro `exclude_unset` do Pydantic { #using-pydantics-exclude-unset-parameter }
-Se você quiser receber atualizações parciais, é muito útil usar o parâmetro `exclude_unset` no método `.model_dump()` do modelo do Pydantic.
+Se você quiser receber atualizações parciais, é muito útil usar o parâmetro `exclude_unset` no `.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.
+Isso geraria um `dict` com apenas os dados que foram 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
+### Usando o parâmetro `update` do Pydantic { #using-pydantics-update-parameter }
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
+### Recapitulando as atualizações parciais { #partial-updates-recap }
-Resumindo, para aplicar atualizações parciais você pode:
+Resumindo, para aplicar atualizações parciais você deveria:
* (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.
+ * Dessa forma, você pode atualizar apenas os valores realmente definidos pelo usuário, em vez de substituir valores já armazenados por valores padrão do 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.
+* Converter o modelo copiado em algo que possa ser armazenado no seu BD (por exemplo, usando o `jsonable_encoder`).
+ * Isso é comparável a usar o método `.model_dump()` do modelo novamente, 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 BD.
* Retornar o modelo atualizado.
{* ../../docs_src/body_updates/tutorial002_py310.py hl[28:35] *}
@@ -109,8 +93,8 @@ Mas o exemplo aqui usa `PATCH` porque foi criado para esses casos de uso.
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`).
+Portanto, se você quiser receber atualizações parciais que possam omitir todos os atributos, você precisa 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}.
+Para distinguir entre 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 2508d7981..669334439 100644
--- a/docs/pt/docs/tutorial/body.md
+++ b/docs/pt/docs/tutorial/body.md
@@ -1,51 +1,52 @@
-# Corpo da Requisição
+# Corpo da requisição { #request-body }
-Quando você precisa enviar dados de um cliente (como de um navegador web) para sua API, você o envia como um **corpo da requisição**.
+Quando você precisa enviar dados de um cliente (como de um navegador) para sua API, você os envia como um **corpo da requisição**.
O corpo da **requisição** é a informação enviada pelo cliente para sua API. O corpo da **resposta** é a informação que sua API envia para o cliente.
-Sua API quase sempre irá enviar um corpo na **resposta**. Mas os clientes não necessariamente precisam enviar um corpo em toda **requisição**.
+Sua API quase sempre precisa enviar um corpo na **resposta**. Mas os clientes não necessariamente precisam enviar **corpos de requisição** o tempo todo, às vezes eles apenas requisitam um path, talvez com alguns parâmetros de consulta, mas não enviam um corpo.
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`.
+Para enviar dados, você deveria usar um dos: `POST` (o mais comum), `PUT`, `DELETE` ou `PATCH`.
Enviar um corpo em uma requisição `GET` não tem um comportamento definido nas especificações, porém é suportado pelo FastAPI, apenas para casos de uso bem complexos/extremos.
-Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição para um `GET`, e proxies que intermediarem podem não suportar o corpo da requisição.
+Como é desencorajado, a documentação interativa com Swagger UI não irá mostrar a documentação para o corpo da requisição ao usar `GET`, e proxies intermediários podem não suportá-lo.
///
-## Importe o `BaseModel` do Pydantic
+## Importe o `BaseModel` do Pydantic { #import-pydantics-basemodel }
Primeiro, você precisa importar `BaseModel` do `pydantic`:
-{* ../../docs_src/body/tutorial001.py hl[4] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## Crie seu modelo de dados
+## Crie seu modelo de dados { #create-your-data-model }
Então você declara seu modelo de dados como uma classe que herda `BaseModel`.
Utilize os tipos Python padrão para todos os atributos:
-{* ../../docs_src/body/tutorial001.py hl[7:11] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
-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.
+
+Assim como quando declaramos parâmetros de consulta, quando um atributo do modelo possui um valor padrão, ele não é obrigatório. Caso contrário, é obrigatório. Use `None` para torná-lo apenas opcional.
Por exemplo, o modelo acima declara um JSON "`object`" (ou `dict` no Python) como esse:
```JSON
{
"name": "Foo",
- "description": "Uma descrição opcional",
+ "description": "An optional description",
"price": 45.2,
"tax": 3.5
}
```
-...como `description` e `tax` são opcionais (Com um valor padrão de `None`), esse JSON "`object`" também é válido:
+...como `description` e `tax` são opcionais (com um valor padrão de `None`), esse JSON "`object`" também é válido:
```JSON
{
@@ -54,40 +55,40 @@ Por exemplo, o modelo acima declara um JSON "`object`" (ou `dict` no Python) com
}
```
-## Declare como um parâmetro
+## Declare como um parâmetro { #declare-it-as-a-parameter }
-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:
+Para adicioná-lo à sua *operação de rota*, declare-o da mesma maneira que você declarou parâmetros de rota e de consulta:
-{* ../../docs_src/body/tutorial001.py hl[18] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
-...E declare o tipo como o modelo que você criou, `Item`.
+...e declare o seu tipo como o modelo que você criou, `Item`.
-## Resultados
+## Resultados { #results }
-Apenas com esse declaração de tipos do Python, o **FastAPI** irá:
+Apenas com essa declaração de tipos do Python, o **FastAPI** irá:
-* Ler o corpo da requisição como um JSON.
+* Ler o corpo da requisição como JSON.
* Converter os tipos correspondentes (se necessário).
* Validar os dados.
- * Se algum dados for inválido, irá retornar um erro bem claro, indicando exatamente onde e o que está incorreto.
+ * Se algum dado for inválido, irá retornar um erro bem claro, indicando exatamente onde e o que estava incorreto.
* Entregar a você a informação recebida no parâmetro `item`.
* Como você o declarou na função como do tipo `Item`, você também terá o suporte do editor (completação, etc) para todos os atributos e seus tipos.
-* Gerar um Esquema JSON com as definições do seu modelo, você também pode utilizá-lo em qualquer lugar que quiser, se fizer sentido para seu projeto.
-* Esses esquemas farão parte do esquema OpenAPI, e utilizados nas UIs de documentação automática.
+* Gerar definições de JSON Schema para o seu modelo; você também pode usá-las em qualquer outro lugar se fizer sentido para o seu projeto.
+* Esses schemas farão parte do esquema OpenAPI gerado, e serão usados pelas UIs de documentação automática.
-## Documentação automática
+## Documentação automática { #automatic-docs }
-Os esquemas JSON dos seus modelos farão parte do esquema OpenAPI gerado para sua aplicação, e aparecerão na documentação interativa da API:
+Os JSON Schemas dos seus modelos farão parte do esquema OpenAPI gerado para sua aplicação, e aparecerão na documentação interativa da API:
-E também serão utilizados em cada *função de operação de rota* que utilizá-los:
+E também serão utilizados na documentação da API dentro de cada *operação de rota* que precisar deles:
-## Suporte do editor de texto:
+## Suporte do editor { #editor-support }
-No seu editor de texto, dentro da função você receberá dicas de tipos e completação em todo lugar (isso não aconteceria se você recebesse um `dict` em vez de um modelo Pydantic):
+No seu editor, dentro da função você receberá dicas de tipos e completação em todo lugar (isso não aconteceria se você recebesse um `dict` em vez de um modelo Pydantic):
@@ -111,9 +112,9 @@ Mas você terá o mesmo suporte do editor no PyCharm como editor, você pode utilizar o Plugin do Pydantic para o PyCharm .
-Melhora o suporte do editor para seus modelos Pydantic com::
+Melhora o suporte do editor para seus modelos Pydantic com:
-* completação automática
+* preenchimento automático
* verificação de tipos
* refatoração
* buscas
@@ -121,42 +122,45 @@ Melhora o suporte do editor para seus modelos Pydantic com::
///
-## Use o modelo
+## Use o modelo { #use-the-model }
Dentro da função, você pode acessar todos os atributos do objeto do modelo diretamente:
-{* ../../docs_src/body/tutorial002.py hl[21] *}
+{* ../../docs_src/body/tutorial002_py310.py *}
-## Corpo da requisição + parâmetros de rota
+## Corpo da requisição + parâmetros de rota { #request-body-path-parameters }
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**.
+O **FastAPI** irá reconhecer que os parâmetros da função que combinam com parâmetros de rota devem ser **retirados da rota**, e que parâmetros da função que são declarados como modelos Pydantic sejam **retirados do corpo da requisição**.
+
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-{* ../../docs_src/body/tutorial003.py hl[17:18] *}
-## Corpo da requisição + parâmetros de rota + parâmetros de consulta
+## Corpo da requisição + parâmetros de rota + parâmetros de consulta { #request-body-path-query-parameters }
Você também pode declarar parâmetros de **corpo**, **rota** e **consulta**, ao mesmo tempo.
O **FastAPI** irá reconhecer cada um deles e retirar a informação do local correto.
-{* ../../docs_src/body/tutorial004.py hl[18] *}
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
Os parâmetros da função serão reconhecidos conforme abaixo:
-* Se o parâmetro também é declarado na **rota**, será utilizado como um parâmetro de rota.
+* Se o parâmetro também é declarado no **path**, será utilizado como um parâmetro de rota.
* Se o parâmetro é de um **tipo único** (como `int`, `float`, `str`, `bool`, etc) será interpretado como um parâmetro de **consulta**.
* Se o parâmetro é declarado como um **modelo Pydantic**, será interpretado como o **corpo** da requisição.
-/// note | Observação
+/// note | Nota
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.
+O `str | None` (Python 3.10+) ou o `Union` em `Union[str, None]` (Python 3.9+) não é utilizado pelo FastAPI para determinar que o valor não é obrigatório, ele saberá que não é obrigatório porque tem um valor padrão `= None`.
+
+Mas adicionar as anotações de tipo permitirá ao seu editor oferecer um suporte melhor e detectar erros.
///
-## Sem o Pydantic
+## Sem o Pydantic { #without-pydantic }
-Se você não quer utilizar os modelos Pydantic, você também pode utilizar o parâmetro **Body**. Veja a documentação para [Body - Parâmetros múltiplos: Valores singulares no body](body-multiple-params.md#valores-singulares-no-corpo){.internal-link target=_blank}.
+Se você não quer utilizar os modelos Pydantic, você também pode utilizar o parâmetro **Body**. Veja a documentação para [Body - Parâmetros múltiplos: Valores singulares no body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/pt/docs/tutorial/cookie-param-models.md b/docs/pt/docs/tutorial/cookie-param-models.md
index 3d46ba44c..73c94050f 100644
--- a/docs/pt/docs/tutorial/cookie-param-models.md
+++ b/docs/pt/docs/tutorial/cookie-param-models.md
@@ -1,4 +1,4 @@
-# Modelos de Parâmetros de Cookie
+# Modelos de Parâmetros de Cookie { #cookie-parameter-models }
Se você possui um grupo de **cookies** que estão relacionados, você pode criar um **modelo Pydantic** para declará-los. 🍪
@@ -16,7 +16,7 @@ Essa mesma técnica se aplica para `Query`, `Cookie`, e `Header`. 😎
///
-## Cookies com Modelos Pydantic
+## Cookies com Modelos Pydantic { #cookies-with-a-pydantic-model }
Declare o parâmetro de **cookie** que você precisa em um **modelo Pydantic**, e depois declare o parâmetro como um `Cookie`:
@@ -24,9 +24,9 @@ Declare o parâmetro de **cookie** que você precisa em um **modelo Pydantic**,
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
+## Verifique a Documentação { #check-the-docs }
-Você pode ver os cookies definidos na IU dos documentos em `/docs`:
+Você pode ver os cookies definidos na IU da documentação em `/docs`:
@@ -36,29 +36,27 @@ Você pode ver os cookies definidos na IU dos documentos em `/docs`:
Tenha em mente que, como os **navegadores lidam com cookies** de maneira especial e por baixo dos panos, eles **não** permitem facilmente que o **JavaScript** lidem com eles.
-Se você for na **IU de documentos da API** em `/docs` você poderá ver a **documentação** para cookies das suas *operações de rotas*.
+Se você for na **IU da documentação da API** em `/docs` você poderá ver a **documentação** para cookies das suas *operações de rotas*.
-Mas mesmo que você **adicionar os dados** e clicar em "Executar", pelo motivo da IU dos documentos trabalharem com **JavaScript**, os cookies não serão enviados, e você verá uma mensagem de **erro** como se você não tivesse escrito nenhum dado.
+Mas mesmo que você **adicionar os dados** e clicar em "Executar", pelo motivo da IU da documentação trabalhar com **JavaScript**, os cookies não serão enviados, e você verá uma mensagem de **erro** como se você não tivesse escrito nenhum dado.
///
-## Proibir Cookies Adicionais
+## Proibir Cookies Adicionais { #forbid-extra-cookies }
Em alguns casos especiais (provavelmente não muito comuns), você pode querer **restringir** os cookies que você deseja receber.
-Agora a sua API possui o poder de contrar o seu próprio consentimento de cookie. 🤪🍪
+Agora a sua API possui o poder de controlar o seu próprio consentimento de cookie. 🤪🍪
+Você pode utilizar a configuração do modelo Pydantic para `proibir` qualquer campo `extra`:
- Você pode utilizar a configuração do modelo Pydantic para `proibir` qualquer campo `extra`.
-
-
-{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
Se o cliente tentar enviar alguns **cookies extras**, eles receberão um retorno de **erro**.
Coitados dos banners de cookies com todo o seu esforço para obter o seu consentimento para a API rejeitá-lo. 🍪
-Por exemplo, se o cliente tentar enviar um cookie `santa_tracker` com o valor de `good-list-please`, o cliente receberá uma resposta de **erro** informando que o cookie `santa_tracker` is not allowed:
+Por exemplo, se o cliente tentar enviar um cookie `santa_tracker` com o valor de `good-list-please`, o cliente receberá uma resposta de **erro** informando que o `santa_tracker` cookie não é permitido:
```json
{
@@ -73,6 +71,6 @@ Por exemplo, se o cliente tentar enviar um cookie `santa_tracker` com o valor de
}
```
-## Resumo
+## Resumo { #summary }
Você consegue utilizar **modelos Pydantic** para declarar **cookies** no **FastAPI**. 😎
diff --git a/docs/pt/docs/tutorial/cookie-params.md b/docs/pt/docs/tutorial/cookie-params.md
index da85d796e..5540a67d2 100644
--- a/docs/pt/docs/tutorial/cookie-params.md
+++ b/docs/pt/docs/tutorial/cookie-params.md
@@ -1,20 +1,19 @@
-# Parâmetros de Cookie
+# Parâmetros de Cookie { #cookie-parameters }
-Você pode definir parâmetros de Cookie da mesma maneira que define paramêtros com `Query` e `Path`.
+Você pode definir parâmetros de Cookie da mesma maneira que define parâmetros com `Query` e `Path`.
-## Importe `Cookie`
+## Importe `Cookie` { #import-cookie }
Primeiro importe `Cookie`:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## Declare parâmetros de `Cookie`
+## Declare parâmetros de `Cookie` { #declare-cookie-parameters }
-Então declare os paramêtros de cookie usando a mesma estrutura que em `Path` e `Query`.
+Então declare os parâmetros de cookie usando a mesma estrutura que em `Path` e `Query`.
Você pode definir o valor padrão, assim como todas as validações extras ou parâmetros de anotação:
-
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
/// note | Detalhes Técnicos
@@ -31,6 +30,16 @@ Para declarar cookies, você precisa usar `Cookie`, pois caso contrário, os par
///
-## Recapitulando
+/// info | Informação
+
+Tenha em mente que, como os **navegadores lidam com cookies** de maneiras especiais e nos bastidores, eles **não** permitem facilmente que o **JavaScript** os acesse.
+
+Se você for à **interface de documentação da API** em `/docs`, poderá ver a **documentação** de cookies para suas *operações de rota*.
+
+Mas mesmo que você **preencha os dados** e clique em "Execute", como a interface de documentação funciona com **JavaScript**, os cookies não serão enviados e você verá uma mensagem de **erro** como se você não tivesse escrito nenhum valor.
+
+///
+
+## Recapitulando { #recap }
Declare cookies com `Cookie`, usando o mesmo padrão comum que utiliza-se em `Query` e `Path`.
diff --git a/docs/pt/docs/tutorial/cors.md b/docs/pt/docs/tutorial/cors.md
index 0ab07a3c2..0f99db888 100644
--- a/docs/pt/docs/tutorial/cors.md
+++ b/docs/pt/docs/tutorial/cors.md
@@ -1,8 +1,8 @@
-# CORS (Cross-Origin Resource Sharing)
+# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
CORS ou "Cross-Origin Resource Sharing" refere-se às situações em que um frontend rodando em um navegador possui um código JavaScript que se comunica com um backend, e o backend está em uma "origem" diferente do frontend.
-## Origem
+## Origem { #origin }
Uma origem é a combinação de protocolo (`http`, `https`), domínio (`myapp.com`, `localhost`, `localhost.tiangolo.com`), e porta (`80`, `443`, `8080`).
@@ -12,27 +12,27 @@ Então, todos estes são origens diferentes:
* `https://localhost`
* `http://localhost:8080`
-Mesmo se todos estiverem em `localhost`, eles usam diferentes protocolos e portas, portanto, são "origens" diferentes.
+Mesmo se todos estiverem em `localhost`, eles usam diferentes protocolos ou portas, portanto, são "origens" diferentes.
-## Passos
+## Passos { #steps }
-Então, digamos que você tenha um frontend rodando no seu navegador em `http://localhost:8080`, e seu JavaScript esteja tentando se comunicar com um backend rodando em http://localhost (como não especificamos uma porta, o navegador assumirá a porta padrão `80`).
+Então, digamos que você tenha um frontend rodando no seu navegador em `http://localhost:8080`, e seu JavaScript esteja tentando se comunicar com um backend rodando em `http://localhost` (como não especificamos uma porta, o navegador assumirá a porta padrão `80`).
-Portanto, o navegador irá enviar uma requisição HTTP `OPTIONS` ao backend, e se o backend enviar os cabeçalhos apropriados autorizando a comunicação a partir de uma origem diferente (`http://localhost:8080`) então o navegador deixará o JavaScript no frontend enviar sua requisição para o backend.
+Portanto, o navegador enviará uma requisição HTTP `OPTIONS` ao backend `:80`, e se o backend enviar os cabeçalhos apropriados autorizando a comunicação a partir dessa origem diferente (`http://localhost:8080`), então o navegador `:8080` permitirá que o JavaScript no frontend envie sua requisição para o backend `:80`.
-Para conseguir isso, o backend deve ter uma lista de "origens permitidas".
+Para conseguir isso, o backend `:80` deve ter uma lista de "origens permitidas".
-Neste caso, ele terá que incluir `http://localhost:8080` para o frontend funcionar corretamente.
+Neste caso, a lista terá que incluir `http://localhost:8080` para o frontend `:8080` funcionar corretamente.
-## Curingas
+## Curingas { #wildcards }
-É possível declarar uma lista com `"*"` (um "curinga") para dizer que tudo está permitido.
+É possível declarar a lista como `"*"` (um "curinga") para dizer que tudo está permitido.
Mas isso só permitirá certos tipos de comunicação, excluindo tudo que envolva credenciais: cookies, cabeçalhos de autorização como aqueles usados com Bearer Tokens, etc.
Então, para que tudo funcione corretamente, é melhor especificar explicitamente as origens permitidas.
-## Usar `CORSMiddleware`
+## Usar `CORSMiddleware` { #use-corsmiddleware }
Você pode configurá-lo em sua aplicação **FastAPI** usando o `CORSMiddleware`.
@@ -46,9 +46,9 @@ Você também pode especificar se o seu backend permite:
* Métodos HTTP específicos (`POST`, `PUT`) ou todos eles com o curinga `"*"`.
* Cabeçalhos HTTP específicos ou todos eles com o curinga `"*"`.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
-Os parâmetros padrão usados pela implementação `CORSMiddleware` são restritivos por padrão, então você precisará habilitar explicitamente as origens, métodos ou cabeçalhos específicos para que os navegadores tenham permissão para usá-los em um contexto de domínios diferentes.
+Os parâmetros padrão usados pela implementação `CORSMiddleware` são restritivos por padrão, então você precisará habilitar explicitamente as origens, métodos ou cabeçalhos específicos para que os navegadores tenham permissão para usá-los em um contexto cross domain.
Os seguintes argumentos são suportados:
@@ -56,27 +56,30 @@ Os seguintes argumentos são suportados:
* `allow_origin_regex` - Uma string regex para corresponder às origens que devem ter permissão para fazer requisições de origem cruzada. Por exemplo, `'https://.*\.example\.org'`.
* `allow_methods` - Uma lista de métodos HTTP que devem ser permitidos para requisições de origem cruzada. O padrão é `['GET']`. Você pode usar `['*']` para permitir todos os métodos padrão.
* `allow_headers` - Uma lista de cabeçalhos de solicitação HTTP que devem ter suporte para requisições de origem cruzada. O padrão é `[]`. Você pode usar `['*']` para permitir todos os cabeçalhos. Os cabeçalhos `Accept`, `Accept-Language`, `Content-Language` e `Content-Type` são sempre permitidos para requisições CORS simples.
-* `allow_credentials` - Indica que os cookies devem ser suportados para requisições de origem cruzada. O padrão é `False`. Além disso, `allow_origins` não pode ser definido como `['*']` para que as credenciais sejam permitidas, as origens devem ser especificadas.
+* `allow_credentials` - Indica que os cookies devem ser suportados para requisições de origem cruzada. O padrão é `False`.
+
+ Nenhum de `allow_origins`, `allow_methods` e `allow_headers` pode ser definido como `['*']` se `allow_credentials` estiver definido como `True`. Todos eles devem ser especificados explicitamente.
+
* `expose_headers` - Indica quaisquer cabeçalhos de resposta que devem ser disponibilizados ao navegador. O padrão é `[]`.
* `max_age` - Define um tempo máximo em segundos para os navegadores armazenarem em cache as respostas CORS. O padrão é `600`.
O middleware responde a dois tipos específicos de solicitação HTTP...
-### Requisições CORS pré-voo (preflight)
+### Requisições CORS pré-voo (preflight) { #cors-preflight-requests }
Estas são quaisquer solicitações `OPTIONS` com cabeçalhos `Origin` e `Access-Control-Request-Method`.
Nesse caso, o middleware interceptará a solicitação recebida e responderá com cabeçalhos CORS apropriados e uma resposta `200` ou `400` para fins informativos.
-### Requisições Simples
+### Requisições Simples { #simple-requests }
Qualquer solicitação com um cabeçalho `Origin`. Neste caso, o middleware passará a solicitação normalmente, mas incluirá cabeçalhos CORS apropriados na resposta.
-## Mais informações
+## Mais informações { #more-info }
-Para mais informações CORS, acesse Mozilla CORS documentation.
+Para mais informações sobre CORS, consulte a documentação do CORS da Mozilla.
-/// note | Detalhes técnicos
+/// note | Detalhes Técnicos
Você também pode usar `from starlette.middleware.cors import CORSMiddleware`.
diff --git a/docs/pt/docs/tutorial/debugging.md b/docs/pt/docs/tutorial/debugging.md
index 67b764457..e39c7d128 100644
--- a/docs/pt/docs/tutorial/debugging.md
+++ b/docs/pt/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# Depuração
+# Depuração { #debugging }
Você pode conectar o depurador no seu editor, por exemplo, com o Visual Studio Code ou PyCharm.
-## Chamar `uvicorn`
+## Chamar `uvicorn` { #call-uvicorn }
-Em seu aplicativo FastAPI, importe e execute `uvicorn` diretamente:
+Em sua aplicação FastAPI, importe e execute `uvicorn` diretamente:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### Sobre `__name__ == "__main__"`
+### Sobre `__name__ == "__main__"` { #about-name-main }
O objetivo principal de `__name__ == "__main__"` é ter algum código que seja executado quando seu arquivo for chamado com:
@@ -26,7 +26,7 @@ mas não é chamado quando outro arquivo o importa, como em:
from myapp import app
```
-#### Mais detalhes
+#### Mais detalhes { #more-details }
Digamos que seu arquivo se chama `myapp.py`.
@@ -78,9 +78,9 @@ Para mais informações, consulte
-## Pegando um Atalho
+## Pegando um Atalho { #shortcut }
Mas você pode ver que temos uma repetição do código neste exemplo, escrevendo `CommonQueryParams` duas vezes:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -205,7 +205,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ non-Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Dica
@@ -225,7 +225,7 @@ Para esses casos específicos, você pode fazer o seguinte:
Em vez de escrever:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -233,7 +233,7 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.8+ non-Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Dica
@@ -249,7 +249,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
...escreva:
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends()]
@@ -257,7 +257,7 @@ commons: Annotated[CommonQueryParams, Depends()]
////
-//// tab | Python 3.8 non-Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Dica
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 d7d31bb45..ee8a58dc2 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
@@ -1,4 +1,4 @@
-# Dependências em decoradores de operações de rota
+# Dependências em decoradores de operações de rota { #dependencies-in-path-operation-decorators }
Em alguns casos você não precisa necessariamente retornar o valor de uma dependência dentro de uma *função de operação de rota*.
@@ -8,7 +8,7 @@ Mas você ainda precisa que ela seja executada/resolvida.
Para esses casos, em vez de declarar um parâmetro em uma *função de operação de rota* com `Depends`, você pode adicionar um argumento `dependencies` do tipo `list` ao decorador da operação de rota.
-## Adicionando `dependencies` ao decorador da operação de rota
+## Adicione `dependencies` ao decorador da operação de rota { #add-dependencies-to-the-path-operation-decorator }
O *decorador da operação de rota* recebe um argumento opcional `dependencies`.
@@ -22,7 +22,7 @@ Essas dependências serão executadas/resolvidas da mesma forma que dependência
Alguns editores de texto checam parâmetros de funções não utilizados, e os mostram como erros.
-Utilizando `dependencies` no *decorador da operação de rota* você pode garantir que elas serão executadas enquanto evita errors de editores/ferramentas.
+Utilizando `dependencies` no *decorador da operação de rota* você pode garantir que elas serão executadas enquanto evita erros de editores/ferramentas.
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.
@@ -30,29 +30,29 @@ Isso também pode ser útil para evitar confundir novos desenvolvedores que ao v
/// info | Informação
-Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Keys` e `X-Token`.
+Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Key` 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
+## Erros das dependências e valores de retorno { #dependencies-errors-and-return-values }
Você pode utilizar as mesmas *funções* de dependências que você usaria normalmente.
-### Requisitos de Dependências
+### Requisitos de Dependências { #dependency-requirements }
Dependências podem declarar requisitos de requisições (como cabeçalhos) ou outras subdependências:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### Levantando exceções
+### Levantar exceções { #raise-exceptions }
-Essas dependências podem levantar exceções, da mesma forma que dependências comuns:
+Essas dependências podem `raise` exceções, da mesma forma que dependências comuns:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### Valores de retorno
+### Valores de retorno { #return-values }
E elas também podem ou não retornar valores, eles não serão utilizados.
@@ -60,10 +60,10 @@ Então, você pode reutilizar uma dependência comum (que retorna um valor) que
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## Dependências para um grupo de *operações de rota*
+## Dependências para um grupo de *operações de rota* { #dependencies-for-a-group-of-path-operations }
-Mais a frente, quando você ler sobre como estruturar aplicações maiores ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possivelmente com múltiplos arquivos, você aprenderá a declarar um único parâmetro `dependencies` para um grupo de *operações de rota*.
+Mais a frente, quando você ler sobre como estruturar aplicações maiores ([Aplicações maiores - Múltiplos arquivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possivelmente com múltiplos arquivos, você aprenderá a declarar um único parâmetro `dependencies` para um grupo de *operações de rota*.
-## Dependências globais
+## Dependências globais { #global-dependencies }
-No próximo passo veremos como adicionar dependências para uma aplicação `FastAPI` inteira, para que ela seja aplicada em toda *operação de rota*.
+No próximo passo veremos como adicionar dependências para uma aplicação `FastAPI` inteira, para que elas sejam aplicadas em toda *operação 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 eaf711197..367873013 100644
--- a/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/pt/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,12 +1,12 @@
-# Dependências com yield
+# Dependências com yield { #dependencies-with-yield }
-O FastAPI possui suporte para dependências que realizam alguns passos extras ao finalizar.
+O **FastAPI** possui suporte para dependências que realizam alguns passos extras ao finalizar.
Para fazer isso, utilize `yield` em vez de `return`, e escreva os passos extras (código) depois.
/// tip | Dica
-Garanta que `yield` é utilizado apenas uma vez.
+Garanta utilizar `yield` apenas uma vez por dependência.
///
@@ -23,21 +23,21 @@ Na realidade, o FastAPI utiliza esses dois decoradores internamente.
///
-## Uma dependência de banco de dados com `yield`
+## Uma dependência de banco de dados com `yield` { #a-database-dependency-with-yield }
-Por exemplo, você poderia utilizar isso para criar uma sessão do banco de dados, e fechá-la após terminar sua operação.
+Por exemplo, você poderia utilizar isso para criar uma sessão do banco de dados, e fechá-la após terminar.
-Apenas o código anterior a declaração com `yield` e o código contendo essa declaração são executados antes de criar uma resposta.
+Apenas o código anterior à declaração com `yield` e o código contendo essa declaração são executados antes de criar uma resposta:
-{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[2:4] *}
-O valor gerado (yielded) é o que é injetado nas *operações de rota* e outras dependências.
+O valor gerado (yielded) é o que é injetado nas *operações de rota* e outras dependências:
-{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[4] *}
-O código após o `yield` é executado após a resposta ser entregue:
+O código após o `yield` é executado após a resposta:
-{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[5:6] *}
/// tip | Dica
@@ -47,21 +47,19 @@ O **FastAPI** saberá o que fazer com cada uma, da mesma forma que as dependênc
///
-## Uma dependência com `yield` e `try`
+## Uma dependência com `yield` e `try` { #a-dependency-with-yield-and-try }
Se você utilizar um bloco `try` em uma dependência com `yield`, você irá capturar qualquer exceção que for lançada enquanto a dependência é utilizada.
-Por exemplo, se algum código em um certo momento no meio da operação, em outra dependência ou em uma *operação de rota*, fizer um "rollback" de uma transação de banco de dados ou causar qualquer outro erro, você irá capturar a exceção em sua dependência.
+Por exemplo, se algum código em um certo momento no meio, em outra dependência ou em uma *operação de rota*, fizer um "rollback" de uma transação de banco de dados ou causar qualquer outra exceção, você irá capturar a exceção em sua dependência.
Então, você pode procurar por essa exceção específica dentro da dependência com `except AlgumaExcecao`.
Da mesma forma, você pode utilizar `finally` para garantir que os passos de saída são executados, com ou sem exceções.
-```python hl_lines="3 5"
-{!../../docs_src/dependencies/tutorial007.py!}
-```
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[3,5] *}
-## Subdependências com `yield`
+## Subdependências com `yield` { #sub-dependencies-with-yield }
Você pode ter subdependências e "árvores" de subdependências de qualquer tamanho e forma, e qualquer uma ou todas elas podem utilizar `yield`.
@@ -69,73 +67,17 @@ O **FastAPI** garantirá que o "código de saída" em cada dependência com `yie
Por exemplo, `dependency_c` pode depender de `dependency_b`, e `dependency_b` depender de `dependency_a`:
-//// tab | python 3.9+
-
-```python hl_lines="6 14 22"
-{!> ../../docs_src/dependencies/tutorial008_an_py39.py!}
-```
-
-////
-
-//// tab | python 3.8+
-
-```python hl_lines="5 13 21"
-{!> ../../docs_src/dependencies/tutorial008_an.py!}
-```
-
-////
-
-//// tab | python 3.8+ non-annotated
-
-/// tip | Dica
-
-Utilize a versão com `Annotated` se possível.
-
-///
-
-```python hl_lines="4 12 20"
-{!> ../../docs_src/dependencies/tutorial008.py!}
-```
-
-////
+{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[6,14,22] *}
E todas elas podem utilizar `yield`.
-Neste caso, `dependency_c` precisa que o valor de `dependency_b` (nomeada de `dep_b` aqui) continue disponível para executar seu código de saída.
+Neste caso, `dependency_c`, para executar seu código de saída, precisa que o valor de `dependency_b` (nomeado de `dep_b` aqui) continue disponível.
-E, por outro lado, `dependency_b` precisa que o valor de `dependency_a` (nomeada de `dep_a`) continue disponível para executar seu código de saída.
+E, por outro lado, `dependency_b` precisa que o valor de `dependency_a` (nomeado de `dep_a`) esteja disponível para executar seu código de saída.
-//// tab | python 3.9+
+{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[18:19,26:27] *}
-```python hl_lines="18-19 26-27"
-{!> ../../docs_src/dependencies/tutorial008_an_py39.py!}
-```
-
-////
-
-//// tab | python 3.8+
-
-```python hl_lines="17-18 25-26"
-{!> ../../docs_src/dependencies/tutorial008_an.py!}
-```
-
-////
-
-//// tab | python 3.8+ non-annotated
-
-/// tip | Dica
-
-Utilize a versão com `Annotated` se possível.
-
-///
-
-```python hl_lines="16-17 24-25"
-{!> ../../docs_src/dependencies/tutorial008.py!}
-```
-
-////
-
-Da mesma forma, você pode ter algumas dependências com `yield` e outras com `return` e ter uma relação de dependência entre algumas dos dois tipos.
+Da mesma forma, você pode ter algumas dependências com `yield` e outras com `return` e ter uma relação de dependência entre algumas das duas.
E você poderia ter uma única dependência que precisa de diversas outras dependências com `yield`, etc.
@@ -151,83 +93,45 @@ O **FastAPI** utiliza eles internamente para alcançar isso.
///
-## Dependências com `yield` e `httpexception`
+## Dependências com `yield` e `HTTPException` { #dependencies-with-yield-and-httpexception }
-Você viu que dependências podem ser utilizadas com `yield` e podem incluir blocos `try` para capturar exceções.
+Você viu que pode usar dependências com `yield` e ter blocos `try` que tentam executar algum código e depois executar algum código de saída com `finally`.
-Da mesma forma, você pode lançar uma `httpexception` ou algo parecido no código de saída, após o `yield`
+Você também pode usar `except` para capturar a exceção que foi levantada e fazer algo com ela.
+
+Por exemplo, você pode levantar uma exceção diferente, como `HTTPException`.
/// tip | Dica
-Essa é uma técnica relativamente avançada, e na maioria dos casos você não precisa dela totalmente, já que você pode lançar exceções (incluindo `httpexception`) dentro do resto do código da sua aplicação, por exemplo, em uma *função de operação de rota*.
+Essa é uma técnica relativamente avançada, e na maioria dos casos você não vai precisar dela, já que você pode levantar exceções (incluindo `HTTPException`) dentro do resto do código da sua aplicação, por exemplo, na *função de operação de rota*.
Mas ela existe para ser utilizada caso você precise. 🤓
///
-//// tab | python 3.9+
-
-```python hl_lines="18-22 31"
-{!> ../../docs_src/dependencies/tutorial008b_an_py39.py!}
-```
-
-////
-
-//// tab | python 3.8+
-
-```python hl_lines="17-21 30"
-{!> ../../docs_src/dependencies/tutorial008b_an.py!}
-```
-
-////
-
-//// tab | python 3.8+ non-annotated
-
-/// tip | Dica
-
-Utilize a versão com `Annotated` se possível.
-
-///
-
-```python hl_lines="16-20 29"
-{!> ../../docs_src/dependencies/tutorial008b.py!}
-```
+{* ../../docs_src/dependencies/tutorial008b_an_py39.py hl[18:22,31] *}
-////
+Se você quiser capturar exceções e criar uma resposta personalizada com base nisso, crie um [Manipulador de Exceções Customizado](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
-Uma alternativa que você pode utilizar para capturar exceções (e possivelmente lançar outra HTTPException) é criar um [Manipulador de Exceções Customizado](../handling-errors.md#instalando-manipuladores-de-excecoes-customizados){.internal-link target=_blank}.
+## Dependências com `yield` e `except` { #dependencies-with-yield-and-except }
-## Dependências com `yield` e `except`
-
-Se você capturar uma exceção com `except` em uma dependência que utilize `yield` e ela não for levantada novamente (ou uma nova exceção for levantada), o FastAPI não será capaz de identifcar que houve uma exceção, da mesma forma que aconteceria com Python puro:
+Se você capturar uma exceção com `except` em uma dependência que utilize `yield` e ela não for levantada novamente (ou uma nova exceção for levantada), o FastAPI não será capaz de identificar que houve uma exceção, da mesma forma que aconteceria com Python puro:
{* ../../docs_src/dependencies/tutorial008c_an_py39.py hl[15:16] *}
Neste caso, o cliente irá ver uma resposta *HTTP 500 Internal Server Error* como deveria acontecer, já que não estamos levantando nenhuma `HTTPException` ou coisa parecida, mas o servidor **não terá nenhum log** ou qualquer outra indicação de qual foi o erro. 😱
-### Sempre levante (`raise`) exceções em Dependências com `yield` e `except`
+### Sempre levante (`raise`) em Dependências com `yield` e `except` { #always-raise-in-dependencies-with-yield-and-except }
-Se você capturar uma exceção em uma dependência com `yield`, a menos que você esteja levantando outra `HTTPException` ou coisa parecida, você deveria relançar a exceção original.
+Se você capturar uma exceção em uma dependência com `yield`, a menos que você esteja levantando outra `HTTPException` ou coisa parecida, **você deve relançar a exceção original**.
Você pode relançar a mesma exceção utilizando `raise`:
{* ../../docs_src/dependencies/tutorial008d_an_py39.py hl[17] *}
-//// tab | python 3.8+ non-annotated
-
-/// tip | Dica
-
-Utilize a versão com `Annotated` se possível.
-
-///
-
-{* ../../docs_src/dependencies/tutorial008d.py hl[15] *}
-
-////
-
Agora o cliente irá receber a mesma resposta *HTTP 500 Internal Server Error*, mas o servidor terá nosso `InternalError` personalizado nos logs. 😎
-## Execução de dependências com `yield`
+## Execução de dependências com `yield` { #execution-of-dependencies-with-yield }
A sequência de execução é mais ou menos como esse diagrama. O tempo passa do topo para baixo. E cada coluna é uma das partes interagindo ou executando código.
@@ -270,57 +174,69 @@ participant tasks as Tarefas de Background
Apenas **uma resposta** será enviada para o cliente. Ela pode ser uma das respostas de erro, ou então a resposta da *operação de rota*.
-Após uma dessas respostas ser enviada, nenhuma outra resposta pode ser enviada
+Após uma dessas respostas ser enviada, nenhuma outra resposta pode ser enviada.
///
/// tip | Dica
-Esse diagrama mostra `HttpException`, mas você pode levantar qualquer outra exceção que você capture em uma dependência com `yield` ou um [Manipulador de exceções personalizado](../handling-errors.md#instalando-manipuladores-de-excecoes-customizados){.internal-link target=_blank}.
-
-Se você lançar qualquer exceção, ela será passada para as dependências com yield, inlcuindo a `HTTPException`. Na maioria dos casos você vai querer relançar essa mesma exceção ou uma nova a partir da dependência com `yield` para garantir que ela seja tratada adequadamente.
+Se você levantar qualquer exceção no código da *função de operação de rota*, ela será passada para as dependências com `yield`, incluindo `HTTPException`. Na maioria dos casos, você vai querer relançar essa mesma exceção ou uma nova a partir da dependência com `yield` para garantir que ela seja tratada adequadamente.
///
-## Dependências com `yield`, `HTTPException`, `except` e Tarefas de Background
-
-/// warning | Aviso
+## Saída antecipada e `scope` { #early-exit-and-scope }
-Você provavelmente não precisa desses detalhes técnicos, você pode pular essa seção e continuar na próxima seção abaixo.
+Normalmente, o código de saída das dependências com `yield` é executado **após a resposta** ser enviada ao cliente.
-Esses detalhes são úteis principalmente se você estiver usando uma versão do FastAPI anterior à 0.106.0 e utilizando recursos de dependências com `yield` em tarefas de background.
+Mas se você sabe que não precisará usar a dependência depois de retornar da *função de operação de rota*, você pode usar `Depends(scope="function")` para dizer ao FastAPI que deve fechar a dependência depois que a *função de operação de rota* retornar, mas **antes** de a **resposta ser enviada**.
-///
+{* ../../docs_src/dependencies/tutorial008e_an_py39.py hl[12,16] *}
-### Dependências com `yield` e `except`, Detalhes Técnicos
+`Depends()` recebe um parâmetro `scope` que pode ser:
-Antes do FastAPI 0.110.0, se você utilizasse uma dependência com `yield`, e então capturasse uma dependência com `except` nessa dependência, caso a exceção não fosse relançada, ela era automaticamente lançada para qualquer manipulador de exceções ou o manipulador de erros interno do servidor.
+* `"function"`: iniciar a dependência antes da *função de operação de rota* que trata a requisição, encerrar a dependência depois que a *função de operação de rota* termina, mas **antes** de a resposta ser enviada de volta ao cliente. Assim, a função da dependência será executada **em torno** da *função de operação de rota*.
+* `"request"`: iniciar a dependência antes da *função de operação de rota* que trata a requisição (semelhante a quando se usa `"function"`), mas encerrar **depois** que a resposta é enviada de volta ao cliente. Assim, a função da dependência será executada **em torno** do ciclo de **requisição** e resposta.
-Isso foi modificado na versão 0.110.0 para consertar o consumo de memória não controlado das exceções relançadas automaticamente sem um manipulador (erros internos do servidor), e para manter o comportamento consistente com o código Python tradicional.
+Se não for especificado e a dependência tiver `yield`, ela terá `scope` igual a `"request"` por padrão.
-### Tarefas de Background e Dependências com `yield`, Detalhes Técnicos
+### `scope` para subdependências { #scope-for-sub-dependencies }
-Antes do FastAPI 0.106.0, levantar exceções após um `yield` não era possível, o código de saída nas dependências com `yield` era executado *após* a resposta ser enviada, então os [Manipuladores de Exceções](../handling-errors.md#instalando-manipuladores-de-excecoes-customizados){.internal-link target=_blank} já teriam executado.
+Quando você declara uma dependência com `scope="request"` (o padrão), qualquer subdependência também precisa ter `scope` igual a `"request"`.
-Isso foi implementado dessa forma principalmente para permitir que os mesmos objetos fornecidos ("yielded") pelas dependências dentro de tarefas de background fossem reutilizados, por que o código de saída era executado antes das tarefas de background serem finalizadas.
+Mas uma dependência com `scope` igual a `"function"` pode ter dependências com `scope` igual a `"function"` e com `scope` igual a `"request"`.
-Ainda assim, como isso exigiria esperar que a resposta navegasse pela rede enquanto mantia ativo um recurso desnecessário na dependência com yield (por exemplo, uma conexão com banco de dados), isso mudou na versão 0.106.0 do FastAPI.
+Isso porque qualquer dependência precisa conseguir executar seu código de saída antes das subdependências, pois pode ainda precisar usá-las durante seu código de saída.
-/// tip | Dica
-
-Adicionalmente, uma tarefa de background é, normalmente, um conjunto de lógicas independentes que devem ser manipuladas separadamente, com seus próprios recursos (e.g. sua própria conexão com banco de dados).
+```mermaid
+sequenceDiagram
-Então, dessa forma você provavelmente terá um código mais limpo.
+participant client as Cliente
+participant dep_req as Dep scope="request"
+participant dep_func as Dep scope="function"
+participant operation as Operação de Rota
-///
+ client ->> dep_req: Iniciar requisição
+ Note over dep_req: Executar código até o yield
+ dep_req ->> dep_func: Passar dependência
+ Note over dep_func: Executar código até o yield
+ dep_func ->> operation: Executar operação de rota com dependência
+ operation ->> dep_func: Retornar da operação de rota
+ Note over dep_func: Executar código após o yield
+ Note over dep_func: ✅ Dependência fechada
+ dep_func ->> client: Enviar resposta ao cliente
+ Note over client: Resposta enviada
+ Note over dep_req: Executar código após o yield
+ Note over dep_req: ✅ Dependência fechada
+```
-Se você costumava depender desse comportamento, agora você precisa criar os recursos para uma tarefa de background dentro dela mesma, e usar internamente apenas dados que não dependam de recursos de dependências com `yield`.
+## Dependências com `yield`, `HTTPException`, `except` e Tarefas de Background { #dependencies-with-yield-httpexception-except-and-background-tasks }
-Por exemplo, em vez de utilizar a mesma sessão do banco de dados, você criaria uma nova sessão dentro da tarefa de background, e você obteria os objetos do banco de dados utilizando essa nova sessão. E então, em vez de passar o objeto obtido do banco de dados como um parâmetro para a função da tarefa de background, você passaria o ID desse objeto e buscaria ele novamente dentro da função da tarefa de background.
+Dependências com `yield` evoluíram ao longo do tempo para cobrir diferentes casos de uso e corrigir alguns problemas.
-## Gerenciadores de contexto
+Se você quiser ver o que mudou em diferentes versões do FastAPI, você pode ler mais sobre isso no guia avançado, em [Dependências Avançadas - Dependências com `yield`, `HTTPException`, `except` e Tarefas de Background](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks){.internal-link target=_blank}.
+## Gerenciadores de contexto { #context-managers }
-### O que são gerenciadores de contexto
+### O que são "Gerenciadores de Contexto" { #what-are-context-managers }
"Gerenciadores de Contexto" são qualquer um dos objetos Python que podem ser utilizados com a declaração `with`.
@@ -338,9 +254,9 @@ Quando o bloco `with` finaliza, ele se certifica de fechar o arquivo, mesmo que
Quando você cria uma dependência com `yield`, o **FastAPI** irá criar um gerenciador de contexto internamente para ela, e combiná-lo com algumas outras ferramentas relacionadas.
-### Utilizando gerenciadores de contexto em dependências com `yield`
+### Utilizando gerenciadores de contexto em dependências com `yield` { #using-context-managers-in-dependencies-with-yield }
-/// warning | Aviso
+/// warning | Atenção
Isso é uma ideia mais ou menos "avançada".
@@ -348,18 +264,18 @@ Se você está apenas iniciando com o **FastAPI** você pode querer pular isso p
///
-Em python, você pode criar Gerenciadores de Contexto ao criar uma classe com dois métodos: `__enter__()` e `__exit__()`.
+Em Python, você pode criar Gerenciadores de Contexto ao criar uma classe com dois métodos: `__enter__()` e `__exit__()`.
-Você também pode usá-los dentro de dependências com `yield` do **FastAPI** ao utilizar `with` ou `async with` dentro da função da dependência:
+Você também pode usá-los dentro de dependências com `yield` do **FastAPI** ao utilizar
+`with` ou `async with` dentro da função da dependência:
-{* ../../docs_src/dependencies/tutorial010.py hl[1:9,13] *}
+{* ../../docs_src/dependencies/tutorial010_py39.py hl[1:9,13] *}
/// tip | Dica
Outra forma de criar um gerenciador de contexto é utilizando:
* `@contextlib.contextmanager` ou
-
* `@contextlib.asynccontextmanager`
Para decorar uma função com um único `yield`.
diff --git a/docs/pt/docs/tutorial/dependencies/global-dependencies.md b/docs/pt/docs/tutorial/dependencies/global-dependencies.md
index a9a7e3b89..4d6e8a69a 100644
--- a/docs/pt/docs/tutorial/dependencies/global-dependencies.md
+++ b/docs/pt/docs/tutorial/dependencies/global-dependencies.md
@@ -1,15 +1,16 @@
-# Dependências Globais
+# Dependências Globais { #global-dependencies }
-Para alguns tipos de aplicação específicos você pode querer adicionar dependências para toda a aplicação.
+Para alguns tipos de aplicação você pode querer adicionar dependências para toda a aplicação.
-De forma semelhante a [adicionar dependências (`dependencies`) em *decoradores de operação de rota*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, você pode adicioná-las à aplicação `FastAPI`.
+De forma semelhante a [adicionar `dependencies` aos *decoradores de operação de rota*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, você pode adicioná-las à aplicação `FastAPI`.
Nesse caso, elas serão aplicadas a todas as *operações de rota* da aplicação:
-{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[16] *}
+{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[17] *}
-E todos os conceitos apresentados na sessão sobre [adicionar dependências em *decoradores de operação de rota*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} ainda se aplicam, mas nesse caso, para todas as *operações de rota* da aplicação.
-## Dependências para conjuntos de *operações de rota*
+E todos os conceitos apresentados na seção sobre [adicionar `dependencies` aos *decoradores de operação de rota*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} ainda se aplicam, mas nesse caso, para todas as *operações de rota* da aplicação.
-Mais para a frente, quando você ler sobre como estruturar aplicações maiores ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possivelmente com múltiplos arquivos, você irá aprender a declarar um único parâmetro `dependencies` para um conjunto de *operações de rota*.
+## Dependências para conjuntos de *operações de rota* { #dependencies-for-groups-of-path-operations }
+
+Mais para a frente, quando você ler sobre como estruturar aplicações maiores ([Aplicações Maiores - Múltiplos Arquivos](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possivelmente com múltiplos arquivos, você irá aprender a declarar um único parâmetro `dependencies` para um conjunto de *operações de rota*.
diff --git a/docs/pt/docs/tutorial/dependencies/index.md b/docs/pt/docs/tutorial/dependencies/index.md
index 1500b715a..bdfe1ac39 100644
--- a/docs/pt/docs/tutorial/dependencies/index.md
+++ b/docs/pt/docs/tutorial/dependencies/index.md
@@ -1,10 +1,10 @@
-# Dependências
+# Dependências { #dependencies }
-O **FastAPI** possui um poderoso, mas intuitivo sistema de **Injeção de Dependência**.
+O **FastAPI** possui um poderoso, mas intuitivo sistema de **Injeção de Dependência**.
Esse sistema foi pensado para ser fácil de usar, e permitir que qualquer desenvolvedor possa integrar facilmente outros componentes ao **FastAPI**.
-## O que é "Injeção de Dependência"
+## O que é "Injeção de Dependência" { #what-is-dependency-injection }
**"Injeção de Dependência"** no mundo da programação significa, que existe uma maneira de declarar no seu código (nesse caso, suas *funções de operação de rota*) para declarar as coisas que ele precisa para funcionar e que serão utilizadas: "dependências".
@@ -19,13 +19,13 @@ Isso é bastante útil quando você precisa:
Tudo isso, enquanto minimizamos a repetição de código.
-## Primeiros passos
+## Primeiros passos { #first-steps }
Vamos ver um exemplo simples. Tão simples que não será muito útil, por enquanto.
Mas dessa forma podemos focar em como o sistema de **Injeção de Dependência** funciona.
-### Criando uma dependência, ou "injetável"
+### Criando uma dependência, ou "injetável" { #create-a-dependency-or-dependable }
Primeiro vamos focar na dependência.
@@ -57,15 +57,15 @@ FastAPI passou a suportar a notação `Annotated` (e começou a recomendá-la) n
Se você utiliza uma versão anterior, ocorrerão erros ao tentar utilizar `Annotated`.
-Certifique-se de [Atualizar a versão do FastAPI](../../deployment/versions.md#atualizando-as-versoes-do-fastapi){.internal-link target=_blank} para pelo menos 0.95.1 antes de usar `Annotated`.
+Certifique-se de [Atualizar a versão do FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} para pelo menos 0.95.1 antes de usar `Annotated`.
///
-### Importando `Depends`
+### Importando `Depends` { #import-depends }
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
-### Declarando a dependência, no "dependente"
+### Declarando a dependência, no "dependente" { #declare-the-dependency-in-the-dependant }
Da mesma forma que você utiliza `Body`, `Query`, etc. Como parâmetros de sua *função de operação de rota*, utilize `Depends` com um novo parâmetro:
@@ -106,7 +106,7 @@ common_parameters --> read_users
Assim, você escreve um código compartilhado apenas uma vez e o **FastAPI** se encarrega de chamá-lo em suas *operações de rota*.
-/// check | Checando
+/// check | Verifique
Perceba que você não precisa criar uma classe especial e enviar a dependência para algum outro lugar em que o **FastAPI** a "registre" ou realize qualquer operação similar.
@@ -114,7 +114,7 @@ Você apenas envia para `Depends` e o **FastAPI** sabe como fazer o resto.
///
-## Compartilhando dependências `Annotated`
+## Compartilhando dependências `Annotated` { #share-annotated-dependencies }
Nos exemplos acima, você pode ver que existe uma pequena **duplicação de código**.
@@ -140,7 +140,7 @@ As dependências continuarão funcionando como esperado, e a **melhor parte** é
Isso é especialmente útil para uma **base de código grande** onde **as mesmas dependências** são utilizadas repetidamente em **muitas *operações de rota***.
-## `Async` ou não, eis a questão
+## `Async` ou não, eis a questão { #to-async-or-not-to-async }
Como as dependências também serão chamadas pelo **FastAPI** (da mesma forma que *funções de operação de rota*), as mesmas regras se aplicam ao definir suas funções.
@@ -152,11 +152,11 @@ Não faz diferença. O **FastAPI** sabe o que fazer.
/// note | Nota
-Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#com-pressa){.internal-link target=_blank} a sessão acerca de `async` e `await` na documentação.
+Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#in-a-hurry){.internal-link target=_blank} a sessão acerca de `async` e `await` na documentação.
///
-## Integrando com OpenAPI
+## Integrando com OpenAPI { #integrated-with-openapi }
Todas as declarações de requisições, validações e requisitos para suas dependências (e sub-dependências) serão integradas em um mesmo esquema OpenAPI.
@@ -164,7 +164,7 @@ Então, a documentação interativa também terá toda a informação sobre essa
-## Caso de Uso Simples
+## Caso de Uso Simples { #simple-usage }
Se você parar para ver, *funções de operação de rota* são declaradas para serem usadas sempre que uma *rota* e uma *operação* se encaixam, e então o **FastAPI** se encarrega de chamar a função correspondente com os argumentos corretos, extraindo os dados da requisição.
@@ -182,7 +182,7 @@ Outros termos comuns para essa mesma ideia de "injeção de dependência" são:
* injetáveis
* componentes
-## Plug-ins em **FastAPI**
+## Plug-ins em **FastAPI** { #fastapi-plug-ins }
Integrações e "plug-ins" podem ser construídos com o sistema de **Injeção de Dependência**. Mas na verdade, **não há necessidade de criar "plug-ins"**, já que utilizando dependências é possível declarar um número infinito de integrações e interações que se tornam disponíveis para as suas *funções de operação de rota*.
@@ -190,7 +190,7 @@ E as dependências pode ser criadas de uma forma bastante simples e intuitiva qu
Você verá exemplos disso nos próximos capítulos, acerca de bancos de dados relacionais e NoSQL, segurança, etc.
-## Compatibilidade do **FastAPI**
+## Compatibilidade do **FastAPI** { #fastapi-compatibility }
A simplicidade do sistema de injeção de dependência do **FastAPI** faz ele compatível com:
@@ -203,7 +203,7 @@ A simplicidade do sistema de injeção de dependência do **FastAPI** faz ele co
* sistemas de injeção de dados de resposta
* etc.
-## Simples e Poderoso
+## Simples e Poderoso { #simple-and-powerful }
Mesmo que o sistema hierárquico de injeção de dependência seja simples de definir e utilizar, ele ainda é bastante poderoso.
@@ -243,7 +243,7 @@ admin_user --> activate_user
paying_user --> pro_items
```
-## Integração com **OpenAPI**
+## Integração com **OpenAPI** { #integrated-with-openapi_1 }
Todas essas dependências, ao declarar os requisitos para suas *operações de rota*, também adicionam parâmetros, validações, etc.
diff --git a/docs/pt/docs/tutorial/dependencies/sub-dependencies.md b/docs/pt/docs/tutorial/dependencies/sub-dependencies.md
index 3975ce182..e2dc9bbf9 100644
--- a/docs/pt/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/pt/docs/tutorial/dependencies/sub-dependencies.md
@@ -1,4 +1,4 @@
-# Subdependências
+# Subdependências { #sub-dependencies }
Você pode criar dependências que possuem **subdependências**.
@@ -6,9 +6,9 @@ Elas podem ter o nível de **profundidade** que você achar necessário.
O **FastAPI** se encarrega de resolver essas dependências.
-## Primeira dependência "injetável"
+## Primeira dependência "dependable" { #first-dependency-dependable }
-Você pode criar uma primeira dependência (injetável) dessa forma:
+Você pode criar uma primeira dependência ("dependable") dessa forma:
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[8:9] *}
@@ -16,20 +16,20 @@ Esse código declara um parâmetro de consulta opcional, `q`, com o tipo `str`,
Isso é bastante simples (e não muito útil), mas irá nos ajudar a focar em como as subdependências funcionam.
-## Segunda dependência, "injetável" e "dependente"
+## Segunda dependência, "dependable" e "dependente" { #second-dependency-dependable-and-dependant }
-Então, você pode criar uma outra função para uma dependência (um "injetável") que ao mesmo tempo declara sua própria dependência (o que faz dela um "dependente" também):
+Então, você pode criar uma outra função para uma dependência (um "dependable") que ao mesmo tempo declara sua própria dependência (o que faz dela um "dependente" também):
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
Vamos focar nos parâmetros declarados:
-* Mesmo que essa função seja uma dependência ("injetável") por si mesma, ela também declara uma outra dependência (ela "depende" de outra coisa).
+* Mesmo que essa função seja uma dependência ("dependable") por si mesma, ela também declara uma outra dependência (ela "depende" de outra coisa).
* Ela depende do `query_extractor`, e atribui o valor retornado pela função ao parâmetro `q`.
* Ela também declara um cookie opcional `last_query`, do tipo `str`.
* Se o usuário não passou nenhuma consulta `q`, a última consulta é utilizada, que foi salva em um cookie anteriormente.
-## Utilizando a dependência
+## Utilizando a dependência { #use-the-dependency }
Então podemos utilizar a dependência com:
@@ -54,7 +54,7 @@ read_query["/items/"]
query_extractor --> query_or_cookie_extractor --> read_query
```
-## Utilizando a mesma dependência múltiplas vezes
+## Utilizando a mesma dependência múltiplas vezes { #using-the-same-dependency-multiple-times }
Se uma de suas dependências é declarada várias vezes para a mesma *operação de rota*, por exemplo, múltiplas dependências com uma mesma subdependência, o **FastAPI** irá chamar essa subdependência uma única vez para cada requisição.
@@ -62,7 +62,7 @@ E o valor retornado é salvo em um ISO.
+Então, um objeto `datetime` teria que ser convertido em um `str` contendo os dados no formato ISO.
Da mesma forma, este banco de dados não receberia um modelo Pydantic (um objeto com atributos), apenas um `dict`.
diff --git a/docs/pt/docs/tutorial/extra-data-types.md b/docs/pt/docs/tutorial/extra-data-types.md
index 09c838be0..97e4cc475 100644
--- a/docs/pt/docs/tutorial/extra-data-types.md
+++ b/docs/pt/docs/tutorial/extra-data-types.md
@@ -1,4 +1,4 @@
-# Tipos de dados extras
+# Tipos de dados extras { #extra-data-types }
Até agora, você tem usado tipos de dados comuns, tais como:
@@ -17,7 +17,7 @@ E você ainda terá os mesmos recursos que viu até agora:
* Validação de dados.
* Anotação e documentação automáticas.
-## Outros tipos de dados
+## Outros tipos de dados { #other-data-types }
Aqui estão alguns dos tipos de dados adicionais que você pode usar:
@@ -36,7 +36,7 @@ Aqui estão alguns dos tipos de dados adicionais que você pode usar:
* `datetime.timedelta`:
* O `datetime.timedelta` do Python.
* Em requisições e respostas será representado como um `float` de segundos totais.
- * O Pydantic também permite representá-lo como uma "codificação ISO 8601 diferença de tempo", cheque a documentação para mais informações.
+ * O Pydantic também permite representá-lo como uma "codificação ISO 8601 diferença de tempo", cheque a documentação para mais informações.
* `frozenset`:
* Em requisições e respostas, será tratado da mesma forma que um `set`:
* Nas requisições, uma lista será lida, eliminando duplicadas e convertendo-a em um `set`.
@@ -49,14 +49,14 @@ Aqui estão alguns dos tipos de dados adicionais que você pode usar:
* `Decimal`:
* O `Decimal` padrão do Python.
* Em requisições e respostas será representado como um `float`.
-* Você pode checar todos os tipos de dados válidos do Pydantic aqui: Tipos de dados do Pydantic.
+* Você pode checar todos os tipos de dados válidos do Pydantic aqui: Tipos de dados do Pydantic.
-## Exemplo
+## Exemplo { #example }
Aqui está um exemplo de *operação de rota* com parâmetros utilizando-se de alguns dos tipos acima.
-{* ../../docs_src/extra_data_types/tutorial001.py hl[1,3,12:16] *}
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
Note que os parâmetros dentro da função tem seu tipo de dados natural, e você pode, por exemplo, realizar manipulações normais de data, como:
-{* ../../docs_src/extra_data_types/tutorial001.py hl[18:19] *}
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}
diff --git a/docs/pt/docs/tutorial/extra-models.md b/docs/pt/docs/tutorial/extra-models.md
index cccef16e3..24eafce01 100644
--- a/docs/pt/docs/tutorial/extra-models.md
+++ b/docs/pt/docs/tutorial/extra-models.md
@@ -1,4 +1,4 @@
-# Modelos Adicionais
+# Modelos Adicionais { #extra-models }
Continuando com o exemplo anterior, será comum ter mais de um modelo relacionado.
@@ -6,9 +6,9 @@ Isso é especialmente o caso para modelos de usuários, porque:
* O **modelo de entrada** precisa ser capaz de ter uma senha.
* O **modelo de saída** não deve ter uma senha.
-* O **modelo de banco de dados** provavelmente precisaria ter uma senha criptografada.
+* O **modelo de banco de dados** provavelmente precisaria ter uma senha com hash.
-/// danger
+/// danger | Cuidado
Nunca armazene senhas em texto simples dos usuários. Sempre armazene uma "hash segura" que você pode verificar depois.
@@ -16,19 +16,19 @@ Se não souber, você aprenderá o que é uma "senha hash" nos [capítulos de se
///
-## Múltiplos modelos
+## Múltiplos modelos { #multiple-models }
Aqui está uma ideia geral de como os modelos poderiam parecer com seus campos de senha e os lugares onde são usados:
-{* ../../docs_src/extra_models/tutorial001.py hl[9,11,16,22,24,29:30,33:35,40:41] *}
+{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}
-### Sobre `**user_in.dict()`
+### Sobre `**user_in.model_dump()` { #about-user-in-model-dump }
-#### O `.dict()` do Pydantic
+#### O `.model_dump()` do Pydantic { #pydantics-model-dump }
`user_in` é um modelo Pydantic da classe `UserIn`.
-Os modelos Pydantic possuem um método `.dict()` que retorna um `dict` com os dados do modelo.
+Os modelos Pydantic possuem um método `.model_dump()` que retorna um `dict` com os dados do modelo.
Então, se criarmos um objeto Pydantic `user_in` como:
@@ -39,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com
e depois chamarmos:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
```
agora temos um `dict` com os dados na variável `user_dict` (é um `dict` em vez de um objeto de modelo Pydantic).
@@ -61,7 +61,7 @@ teríamos um `dict` Python com:
}
```
-#### Desembrulhando um `dict`
+#### Desembrulhando um `dict` { #unpacking-a-dict }
Se tomarmos um `dict` como `user_dict` e passarmos para uma função (ou classe) com `**user_dict`, o Python irá "desembrulhá-lo". Ele passará as chaves e valores do `user_dict` diretamente como argumentos chave-valor.
@@ -93,31 +93,31 @@ UserInDB(
)
```
-#### Um modelo Pydantic a partir do conteúdo de outro
+#### Um modelo Pydantic a partir do conteúdo de outro { #a-pydantic-model-from-the-contents-of-another }
-Como no exemplo acima, obtivemos o `user_dict` a partir do `user_in.dict()`, este código:
+Como no exemplo acima, obtivemos o `user_dict` a partir do `user_in.model_dump()`, este código:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
UserInDB(**user_dict)
```
seria equivalente a:
```Python
-UserInDB(**user_in.dict())
+UserInDB(**user_in.model_dump())
```
-...porque `user_in.dict()` é um `dict`, e depois fazemos o Python "desembrulhá-lo" passando-o para UserInDB precedido por `**`.
+...porque `user_in.model_dump()` é um `dict`, e depois fazemos o Python "desembrulhá-lo" passando-o para `UserInDB` precedido por `**`.
Então, obtemos um modelo Pydantic a partir dos dados em outro modelo Pydantic.
-#### Desembrulhando um `dict` e palavras-chave extras
+#### Desembrulhando um `dict` e palavras-chave extras { #unpacking-a-dict-and-extra-keywords }
E, então, adicionando o argumento de palavra-chave extra `hashed_password=hashed_password`, como em:
```Python
-UserInDB(**user_in.dict(), hashed_password=hashed_password)
+UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
```
...acaba sendo como:
@@ -132,13 +132,13 @@ UserInDB(
)
```
-/// warning
+/// warning | Atenção
-As funções adicionais de suporte são apenas para demonstração de um fluxo possível dos dados, mas é claro que elas não fornecem segurança real.
+As funções adicionais de suporte `fake_password_hasher` e `fake_save_user` servem apenas para demonstrar um fluxo possível dos dados, mas é claro que elas não fornecem segurança real.
///
-## Reduzir duplicação
+## Reduzir duplicação { #reduce-duplication }
Reduzir a duplicação de código é uma das ideias principais no **FastAPI**.
@@ -154,25 +154,25 @@ Toda conversão de dados, validação, documentação, etc. ainda funcionará no
Dessa forma, podemos declarar apenas as diferenças entre os modelos (com `password` em texto claro, com `hashed_password` e sem senha):
-{* ../../docs_src/extra_models/tutorial002.py hl[9,15:16,19:20,23:24] *}
+{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
-## `Union` ou `anyOf`
+## `Union` ou `anyOf` { #union-or-anyof }
-Você pode declarar uma resposta como o `Union` de dois tipos, o que significa que a resposta seria qualquer um dos dois.
+Você pode declarar uma resposta como o `Union` de dois ou mais tipos, o que significa que a resposta seria qualquer um deles.
Isso será definido no OpenAPI com `anyOf`.
-Para fazer isso, use a dica de tipo padrão do Python `typing.Union`:
+Para fazer isso, use a anotação de tipo padrão do Python `typing.Union`:
-/// note
+/// note | Nota
Ao definir um `Union`, inclua o tipo mais específico primeiro, seguido pelo tipo menos específico. No exemplo abaixo, o tipo mais específico `PlaneItem` vem antes de `CarItem` em `Union[PlaneItem, CarItem]`.
///
-{* ../../docs_src/extra_models/tutorial003.py hl[1,14:15,18:20,33] *}
+{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
-### `Union` no Python 3.10
+### `Union` no Python 3.10 { #union-in-python-3-10 }
Neste exemplo, passamos `Union[PlaneItem, CarItem]` como o valor do argumento `response_model`.
@@ -184,27 +184,27 @@ Se estivesse em uma anotação de tipo, poderíamos ter usado a barra vertical,
some_variable: PlaneItem | CarItem
```
-Mas se colocarmos isso em `response_model=PlaneItem | CarItem` teríamos um erro, pois o Python tentaria executar uma **operação inválida** entre `PlaneItem` e `CarItem` em vez de interpretar isso como uma anotação de tipo.
+Mas se colocarmos isso na atribuição `response_model=PlaneItem | CarItem`, teríamos um erro, pois o Python tentaria executar uma **operação inválida** entre `PlaneItem` e `CarItem` em vez de interpretar isso como uma anotação de tipo.
-## Lista de modelos
+## Lista de modelos { #list-of-models }
Da mesma forma, você pode declarar respostas de listas de objetos.
Para isso, use o padrão Python `typing.List` (ou simplesmente `list` no Python 3.9 e superior):
-{* ../../docs_src/extra_models/tutorial004.py hl[1,20] *}
+{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
-## Resposta com `dict` arbitrário
+## Resposta com `dict` arbitrário { #response-with-arbitrary-dict }
Você também pode declarar uma resposta usando um simples `dict` arbitrário, declarando apenas o tipo das chaves e valores, sem usar um modelo Pydantic.
Isso é útil se você não souber os nomes de campo / atributo válidos (que seriam necessários para um modelo Pydantic) antecipadamente.
-Neste caso, você pode usar `typing.Dict` (ou simplesmente dict no Python 3.9 e superior):
+Neste caso, você pode usar `typing.Dict` (ou simplesmente `dict` no Python 3.9 e superior):
-{* ../../docs_src/extra_models/tutorial005.py hl[1,8] *}
+{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
-## Em resumo
+## Recapitulação { #recap }
Use vários modelos Pydantic e herde livremente para cada caso.
diff --git a/docs/pt/docs/tutorial/first-steps.md b/docs/pt/docs/tutorial/first-steps.md
index 5184d2d5f..86cddde5d 100644
--- a/docs/pt/docs/tutorial/first-steps.md
+++ b/docs/pt/docs/tutorial/first-steps.md
@@ -1,8 +1,8 @@
-# Primeiros Passos
+# Primeiros Passos { #first-steps }
O arquivo FastAPI mais simples pode se parecer com:
-{* ../../docs_src/first_steps/tutorial001.py *}
+{* ../../docs_src/first_steps/tutorial001_py39.py *}
Copie o conteúdo para um arquivo `main.py`.
@@ -48,15 +48,15 @@ $ fastapi dev http://127.0.0.1:8000.
@@ -66,7 +66,7 @@ Você verá essa resposta em JSON:
{"message": "Hello World"}
```
-### Documentação Interativa de APIs
+### Documentação Interativa de APIs { #interactive-api-docs }
Agora vá para http://127.0.0.1:8000/docs.
@@ -74,7 +74,7 @@ Você verá a documentação interativa automática da API (fornecida por http://127.0.0.1:8000/redoc.
@@ -82,31 +82,31 @@ Você verá a documentação alternativa automática (fornecida por OpenAPI é uma especificação que determina como definir um *schema* da sua API.
-Esta definição de *schema* inclui as rotas da sua API, os parâmetros possíveis que elas usam, etc.
+Esta definição de *schema* inclui os paths da sua API, os parâmetros possíveis que eles usam, etc.
-#### "*Schema*" de dados
+#### "*Schema*" de dados { #data-schema }
O termo "*schema*" também pode se referir à forma de alguns dados, como um conteúdo JSON.
Nesse caso, significaria os atributos JSON e os tipos de dados que eles possuem, etc.
-#### OpenAPI e JSON *Schema*
+#### OpenAPI e JSON Schema { #openapi-and-json-schema }
-OpenAPI define um *schema* de API para sua API. E esse *schema* inclui definições (ou "*schemas*") dos dados enviados e recebidos por sua API usando **JSON *Schema***, o padrão para *schemas* de dados JSON.
+OpenAPI define um *schema* de API para sua API. E esse *schema* inclui definições (ou "*schemas*") dos dados enviados e recebidos por sua API usando **JSON Schema**, o padrão para *schemas* de dados JSON.
-#### Verifique o `openapi.json`
+#### Verifique o `openapi.json` { #check-the-openapi-json }
Se você está curioso(a) sobre a aparência do *schema* bruto OpenAPI, o FastAPI gera automaticamente um JSON (*schema*) com as descrições de toda a sua API.
@@ -116,7 +116,7 @@ Ele mostrará um JSON começando com algo como:
```JSON
{
- "openapi": "3.0.2",
+ "openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
@@ -135,7 +135,7 @@ Ele mostrará um JSON começando com algo como:
...
```
-#### Para que serve o OpenAPI
+#### Para que serve o OpenAPI { #what-is-openapi-for }
O *schema* OpenAPI é o que possibilita os dois sistemas de documentação interativos mostrados.
@@ -143,35 +143,71 @@ E existem dezenas de alternativas, todas baseadas em OpenAPI. Você pode facilme
Você também pode usá-lo para gerar código automaticamente para clientes que se comunicam com sua API. Por exemplo, aplicativos front-end, móveis ou IoT.
-## Recapitulando, passo a passo
+### Faça o deploy da sua aplicação (opcional) { #deploy-your-app-optional }
-### Passo 1: importe `FastAPI`
+Você pode, opcionalmente, fazer o deploy da sua aplicação FastAPI na FastAPI Cloud; acesse e entre na lista de espera, se ainda não entrou. 🚀
-{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
+Se você já tem uma conta na **FastAPI Cloud** (nós convidamos você da lista de espera 😉), pode fazer o deploy da sua aplicação com um único comando.
+
+Antes do deploy, certifique-se de que está autenticado:
+
+get
+* o path `/`
+* usando uma operação get
-/// info | `@decorador`
+/// info | Informações sobre `@decorator`
Essa sintaxe `@alguma_coisa` em Python é chamada de "decorador".
@@ -245,9 +281,9 @@ Você o coloca em cima de uma função. Como um chapéu decorativo (acho que é
Um "decorador" pega a função abaixo e faz algo com ela.
-Em nosso caso, este decorador informa ao **FastAPI** que a função abaixo corresponde a **rota** `/` com uma **operação** `get`.
+Em nosso caso, este decorador informa ao **FastAPI** que a função abaixo corresponde ao **path** `/` com uma **operação** `get`.
-É o "**decorador de rota**".
+É o "**decorador de operação de rota**".
///
@@ -276,48 +312,69 @@ Por exemplo, ao usar GraphQL, você normalmente executa todas as ações usando
///
-### Passo 4: defina uma **função de rota**
+### Passo 4: defina a função de operação de rota { #step-4-define-the-path-operation-function }
-Esta é a nossa "**função de rota**":
+Esta é a nossa "**função de operação de rota**":
-* **rota**: é `/`.
+* **path**: é `/`.
* **operação**: é `get`.
* **função**: é a função abaixo do "decorador" (abaixo do `@app.get("/")`).
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *}
Esta é uma função Python.
-Ela será chamada pelo **FastAPI** sempre que receber uma requisição para a URL "`/ `" usando uma operação `GET`.
+Ela será chamada pelo **FastAPI** sempre que receber uma requisição para a URL "`/`" usando uma operação `GET`.
-Neste caso, é uma função `assíncrona`.
+Neste caso, é uma função `async`.
---
Você também pode defini-la como uma função normal em vez de `async def`:
-{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *}
/// note | Nota
-Se você não sabe a diferença, verifique o [Async: *"Com pressa?"*](../async.md#com-pressa){.internal-link target=_blank}.
+Se você não sabe a diferença, verifique o [Async: *"Com pressa?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
///
-### Passo 5: retorne o conteúdo
+### Passo 5: retorne o conteúdo { #step-5-return-the-content }
-{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *}
Você pode retornar um `dict`, `list` e valores singulares como `str`, `int`, etc.
-Você também pode devolver modelos Pydantic (você verá mais sobre isso mais tarde).
+Você também pode devolver modelos Pydantic ( você verá mais sobre isso mais tarde).
Existem muitos outros objetos e modelos que serão convertidos automaticamente para JSON (incluindo ORMs, etc). Tente usar seus favoritos, é altamente provável que já sejam compatíveis.
-## Recapitulando
+### Passo 6: Faça o deploy { #step-6-deploy-it }
+
+Faça o deploy da sua aplicação para a **FastAPI Cloud** com um comando: `fastapi deploy`. 🎉
+
+#### Sobre o FastAPI Cloud { #about-fastapi-cloud }
+
+A **FastAPI Cloud** é construída pelo mesmo autor e equipe por trás do **FastAPI**.
+
+Ela simplifica o processo de **construir**, **fazer deploy** e **acessar** uma API com o mínimo de esforço.
+
+Traz a mesma **experiência do desenvolvedor** de criar aplicações com FastAPI para **fazer o deploy** delas na nuvem. 🎉
+
+A FastAPI Cloud é a principal patrocinadora e financiadora dos projetos open source do ecossistema *FastAPI and friends*. ✨
+
+#### Faça o deploy em outros provedores de nuvem { #deploy-to-other-cloud-providers }
+
+FastAPI é open source e baseado em padrões. Você pode fazer deploy de aplicações FastAPI em qualquer provedor de nuvem que preferir.
+
+Siga os tutoriais do seu provedor de nuvem para fazer deploy de aplicações FastAPI com eles. 🤓
+
+## Recapitulando { #recap }
* Importe `FastAPI`.
* Crie uma instância do `app`.
-* Coloque o **decorador que define a operação** (como `@app.get("/")`).
-* Escreva uma **função para a operação da rota** (como `def root(): ...`) abaixo.
-* Execute o servidor de desenvolvimento (como `uvicorn main:app --reload`).
+* Escreva um **decorador de operação de rota** usando decoradores como `@app.get("/")`.
+* Defina uma **função de operação de rota**; por exemplo, `def root(): ...`.
+* Execute o servidor de desenvolvimento usando o comando `fastapi dev`.
+* Opcionalmente, faça o deploy da sua aplicação com `fastapi deploy`.
diff --git a/docs/pt/docs/tutorial/handling-errors.md b/docs/pt/docs/tutorial/handling-errors.md
index 098195db7..1c162c205 100644
--- a/docs/pt/docs/tutorial/handling-errors.md
+++ b/docs/pt/docs/tutorial/handling-errors.md
@@ -1,4 +1,4 @@
-# Manipulação de erros
+# Manipulação de erros { #handling-errors }
Há diversas situações em que você precisa notificar um erro a um cliente que está utilizando a sua API.
@@ -11,7 +11,6 @@ Pode ser que você precise comunicar ao cliente que:
* O item que o cliente está tentando acessar não existe.
* etc.
-
Nesses casos, você normalmente retornaria um **HTTP status code** próximo ao status code na faixa do status code **400** (do 400 ao 499).
Isso é bastante similar ao caso do HTTP status code 200 (do 200 ao 299). Esses "200" status codes significam que, de algum modo, houve sucesso na requisição.
@@ -20,15 +19,15 @@ Os status codes na faixa dos 400 significam que houve um erro por parte do clien
Você se lembra de todos aqueles erros (e piadas) a respeito do "**404 Not Found**"?
-## Use o `HTTPException`
+## Use o `HTTPException` { #use-httpexception }
Para retornar ao cliente *responses* HTTP com erros, use o `HTTPException`.
-### Import `HTTPException`
+### Import `HTTPException` { #import-httpexception }
-{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *}
-### Lance o `HTTPException` no seu código.
+### Lance o `HTTPException` no seu código { #raise-an-httpexception-in-your-code }
`HTTPException`, ao fundo, nada mais é do que a conjunção entre uma exceção comum do Python e informações adicionais relevantes para APIs.
@@ -40,15 +39,14 @@ O benefício de lançar uma exceção em vez de retornar um valor ficará mais e
Neste exemplo, quando o cliente pede, na requisição, por um item cujo ID não existe, a exceção com o status code `404` é lançada:
-{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
-
-### A response resultante
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *}
+### A response resultante { #the-resulting-response }
Se o cliente faz uma requisição para `http://example.com/items/foo` (um `item_id` `"foo"`), esse cliente receberá um HTTP status code 200, e uma resposta JSON:
-```
+```JSON
{
"item": "The Foo Wrestlers"
}
@@ -71,7 +69,7 @@ Esses tipos de dados são manipulados automaticamente pelo **FastAPI** e convert
///
-## Adicione headers customizados
+## Adicione headers customizados { #add-custom-headers }
Há certas situações em que é bastante útil poder adicionar headers customizados no HTTP error. Exemplo disso seria adicionar headers customizados para tipos de segurança.
@@ -79,17 +77,17 @@ Você provavelmente não precisará utilizar esses headers diretamente no seu c
Mas caso você precise, para um cenário mais complexo, você pode adicionar headers customizados:
-{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
+{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *}
-## Instalando manipuladores de exceções customizados
+## Instale manipuladores de exceções customizados { #install-custom-exception-handlers }
-Você pode adicionar manipuladores de exceção customizados com a mesma seção de utilidade de exceções presentes no Starlette
+Você pode adicionar manipuladores de exceção customizados com a mesma seção de utilidade de exceções presentes no Starlette.
Digamos que você tenha uma exceção customizada `UnicornException` que você (ou uma biblioteca que você use) precise lançar (`raise`).
Nesse cenário, se você precisa manipular essa exceção de modo global com o FastAPI, você pode adicionar um manipulador de exceção customizada com `@app.exception_handler()`.
-{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *}
Nesse cenário, se você fizer uma requisição para `/unicorns/yolo`, a *operação de caminho* vai lançar (`raise`) o `UnicornException`.
@@ -103,27 +101,31 @@ Dessa forma você receberá um erro "limpo", com o HTTP status code `418` e um J
/// note | Detalhes Técnicos
-Você também pode usar `from starlette.requests import Request` and `from starlette.responses import JSONResponse`.
+Você também pode usar `from starlette.requests import Request` e `from starlette.responses import JSONResponse`.
**FastAPI** disponibiliza o mesmo `starlette.responses` através do `fastapi.responses` por conveniência ao desenvolvedor. Contudo, a maior parte das respostas disponíveis vem diretamente do Starlette. O mesmo acontece com o `Request`.
///
-## Sobrescreva o manipulador padrão de exceções
+## Sobrescreva os manipuladores de exceções padrão { #override-the-default-exception-handlers }
**FastAPI** tem alguns manipuladores padrão de exceções.
-Esses manipuladores são os responsáveis por retornar o JSON padrão de respostas quando você lança (`raise`) o `HTTPException` e quando a requisição tem dados invalidos.
+Esses manipuladores são os responsáveis por retornar o JSON padrão de respostas quando você lança (`raise`) o `HTTPException` e quando a requisição tem dados inválidos.
Você pode sobrescrever esses manipuladores de exceção com os seus próprios manipuladores.
-## Sobrescreva exceções de validação da requisição
+### Sobrescreva exceções de validação da requisição { #override-request-validation-exceptions }
Quando a requisição contém dados inválidos, **FastAPI** internamente lança para o `RequestValidationError`.
+E também inclui um manipulador de exceções padrão para ele.
+
Para sobrescrevê-lo, importe o `RequestValidationError` e use-o com o `@app.exception_handler(RequestValidationError)` para decorar o manipulador de exceções.
-{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+O manipulador de exceções receberá um `Request` e a exceção.
+
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *}
Se você for ao `/items/foo`, em vez de receber o JSON padrão com o erro:
@@ -145,34 +147,17 @@ Se você for ao `/items/foo`, em vez de receber o JSON padrão com o erro:
você receberá a versão em texto:
```
-1 validation error
-path -> item_id
- value is not a valid integer (type=type_error.integer)
+Validation errors:
+Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer
```
-### `RequestValidationError` vs `ValidationError`
-
-/// warning | Aviso
-
-Você pode pular estes detalhes técnicos caso eles não sejam importantes para você neste momento.
-
-///
-
-`RequestValidationError` é uma subclasse do `ValidationError` existente no Pydantic.
-
-**FastAPI** faz uso dele para que você veja o erro no seu log, caso você utilize um modelo de Pydantic em `response_model`, e seus dados tenham erro.
+### Sobrescreva o manipulador de erro `HTTPException` { #override-the-httpexception-error-handler }
-Contudo, o cliente ou usuário não terão acesso a ele. Ao contrário, o cliente receberá um "Internal Server Error" com o HTTP status code `500`.
-
-E assim deve ser porque seria um bug no seu código ter o `ValidationError` do Pydantic na sua *response*, ou em qualquer outro lugar do seu código (que não na requisição do cliente).
-
-E enquanto você conserta o bug, os clientes / usuários não deveriam ter acesso às informações internas do erro, porque, desse modo, haveria exposição de uma vulnerabilidade de segurança.
-
-Do mesmo modo, você pode sobreescrever o `HTTPException`.
+Do mesmo modo, você pode sobrescrever o `HTTPException`.
Por exemplo, você pode querer retornar uma *response* em *plain text* ao invés de um JSON para os seguintes erros:
-{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *}
/// note | Detalhes Técnicos
@@ -182,11 +167,21 @@ Você pode usar `from starlette.responses import PlainTextResponse`.
///
-### Use o body do `RequestValidationError`.
+/// warning | Atenção
+
+Tenha em mente que o `RequestValidationError` contém as informações do nome do arquivo e da linha onde o erro de validação acontece, para que você possa mostrá-las nos seus logs com as informações relevantes, se quiser.
+
+Mas isso significa que, se você simplesmente convertê-lo para uma string e retornar essa informação diretamente, você pode acabar vazando um pouco de informação sobre o seu sistema; por isso, aqui o código extrai e mostra cada erro de forma independente.
+
+///
+
+### Use o body do `RequestValidationError` { #use-the-requestvalidationerror-body }
O `RequestValidationError` contém o `body` que ele recebeu de dados inválidos.
-Você pode utilizá-lo enquanto desenvolve seu app para conectar o *body* e debugá-lo, e assim retorná-lo ao usuário, etc.
+Você pode utilizá-lo enquanto desenvolve seu app para registrar o *body* e debugá-lo, e assim retorná-lo ao usuário, etc.
+
+{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *}
Tente enviar um item inválido como este:
@@ -197,7 +192,7 @@ Tente enviar um item inválido como este:
}
```
-Você receberá uma *response* informando-o de que a data é inválida, e contendo o *body* recebido:
+Você receberá uma *response* informando-o de que os dados são inválidos, e contendo o *body* recebido:
```JSON hl_lines="12-15"
{
@@ -218,30 +213,30 @@ Você receberá uma *response* informando-o de que a data é inválida, e conten
}
```
-#### O `HTTPException` do FastAPI vs o `HTTPException` do Starlette.
+#### O `HTTPException` do FastAPI vs o `HTTPException` do Starlette { #fastapis-httpexception-vs-starlettes-httpexception }
O **FastAPI** tem o seu próprio `HTTPException`.
E a classe de erro `HTTPException` do **FastAPI** herda da classe de erro do `HTTPException` do Starlette.
-A diferença entre os dois é a de que o `HTTPException` do **FastAPI** permite que você adicione *headers* que serão incluídos nas *responses*.
-
-Esses *headers* são necessários/utilizados internamente pelo OAuth 2.0 e também por outras utilidades de segurança.
+A única diferença é que o `HTTPException` do **FastAPI** aceita qualquer dado que possa ser convertido em JSON para o campo `detail`, enquanto o `HTTPException` do Starlette aceita apenas strings para esse campo.
Portanto, você pode continuar lançando o `HTTPException` do **FastAPI** normalmente no seu código.
Porém, quando você registrar um manipulador de exceção, você deve registrá-lo através do `HTTPException` do Starlette.
-Dessa forma, se qualquer parte do código interno, extensão ou plug-in do Starlette lançar o `HTTPException`, o seu manipulador de exceção poderá capturar esse lançamento e tratá-lo.
+Dessa forma, se qualquer parte do código interno, extensão ou plug-in do Starlette lançar um `HTTPException` do Starlette, o seu manipulador poderá capturar e tratá-lo.
+
+Neste exemplo, para poder ter ambos os `HTTPException` no mesmo código, a exceção do Starlette é renomeada para `StarletteHTTPException`:
```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
```
-### Re-use os manipulares de exceção do **FastAPI**
+### Reutilize os manipuladores de exceção do **FastAPI** { #reuse-fastapis-exception-handlers }
Se você quer usar a exceção em conjunto com o mesmo manipulador de exceção *default* do **FastAPI**, você pode importar e re-usar esses manipuladores de exceção do `fastapi.exception_handlers`:
-{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+{* ../../docs_src/handling_errors/tutorial006_py39.py hl[2:5,15,21] *}
Nesse exemplo você apenas imprime (`print`) o erro com uma mensagem expressiva. Mesmo assim, dá para pegar a ideia. Você pode usar a exceção e então apenas re-usar o manipulador de exceção *default*.
diff --git a/docs/pt/docs/tutorial/header-param-models.md b/docs/pt/docs/tutorial/header-param-models.md
index 9a88dbfec..046c99c29 100644
--- a/docs/pt/docs/tutorial/header-param-models.md
+++ b/docs/pt/docs/tutorial/header-param-models.md
@@ -1,8 +1,8 @@
-# Modelos de Parâmetros do Cabeçalho
+# Modelos de Parâmetros do Cabeçalho { #header-parameter-models }
Se você possui um grupo de **parâmetros de cabeçalho** relacionados, você pode criar um **modelo do Pydantic** para declará-los.
-Isso vai lhe permitir **reusar o modelo** em **múltiplos lugares** e também declarar validações e metadadados para todos os parâmetros de uma vez. 😎
+Isso vai lhe permitir **reusar o modelo** em **múltiplos lugares** e também declarar validações e metadados para todos os parâmetros de uma vez. 😎
/// note | Nota
@@ -10,7 +10,7 @@ Isso é possível desde a versão `0.115.0` do FastAPI. 🤓
///
-## Parâmetros do Cabeçalho com um Modelo Pydantic
+## Parâmetros do Cabeçalho com um Modelo Pydantic { #header-parameters-with-a-pydantic-model }
Declare os **parâmetros de cabeçalho** que você precisa em um **modelo do Pydantic**, e então declare o parâmetro como `Header`:
@@ -18,7 +18,7 @@ Declare os **parâmetros de cabeçalho** que você precisa em um **modelo do Pyd
O **FastAPI** irá **extrair** os dados de **cada campo** a partir dos **cabeçalhos** da requisição e te retornará o modelo do Pydantic que você definiu.
-### Checando a documentação
+## Checando a documentação { #check-the-docs }
Você pode ver os headers necessários na interface gráfica da documentação em `/docs`:
@@ -26,7 +26,7 @@ Você pode ver os headers necessários na interface gráfica da documentação e
-## Identificador de Licença
+## Identificador de Licença { #license-identifier }
Desde o OpenAPI 3.1.0 e FastAPI 0.99.0, você também pode definir o license_info com um identifier em vez de uma url.
Por exemplo:
-{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
-## Metadados para tags
+## Metadados para tags { #metadata-for-tags }
Você também pode adicionar metadados adicionais para as diferentes tags usadas para agrupar suas operações de rota com o parâmetro `openapi_tags`.
@@ -52,13 +52,13 @@ Cada dicionário pode conter:
* `description`: uma `str` com uma breve descrição da documentação externa.
* `url` (**obrigatório**): uma `str` com a URL da documentação externa.
-### Criar Metadados para tags
+### Criar Metadados para tags { #create-metadata-for-tags }
Vamos tentar isso em um exemplo com tags para `users` e `items`.
Crie metadados para suas tags e passe-os para o parâmetro `openapi_tags`:
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}
Observe que você pode usar Markdown dentro das descrições. Por exemplo, "login" será exibido em negrito (**login**) e "fancy" será exibido em itálico (_fancy_).
@@ -68,31 +68,31 @@ Você não precisa adicionar metadados para todas as tags que você usa.
///
-### Use suas tags
+### Use suas tags { #use-your-tags }
Use o parâmetro `tags` com suas *operações de rota* (e `APIRouter`s) para atribuí-los a diferentes tags:
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
-/// info | Informação
+/// info | Informação
-Leia mais sobre tags em [Configuração de Operação de Caminho](path-operation-configuration.md#tags){.internal-link target=_blank}.
+Leia mais sobre tags em [Configuração de operação de rota](path-operation-configuration.md#tags){.internal-link target=_blank}.
///
-### Cheque os documentos
+### Cheque os documentos { #check-the-docs }
Agora, se você verificar a documentação, ela exibirá todos os metadados adicionais:
-### Ordem das tags
+### Ordem das tags { #order-of-tags }
A ordem de cada dicionário de metadados de tag também define a ordem exibida na interface de documentação.
Por exemplo, embora `users` apareça após `items` em ordem alfabética, ele é exibido antes deles, porque adicionamos seus metadados como o primeiro dicionário na lista.
-## URL da OpenAPI
+## URL da OpenAPI { #openapi-url }
Por padrão, o esquema OpenAPI é servido em `/openapi.json`.
@@ -100,11 +100,11 @@ Mas você pode configurá-lo com o parâmetro `openapi_url`.
Por exemplo, para defini-lo para ser servido em `/api/v1/openapi.json`:
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}
Se você quiser desativar completamente o esquema OpenAPI, pode definir `openapi_url=None`, o que também desativará as interfaces de documentação que o utilizam.
-## URLs da Documentação
+## URLs da Documentação { #docs-urls }
Você pode configurar as duas interfaces de documentação incluídas:
@@ -117,4 +117,4 @@ Você pode configurar as duas interfaces de documentação incluídas:
Por exemplo, para definir o Swagger UI para ser servido em `/documentation` e desativar o ReDoc:
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/pt/docs/tutorial/middleware.md b/docs/pt/docs/tutorial/middleware.md
index 32b81c646..b49c1eaa1 100644
--- a/docs/pt/docs/tutorial/middleware.md
+++ b/docs/pt/docs/tutorial/middleware.md
@@ -1,4 +1,4 @@
-# Middleware
+# Middleware { #middleware }
Você pode adicionar middleware à suas aplicações **FastAPI**.
@@ -11,15 +11,15 @@ Um "middleware" é uma função que manipula cada **requisição** antes de ser
* Ele pode fazer algo com essa **resposta** ou executar qualquer código necessário.
* Então ele retorna a **resposta**.
-/// note | Detalhes técnicos
+/// note | Detalhes Técnicos
Se você tiver dependências com `yield`, o código de saída será executado *depois* do middleware.
-Se houver alguma tarefa em segundo plano (documentada posteriormente), ela será executada *depois* de todo o middleware.
+Se houver alguma tarefa em segundo plano (abordada na seção [Tarefas em segundo plano](background-tasks.md){.internal-link target=_blank}, que você verá mais adiante), ela será executada *depois* de todo o middleware.
///
-## Criar um middleware
+## Criar um middleware { #create-a-middleware }
Para criar um middleware, use o decorador `@app.middleware("http")` logo acima de uma função.
@@ -31,17 +31,17 @@ A função middleware recebe:
* Então ela retorna a `response` gerada pela *operação de rota* correspondente.
* Você pode então modificar ainda mais o `response` antes de retorná-lo.
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip | Dica
-Tenha em mente que cabeçalhos proprietários personalizados podem ser adicionados usando o prefixo 'X-'.
+Tenha em mente que cabeçalhos proprietários personalizados podem ser adicionados usando o prefixo `X-`.
-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.
+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
+/// note | Detalhes Técnicos
Você também pode usar `from starlette.requests import Request`.
@@ -49,7 +49,7 @@ Você também pode usar `from starlette.requests import Request`.
///
-### Antes e depois da `response`
+### Antes e depois da `response` { #before-and-after-the-response }
Você pode adicionar código para ser executado com a `request`, antes que qualquer *operação de rota* o receba.
@@ -57,9 +57,38 @@ 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] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *}
-## Outros middlewares
+/// tip | Dica
+
+Aqui usamos `time.perf_counter()` em vez de `time.time()` porque ele pode ser mais preciso para esses casos de uso. 🤓
+
+///
+
+## Ordem de execução de múltiplos middlewares { #multiple-middleware-execution-order }
+
+Quando você adiciona múltiplos middlewares usando o decorador `@app.middleware()` ou o método `app.add_middleware()`, cada novo middleware envolve a aplicação, formando uma pilha. O último middleware adicionado é o mais externo, e o primeiro é o mais interno.
+
+No caminho da requisição, o middleware mais externo roda primeiro.
+
+No caminho da resposta, ele roda por último.
+
+Por exemplo:
+
+```Python
+app.add_middleware(MiddlewareA)
+app.add_middleware(MiddlewareB)
+```
+
+Isso resulta na seguinte ordem de execução:
+
+* **Requisição**: MiddlewareB → MiddlewareA → rota
+
+* **Resposta**: rota → MiddlewareA → MiddlewareB
+
+Esse comportamento de empilhamento garante que os middlewares sejam executados em uma ordem previsível e controlável.
+
+## Outros middlewares { #other-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}.
diff --git a/docs/pt/docs/tutorial/path-operation-configuration.md b/docs/pt/docs/tutorial/path-operation-configuration.md
index f183c9d23..84eebc128 100644
--- a/docs/pt/docs/tutorial/path-operation-configuration.md
+++ b/docs/pt/docs/tutorial/path-operation-configuration.md
@@ -1,14 +1,14 @@
-# Configuração da Operação de Rota
+# Configuração da Operação de Rota { #path-operation-configuration }
Existem vários parâmetros que você pode passar para o seu *decorador de operação de rota* para configurá-lo.
-/// warning | Aviso
+/// warning | Atenção
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
+## Código de Status da Resposta { #response-status-code }
Você pode definir o `status_code` (HTTP) para ser usado na resposta da sua *operação de rota*.
@@ -16,7 +16,7 @@ Você pode passar diretamente o código `int`, como `404`.
Mas se você não se lembrar o que cada código numérico significa, pode usar as constantes de atalho em `status`:
-{* ../../docs_src/path_operation_configuration/tutorial001.py hl[3,17] *}
+{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
Esse código de status será usado na resposta e será adicionado ao esquema OpenAPI.
@@ -28,17 +28,17 @@ Você também poderia usar `from starlette import status`.
///
-## Tags
+## Tags { #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`):
-{* ../../docs_src/path_operation_configuration/tutorial002.py hl[17,22,27] *}
+{* ../../docs_src/path_operation_configuration/tutorial002_py310.py hl[15,20,25] *}
Eles serão adicionados ao esquema OpenAPI e usados pelas interfaces de documentação automática:
-### Tags com Enums
+### Tags com Enums { #tags-with-enums }
Se você tem uma grande aplicação, você pode acabar acumulando **várias tags**, e você gostaria de ter certeza de que você sempre usa a **mesma tag** para *operações de rota* relacionadas.
@@ -46,32 +46,31 @@ Nestes casos, pode fazer sentido armazenar as tags em um `Enum`.
**FastAPI** suporta isso da mesma maneira que com strings simples:
-{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
+{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
-## Resumo e descrição
+## Resumo e descrição { #summary-and-description }
Você pode adicionar um `summary` e uma `description`:
-{* ../../docs_src/path_operation_configuration/tutorial003.py hl[20:21] *}
+{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
-## Descrição do docstring
+## Descrição do docstring { #description-from-docstring }
Como as descrições tendem a ser longas e cobrir várias linhas, você pode declarar a descrição da *operação de rota* na docstring da função e o **FastAPI** irá lê-la de lá.
Você pode escrever Markdown na docstring, ele será interpretado e exibido corretamente (levando em conta a indentação da docstring).
-{* ../../docs_src/path_operation_configuration/tutorial004.py hl[19:27] *}
+{* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *}
Ela será usada nas documentações interativas:
-
-## Descrição da resposta
+## Descrição da resposta { #response-description }
Você pode especificar a descrição da resposta com o parâmetro `response_description`:
-{* ../../docs_src/path_operation_configuration/tutorial005.py hl[21] *}
+{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[19] *}
/// info | Informação
@@ -79,7 +78,7 @@ Note que `response_description` se refere especificamente à resposta, a `descri
///
-/// check
+/// check | Verifique
OpenAPI especifica que cada *operação de rota* requer uma descrição de resposta.
@@ -89,11 +88,11 @@ Então, se você não fornecer uma, o **FastAPI** irá gerar automaticamente uma
-## Depreciar uma *operação de rota*
+## Descontinuar uma *operação de rota* { #deprecate-a-path-operation }
Se você precisar marcar uma *operação de rota* como descontinuada, mas sem removê-la, passe o parâmetro `deprecated`:
-{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
+{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
Ela será claramente marcada como descontinuada nas documentações interativas:
@@ -103,6 +102,6 @@ Verifique como *operações de rota* descontinuadas e não descontinuadas se par
-## Resumindo
+## Resumindo { #recap }
Você pode configurar e adicionar metadados para suas *operações de rota* facilmente passando parâmetros para os *decoradores de operação de rota*.
diff --git a/docs/pt/docs/tutorial/path-params-numeric-validations.md b/docs/pt/docs/tutorial/path-params-numeric-validations.md
index 3aea1188d..9f12ba38f 100644
--- a/docs/pt/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/pt/docs/tutorial/path-params-numeric-validations.md
@@ -1,91 +1,128 @@
-# Parâmetros da Rota e Validações Numéricas
+# Parâmetros de path e validações numéricas { #path-parameters-and-numeric-validations }
-Do mesmo modo que você pode declarar mais validações e metadados para parâmetros de consulta com `Query`, você pode declarar os mesmos tipos de validações e metadados para parâmetros de rota com `Path`.
+Da mesma forma que você pode declarar mais validações e metadados para parâmetros de consulta com `Query`, você pode declarar o mesmo tipo de validações e metadados para parâmetros de path com `Path`.
-## Importe `Path`
+## Importe `Path` { #import-path }
-Primeiro, importe `Path` de `fastapi`:
+Primeiro, importe `Path` de `fastapi`, e importe `Annotated`:
-{* ../../docs_src/path_params_numeric_validations/tutorial001_py310.py hl[1] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-## Declare metadados
+/// info | Informação
-Você pode declarar todos os parâmetros da mesma maneira que na `Query`.
+O FastAPI adicionou suporte a `Annotated` (e passou a recomendá-lo) na versão 0.95.0.
-Por exemplo para declarar um valor de metadado `title` para o parâmetro de rota `item_id` você pode digitar:
+Se você tiver uma versão mais antiga, verá erros ao tentar usar `Annotated`.
-{* ../../docs_src/path_params_numeric_validations/tutorial001_py310.py hl[8] *}
+Certifique-se de [Atualizar a versão do FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} para pelo menos 0.95.1 antes de usar `Annotated`.
-/// note | Nota
+///
+
+## Declare metadados { #declare-metadata }
+
+Você pode declarar todos os mesmos parâmetros que em `Query`.
+
+Por exemplo, para declarar um valor de metadado `title` para o parâmetro de path `item_id` você pode digitar:
-Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota.
+{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
-Então, você deve declará-lo com `...` para marcá-lo como obrigatório.
+/// note | Nota
-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.
+Um parâmetro de path é sempre obrigatório, pois precisa fazer parte do path. Mesmo que você o declare como `None` ou defina um valor padrão, isso não afetaria nada, ele ainda seria sempre obrigatório.
///
-## Ordene os parâmetros de acordo com sua necessidade
+## Ordene os parâmetros de acordo com sua necessidade { #order-the-parameters-as-you-need }
+
+/// tip | Dica
+
+Isso provavelmente não é tão importante ou necessário se você usar `Annotated`.
-Suponha que você queira declarar o parâmetro de consulta `q` como uma `str` obrigatória.
+///
+
+Vamos supor que você queira declarar o parâmetro de consulta `q` como uma `str` obrigatória.
-E você não precisa declarar mais nada em relação a este parâmetro, então você não precisa necessariamente usar `Query`.
+E você não precisa declarar mais nada para esse parâmetro, então você realmente não precisa usar `Query`.
-Mas você ainda precisa usar `Path` para o parâmetro de rota `item_id`.
+Mas você ainda precisa usar `Path` para o parâmetro de path `item_id`. E você não quer usar `Annotated` por algum motivo.
-O Python irá acusar se você colocar um elemento com um valor padrão definido antes de outro que não tenha um valor padrão.
+O Python vai reclamar se você colocar um valor com “padrão” antes de um valor que não tem “padrão”.
-Mas você pode reordená-los, colocando primeiro o elemento sem o valor padrão (o parâmetro de consulta `q`).
+Mas você pode reordená-los e colocar primeiro o valor sem padrão (o parâmetro de consulta `q`).
-Isso não faz diferença para o **FastAPI**. Ele vai detectar os parâmetros pelos seus nomes, tipos e definições padrão (`Query`, `Path`, etc), sem se importar com a ordem.
+Isso não faz diferença para o **FastAPI**. Ele vai detectar os parâmetros pelos seus nomes, tipos e declarações de padrão (`Query`, `Path`, etc.), sem se importar com a ordem.
Então, você pode declarar sua função assim:
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *}
+
+Mas tenha em mente que, se você usar `Annotated`, você não terá esse problema, não fará diferença, pois você não está usando valores padrão de parâmetros de função para `Query()` ou `Path()`.
-## Ordene os parâmetros de a acordo com sua necessidade, truques
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
-Se você quiser declarar o parâmetro de consulta `q` sem um `Query` nem um valor padrão, e o parâmetro de rota `item_id` usando `Path`, e definí-los em uma ordem diferente, Python tem um pequeno truque na sintaxe para isso.
+## Ordene os parâmetros de acordo com sua necessidade, truques { #order-the-parameters-as-you-need-tricks }
+
+/// tip | Dica
+
+Isso provavelmente não é tão importante ou necessário se você usar `Annotated`.
+
+///
+
+Aqui vai um pequeno truque que pode ser útil, mas você não vai precisar dele com frequência.
+
+Se você quiser:
+
+* declarar o parâmetro de consulta `q` sem um `Query` nem qualquer valor padrão
+* declarar o parâmetro de path `item_id` usando `Path`
+* tê-los em uma ordem diferente
+* não usar `Annotated`
+
+...o Python tem uma pequena sintaxe especial para isso.
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.
+O Python não fará nada com esse `*`, mas saberá que todos os parâmetros seguintes devem ser chamados como argumentos nomeados (pares chave-valor), também conhecidos como kwargs. Mesmo que eles não tenham um valor padrão.
+
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
+
+### Melhor com `Annotated` { #better-with-annotated }
+
+Tenha em mente que, se você usar `Annotated`, como você não está usando valores padrão de parâmetros de função, você não terá esse problema e provavelmente não precisará usar `*`.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
-## Validações numéricas: maior que ou igual
+## Validações numéricas: maior que ou igual { #number-validations-greater-than-or-equal }
-Com `Query` e `Path` (e outras que você verá mais tarde) você pode declarar restrições numéricas.
+Com `Query` e `Path` (e outras que você verá depois) você pode declarar restrições numéricas.
-Aqui, com `ge=1`, `item_id` precisará ser um número inteiro maior que ("`g`reater than") ou igual ("`e`qual") a 1.
+Aqui, com `ge=1`, `item_id` precisará ser um número inteiro “`g`reater than or `e`qual” a `1`.
-{* ../../docs_src/path_params_numeric_validations/tutorial004.py hl[8] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
-## Validações numéricas: maior que e menor que ou igual
+## Validações numéricas: maior que e menor que ou igual { #number-validations-greater-than-and-less-than-or-equal }
-O mesmo se aplica para:
+O mesmo se aplica a:
* `gt`: maior que (`g`reater `t`han)
* `le`: menor que ou igual (`l`ess than or `e`qual)
-{* ../../docs_src/path_params_numeric_validations/tutorial005.py hl[9] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
-## Validações numéricas: valores do tipo float, maior que e menor que
+## Validações numéricas: floats, maior que e menor que { #number-validations-floats-greater-than-and-less-than }
-Validações numéricas também funcionam para valores do tipo `float`.
+Validações numéricas também funcionam para valores `float`.
-Aqui é onde se torna importante a possibilidade de declarar gt e não apenas ge. Com isso você pode especificar, por exemplo, que um valor deve ser maior que `0`, ainda que seja menor que `1`.
+Aqui é onde se torna importante poder declarar gt e não apenas ge. Com isso você pode exigir, por exemplo, que um valor seja maior que `0`, mesmo que seja menor que `1`.
-Assim, `0.5` seria um valor válido. Mas `0.0` ou `0` não seria.
+Assim, `0.5` seria um valor válido. Mas `0.0` ou `0` não seriam.
-E o mesmo para lt.
+E o mesmo para lt.
-{* ../../docs_src/path_params_numeric_validations/tutorial006.py hl[11] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## Recapitulando
+## Recapitulando { #recap }
-Com `Query`, `Path` (e outras que você ainda não viu) você pode declarar metadados e validações de texto do mesmo modo que com [Parâmetros de consulta e validações de texto](query-params-str-validations.md){.internal-link target=_blank}.
+Com `Query`, `Path` (e outras que você ainda não viu) você pode declarar metadados e validações de string do mesmo modo que em [Parâmetros de consulta e validações de string](query-params-str-validations.md){.internal-link target=_blank}.
E você também pode declarar validações numéricas:
@@ -96,7 +133,7 @@ E você também pode declarar validações numéricas:
/// info | Informação
-`Query`, `Path` e outras classes que você verá a frente são subclasses de uma classe comum `Param`.
+`Query`, `Path` e outras classes que você verá depois são subclasses de uma classe comum `Param`.
Todas elas compartilham os mesmos parâmetros para validação adicional e metadados que você viu.
@@ -106,12 +143,12 @@ Todas elas compartilham os mesmos parâmetros para validação adicional e metad
Quando você importa `Query`, `Path` e outras de `fastapi`, elas são na verdade funções.
-Que quando chamadas, retornam instâncias de classes de mesmo nome.
+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.
+Essas funções existem (em vez de usar diretamente as classes) para que seu editor não marque 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.
+Dessa forma, você pode usar seu editor e ferramentas de codificação normais sem precisar adicionar configurações personalizadas para desconsiderar esses erros.
///
diff --git a/docs/pt/docs/tutorial/path-params.md b/docs/pt/docs/tutorial/path-params.md
index ecf77d676..1f47ca6e5 100644
--- a/docs/pt/docs/tutorial/path-params.md
+++ b/docs/pt/docs/tutorial/path-params.md
@@ -1,207 +1,184 @@
-# Parâmetros da rota da URL
+# Parâmetros de path { #path-parameters }
-Você pode declarar os "parâmetros" ou "variáveis" com a mesma sintaxe utilizada pelo formato de strings do Python:
+Você pode declarar "parâmetros" ou "variáveis" de path com a mesma sintaxe usada por strings de formatação do Python:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.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`.
+O valor do parâmetro de path `item_id` será passado para a sua função como o argumento `item_id`.
-Então, se você rodar este exemplo e for até http://127.0.0.1:8000/items/foo, você verá a seguinte resposta:
+Então, se você executar este exemplo e acessar http://127.0.0.1:8000/items/foo, você verá uma resposta:
```JSON
{"item_id":"foo"}
```
-## Parâmetros da rota com tipos
+## Parâmetros de path com tipos { #path-parameters-with-types }
-Você pode declarar o tipo de um parâmetro na função usando as anotações padrões do Python:
+Você pode declarar o tipo de um parâmetro de path na função, usando as anotações de tipo padrão do Python:
-{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *}
-Nesse caso, `item_id` está sendo declarado como um `int`.
+Neste caso, `item_id` é declarado como um `int`.
/// check | Verifique
-
-
-
+Isso fornecerá suporte do editor dentro da sua função, com verificações de erros, preenchimento automático, etc.
///
- Isso vai dar à você suporte do seu editor dentro das funções, com verificações de erros, autocompletar, etc.
-
-## Conversão de dados
+## Dados conversão { #data-conversion }
-Se você rodar esse exemplo e abrir o seu navegador em http://127.0.0.1:8000/items/3, você verá a seguinte resposta:
+Se você executar este exemplo e abrir seu navegador em http://127.0.0.1:8000/items/3, você verá uma resposta:
```JSON
{"item_id":3}
```
/// check | Verifique
+Perceba que o valor que sua função recebeu (e retornou) é `3`, como um `int` do Python, não uma string `"3"`.
-
-
+Então, com essa declaração de tipo, o **FastAPI** fornece "parsing" automático do request.
///
- Observe que o valor recebido pela função (e também retornado por ela) é `3`, como um Python `int`, não como uma string `"3"`.
-
- Então, com essa declaração de tipo, o **FastAPI** dá pra você um "parsing" automático no request .
-
-## Validação de dados
+## Validação de dados { #data-validation }
-Mas se você abrir o seu navegador em http://127.0.0.1:8000/items/foo, você verá um belo erro HTTP:
+Mas se você for no navegador para http://127.0.0.1:8000/items/foo, verá um bom erro HTTP:
```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"
+ }
+ ]
}
```
-devido ao parâmetro da rota `item_id` ter um valor `"foo"`, que não é um `int`.
+porque o parâmetro de path `item_id` tinha o 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
+O mesmo erro apareceria se você fornecesse um `float` em vez de um `int`, como em: http://127.0.0.1:8000/items/4.2
/// check | Verifique
+Então, com a mesma declaração de tipo do Python, o **FastAPI** fornece validação de dados.
+Observe que o erro também declara claramente exatamente o ponto onde a validação não passou.
-
+Isso é incrivelmente útil ao desenvolver e depurar código que interage com sua API.
///
- 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.
-
- Isso é incrivelmente útil enquanto se desenvolve e debuga o código que interage com a sua API.
-
-## Documentação
+## Documentação { #documentation }
-Quando você abrir o seu navegador em http://127.0.0.1:8000/docs, você verá de forma automática e interativa a documentação da API como:
+E quando você abrir seu navegador em http://127.0.0.1:8000/docs, você verá documentação automática, interativa, da API como:
/// check | Verifique
+Novamente, apenas com a mesma declaração de tipo do Python, o **FastAPI** fornece documentação automática e interativa (integrando o Swagger UI).
-
-
+Observe que o parâmetro de path está declarado como um inteiro.
///
- 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).
+## Benefícios baseados em padrões, documentação alternativa { #standards-based-benefits-alternative-documentation }
-## Beneficios baseados em padrões, documentação alternativa
+E como o schema gerado é do padrão OpenAPI, existem muitas ferramentas compatíveis.
-Devido ao schema gerado ser o padrão do OpenAPI, existem muitas ferramentas compatíveis.
-
-Por esse motivo, o próprio **FastAPI** fornece uma API alternativa para documentação (utilizando ReDoc), que você pode acessar em http://127.0.0.1:8000/redoc:
+Por causa disso, o próprio **FastAPI** fornece uma documentação alternativa da API (usando ReDoc), que você pode acessar em http://127.0.0.1:8000/redoc:
Da mesma forma, existem muitas ferramentas compatíveis. Incluindo ferramentas de geração de código para muitas linguagens.
-## Pydantic
+## Pydantic { #pydantic }
-Toda a validação de dados é feita por baixo dos panos pelo Pydantic, então você tem todos os benefícios disso. E assim você sabe que está em boas mãos.
+Toda a validação de dados é realizada nos bastidores pelo Pydantic, então você recebe todos os benefícios disso. E você sabe que está em boas mãos.
-Você pode usar as mesmas declarações de tipo com `str`, `float`, `bool` e muitos outros tipos complexos de dados.
+Você pode usar as mesmas declarações de tipo com `str`, `float`, `bool` e muitos outros tipos de dados complexos.
-Vamos explorar muitos destes tipos nos próximos capítulos do tutorial.
+Vários deles são explorados nos próximos capítulos do tutorial.
-## A ordem importa
+## A ordem importa { #order-matters }
-Quando você cria operações de rota, você pode se deparar com situações onde você pode ter uma rota fixa.
+Ao criar *operações de rota*, você pode encontrar situações em que tem um path fixo.
-Algo como `/users/me` por exemplo, digamos que essa rota seja utilizada para pegar dados sobre o usuário atual.
+Como `/users/me`, digamos que seja para obter dados sobre o usuário atual.
-E então você pode ter também uma rota `/users/{user_id}` para pegar dados sobre um usuário específico associado a um ID de usuário.
+E então você também pode ter um path `/users/{user_id}` para obter dados sobre um usuário específico por algum ID de usuário.
-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}`:
+Como as *operações de rota* são avaliadas em ordem, você precisa garantir que o path para `/users/me` seja declarado antes do de `/users/{user_id}`:
-{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+{* ../../docs_src/path_params/tutorial003_py39.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"`.
+Caso contrário, o path para `/users/{user_id}` também corresponderia a `/users/me`, "achando" que está recebendo um parâmetro `user_id` com o valor `"me"`.
-## Valores predefinidos
+Da mesma forma, você não pode redefinir uma operação de rota:
-Se você tem uma operação de rota que recebe um parâmetro da rota, mas que você queira que esses valores possíveis do parâmetro da rota sejam predefinidos, você pode usar `Enum` padrão do Python.
+{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
-### Criando uma classe `Enum`
+A primeira sempre será usada, já que o path corresponde primeiro.
-Importe `Enum` e crie uma sub-classe que herde de `str` e de `Enum`.
+## Valores predefinidos { #predefined-values }
-Por herdar de `str` a documentação da API vai ser capaz de saber que os valores devem ser do tipo `string` e assim ser capaz de mostrar eles corretamente.
+Se você tem uma *operação de rota* que recebe um *parâmetro de path*, mas quer que os valores válidos possíveis do *parâmetro de path* sejam predefinidos, você pode usar um `Enum` padrão do Python.
-Assim, crie atributos de classe com valores fixos, que serão os valores válidos disponíveis.
+### Crie uma classe `Enum` { #create-an-enum-class }
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+Importe `Enum` e crie uma subclasse que herde de `str` e de `Enum`.
-/// info | informação
+Ao herdar de `str`, a documentação da API saberá que os valores devem ser do tipo `string` e poderá renderizá-los corretamente.
-Enumerations (ou enums) estão disponíveis no Python desde a versão 3.4.
+Em seguida, crie atributos de classe com valores fixos, que serão os valores válidos disponíveis:
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip | Dica
-
-
-
+Se você está se perguntando, "AlexNet", "ResNet" e "LeNet" são apenas nomes de modelos de Aprendizado de Máquina.
///
- 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*
+### Declare um parâmetro de path { #declare-a-path-parameter }
-Logo, crie um *parâmetro de rota* com anotações de tipo usando a classe enum que você criou (`ModelName`):
+Em seguida, crie um *parâmetro de path* com anotação de tipo usando a classe enum que você criou (`ModelName`):
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
-### Revise a documentação
+### Verifique a documentação { #check-the-docs }
-Visto que os valores disponíveis para o parâmetro da rota estão predefinidos, a documentação interativa pode mostrar esses valores de uma forma bem legal:
+Como os valores disponíveis para o *parâmetro de path* são predefinidos, a documentação interativa pode mostrá-los de forma agradável:
-### Trabalhando com os *enumeration* do Python
+### Trabalhando com *enumerações* do Python { #working-with-python-enumerations }
-O valor do *parâmetro da rota* será um *membro de enumeration*.
+O valor do *parâmetro de path* será um *membro de enumeração*.
-#### Compare *membros de enumeration*
+#### Compare membros de enumeração { #compare-enumeration-members }
-Você pode comparar eles com o *membro de enumeration* no enum `ModelName` que você criou:
+Você pode compará-lo com o *membro de enumeração* no seu enum `ModelName` criado:
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
-#### Obtenha o *valor de enumerate*
+#### Obtenha o valor da enumeração { #get-the-enumeration-value }
-Você pode ter o valor exato de enumerate (um `str` nesse caso) usando `model_name.value`, ou em geral, `your_enum_member.value`:
+Você pode obter o valor real (um `str` neste caso) usando `model_name.value`, ou, em geral, `your_enum_member.value`:
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip | Dica
-
-
-
+Você também pode acessar o valor `"lenet"` com `ModelName.lenet.value`.
///
- Você também poderia acessar o valor `"lenet"` com `ModelName.lenet.value`
-
-#### Retorne *membros de enumeration*
+#### Retorne membros de enumeração { #return-enumeration-members }
-Você pode retornar *membros de enum* da sua *rota de operação*, em um corpo JSON aninhado (por exemplo um `dict`).
+Você pode retornar *membros de enum* da sua *operação de rota*, até mesmo aninhados em um corpo JSON (por exemplo, um `dict`).
-Eles serão convertidos para o seus valores correspondentes (strings nesse caso) antes de serem retornados ao cliente:
+Eles serão convertidos para seus valores correspondentes (strings neste caso) antes de serem retornados ao cliente:
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}
-No seu cliente você vai obter uma resposta JSON como:
+No seu cliente, você receberá uma resposta JSON como:
```JSON
{
@@ -210,56 +187,51 @@ No seu cliente você vai obter uma resposta JSON como:
}
```
-## Parâmetros de rota que contém caminhos
+## Parâmetros de path que contêm paths { #path-parameters-containing-paths }
-Digamos que você tenha uma *operação de rota* com uma rota `/files/{file_path}`.
+Digamos que você tenha uma *operação de rota* com um path `/files/{file_path}`.
-Mas você precisa que o próprio `file_path` contenha uma *rota*, como `home/johndoe/myfile.txt`.
+Mas você precisa que o próprio `file_path` contenha um *path*, como `home/johndoe/myfile.txt`.
-Então, a URL para este arquivo deveria ser algo como: `/files/home/johndoe/myfile.txt`.
+Então, a URL para esse arquivo seria algo como: `/files/home/johndoe/myfile.txt`.
-### Suporte do OpenAPI
+### Suporte do OpenAPI { #openapi-support }
-O OpenAPI não suporta uma maneira de declarar um *parâmetro de rota* que contenha uma *rota* dentro, dado que isso poderia levar a cenários que são difíceis de testar e definir.
+O OpenAPI não oferece suporte a uma maneira de declarar um *parâmetro de path* que contenha um *path* dentro, pois isso poderia levar a cenários difíceis de testar e definir.
-No entanto, você pode fazer isso no **FastAPI**, usando uma das ferramentas internas do Starlette.
+Ainda assim, você pode fazer isso no **FastAPI**, usando uma das ferramentas internas do Starlette.
-A documentação continuaria funcionando, ainda que não adicionaria nenhuma informação dizendo que o parâmetro deveria conter uma rota.
+E a documentação continuará funcionando, embora não adicione nenhuma informação dizendo que o parâmetro deve conter um path.
-### Conversor de rota
+### Conversor de path { #path-convertor }
-Usando uma opção direta do Starlette você pode declarar um *parâmetro de rota* contendo uma *rota* usando uma URL como:
+Usando uma opção diretamente do Starlette você pode declarar um *parâmetro de path* contendo um *path* usando uma URL como:
```
/files/{file_path:path}
```
-Nesse caso, o nome do parâmetro é `file_path`, e a última parte, `:path`, diz que o parâmetro deveria coincidir com qualquer *rota*.
+Nesse caso, o nome do parâmetro é `file_path`, e a última parte, `:path`, diz que o parâmetro deve corresponder a qualquer *path*.
-Então, você poderia usar ele com:
+Então, você pode usá-lo com:
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}
/// tip | Dica
+Você pode precisar que o parâmetro contenha `/home/johndoe/myfile.txt`, com uma barra inicial (`/`).
-
-
+Nesse caso, a URL seria: `/files//home/johndoe/myfile.txt`, com uma barra dupla (`//`) entre `files` e `home`.
///
- 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`.
-
-
-## Recapitulando
+## Recapitulação { #recap }
-Com o **FastAPI**, usando as declarações de tipo do Python, você obtém:
+Com o **FastAPI**, ao usar declarações de tipo do Python curtas, intuitivas e padrão, você obtém:
-* Suporte no editor: verificação de erros, e opção de autocompletar, etc.
-* "Parsing" de dados
-* Validação de dados
-* Anotação da API e documentação automática
+- Suporte no editor: verificações de erro, autocompletar, etc.
+- "Parsing" de dados
+- Validação de dados
+- Anotação da API e documentação automática
-Você apenas tem que declará-los uma vez.
+E você só precisa declará-los uma vez.
-Essa é provavelmente a vantagem mais visível do **FastAPI** se comparado com frameworks alternativos (além do desempenho puro).
+Essa é provavelmente a principal vantagem visível do **FastAPI** em comparação com frameworks alternativos (além do desempenho bruto).
diff --git a/docs/pt/docs/tutorial/query-param-models.md b/docs/pt/docs/tutorial/query-param-models.md
index 01a6e462f..42d2604cd 100644
--- a/docs/pt/docs/tutorial/query-param-models.md
+++ b/docs/pt/docs/tutorial/query-param-models.md
@@ -1,4 +1,4 @@
-# Modelos de Parâmetros de Consulta
+# Modelos de Parâmetros de Consulta { #query-parameter-models }
Se você possui um grupo de **parâmetros de consultas** que são relacionados, você pode criar um **modelo Pydantic** para declará-los.
@@ -10,7 +10,7 @@ Isso é suportado desde o FastAPI versão `0.115.0`. 🤓
///
-## Parâmetros de Consulta com um Modelo Pydantic
+## Parâmetros de Consulta com um Modelo Pydantic { #query-parameters-with-a-pydantic-model }
Declare os **parâmetros de consulta** que você precisa em um **modelo Pydantic**, e então declare o parâmetro como `Query`:
@@ -19,7 +19,7 @@ Declare os **parâmetros de consulta** que você precisa em um **modelo Pydantic
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
+## Verifique os Documentos { #check-the-docs }
Você pode ver os parâmetros de consulta nos documentos de IU em `/docs`:
@@ -27,7 +27,7 @@ Você pode ver os parâmetros de consulta nos documentos de IU em `/docs`:
-### Lista de parâmetros de consulta / múltiplos valores por padrão
+### Lista de parâmetros de consulta / múltiplos valores com valores padrão { #query-parameter-list-multiple-values-with-defaults }
-E você também pode definir uma lista (`list`) de valores padrão caso nenhum seja informado:
+Você também pode definir uma `list` de valores padrão caso nenhum seja fornecido:
-{* ../../docs_src/query_params_str_validations/tutorial012.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
Se você for até:
@@ -193,7 +301,7 @@ Se você for até:
http://localhost:8000/items/
```
-O valor padrão de `q` será: `["foo", "bar"]` e sua resposta será:
+o valor padrão de `q` será: `["foo", "bar"]` e sua resposta será:
```JSON
{
@@ -204,93 +312,163 @@ O valor padrão de `q` será: `["foo", "bar"]` e sua resposta será:
}
```
-#### Usando `list`
+#### Usando apenas `list` { #using-just-list }
-Você também pode utilizar o tipo `list` diretamente em vez de `List[str]`:
+Você também pode usar `list` diretamente em vez de `list[str]`:
-{* ../../docs_src/query_params_str_validations/tutorial013.py hl[7] *}
+{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
-/// note | Observação
+/// note | Nota
-Tenha em mente que neste caso, o FastAPI não irá validar os conteúdos da lista.
+Tenha em mente que, neste caso, o FastAPI não verificará o conteúdo da lista.
-Por exemplo, um `List[int]` iria validar (e documentar) que os contéudos da lista são números inteiros. Mas apenas `list` não.
+Por exemplo, `list[int]` verificaria (e documentaria) que os conteúdos da lista são inteiros. Mas `list` sozinho não.
///
-## Declarando mais metadados
+## Declare mais metadados { #declare-more-metadata }
Você pode adicionar mais informações sobre o parâmetro.
-Essa informações serão inclusas no esquema do OpenAPI e utilizado pela documentação interativa e ferramentas externas.
+Essas informações serão incluídas no OpenAPI gerado e usadas pelas interfaces de documentação e por ferramentas externas.
-/// note | Observação
+/// note | Nota
-Tenha em mente que cada ferramenta oferece diferentes níveis de suporte ao OpenAPI.
+Tenha em mente que ferramentas diferentes podem ter níveis diferentes de suporte ao OpenAPI.
-Algumas delas não exibem todas as informações extras que declaramos, ainda que na maioria dos casos, esses recursos estão planejados para desenvolvimento.
+Algumas delas podem ainda não mostrar todas as informações extras declaradas, embora na maioria dos casos a funcionalidade ausente já esteja planejada para desenvolvimento.
///
Você pode adicionar um `title`:
-{* ../../docs_src/query_params_str_validations/tutorial007.py hl[10] *}
+{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
E uma `description`:
-{* ../../docs_src/query_params_str_validations/tutorial008.py hl[13] *}
+{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## Apelidos (alias) de parâmetros
+## Parâmetros com alias { #alias-parameters }
-Imagine que você queira que um parâmetro tenha o nome `item-query`.
+Imagine que você queira que o parâmetro seja `item-query`.
-Desta maneira:
+Assim:
```
http://127.0.0.1:8000/items/?item-query=foobaritems
```
-Mas o nome `item-query` não é um nome de váriavel válido no Python.
+Mas `item-query` não é um nome de variável Python válido.
-O que mais se aproxima é `item_query`.
+O mais próximo seria `item_query`.
-Mas ainda você precisa que o nome seja exatamente `item-query`...
+Mas você ainda precisa que seja exatamente `item-query`...
-Então você pode declarar um `alias`, e esse apelido (alias) que será utilizado para encontrar o valor do parâmetro:
+Então você pode declarar um `alias`, e esse alias será usado para encontrar o valor do parâmetro:
-{* ../../docs_src/query_params_str_validations/tutorial009.py hl[9] *}
+{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## Parâmetros descontinuados
+## Descontinuando parâmetros { #deprecating-parameters }
-Agora vamos dizer que você não queria mais utilizar um parâmetro.
+Agora digamos que você não gosta mais desse parâmetro.
-Você tem que deixá-lo ativo por um tempo, já que existem clientes o utilizando. Mas você quer que a documentação deixe claro que este parâmetro será descontinuado.
+Você tem que deixá-lo por um tempo, pois há clientes usando-o, mas quer que a documentação mostre claramente que ele está deprecated.
-Então você passa o parâmetro `deprecated=True` para `Query`:
+Então passe o parâmetro `deprecated=True` para `Query`:
-{* ../../docs_src/query_params_str_validations/tutorial010.py hl[18] *}
+{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
-Na documentação aparecerá assim:
+A documentação vai mostrar assim:
-## Recapitulando
+## Excluir parâmetros do OpenAPI { #exclude-parameters-from-openapi }
-Você pode adicionar validações e metadados adicionais aos seus parâmetros.
+Para excluir um parâmetro de consulta do OpenAPI gerado (e portanto, dos sistemas de documentação automáticos), defina o parâmetro `include_in_schema` de `Query` como `False`:
+
+{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
+
+## Validação personalizada { #custom-validation }
+
+Podem existir casos em que você precise fazer alguma **validação personalizada** que não pode ser feita com os parâmetros mostrados acima.
+
+Nesses casos, você pode usar uma **função validadora personalizada** que é aplicada após a validação normal (por exemplo, depois de validar que o valor é uma `str`).
+
+Você pode fazer isso usando o `AfterValidator` do Pydantic dentro de `Annotated`.
+
+/// tip | Dica
+
+O Pydantic também tem `BeforeValidator` e outros. 🤓
+
+///
+
+Por exemplo, este validador personalizado verifica se o ID do item começa com `isbn-` para um número de livro ISBN ou com `imdb-` para um ID de URL de filme IMDB:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
+
+/// info | Informação
-Validações genéricas e metadados:
+Isso está disponível com a versão 2 do Pydantic ou superior. 😎
+
+///
+
+/// tip | Dica
+
+Se você precisar fazer qualquer tipo de validação que exija comunicação com algum **componente externo**, como um banco de dados ou outra API, você deveria usar **Dependências do FastAPI** em vez disso; você aprenderá sobre elas mais adiante.
+
+Esses validadores personalizados são para coisas que podem ser verificadas **apenas** com os **mesmos dados** fornecidos na requisição.
+
+///
+
+### Entenda esse código { #understand-that-code }
+
+O ponto importante é apenas usar **`AfterValidator` com uma função dentro de `Annotated`**. Sinta-se à vontade para pular esta parte. 🤸
+
+---
+
+Mas se você estiver curioso sobre este exemplo de código específico e ainda entretido, aqui vão alguns detalhes extras.
+
+#### String com `value.startswith()` { #string-with-value-startswith }
+
+Percebeu? Uma string usando `value.startswith()` pode receber uma tupla, e verificará cada valor na tupla:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### Um item aleatório { #a-random-item }
+
+Com `data.items()` obtemos um objeto iterável com tuplas contendo a chave e o valor de cada item do dicionário.
+
+Convertimos esse objeto iterável em uma `list` adequada com `list(data.items())`.
+
+Em seguida, com `random.choice()` podemos obter um **valor aleatório** da lista, então obtemos uma tupla com `(id, name)`. Será algo como `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+
+Depois **atribuímos esses dois valores** da tupla às variáveis `id` e `name`.
+
+Assim, se o usuário não fornecer um ID de item, ele ainda receberá uma sugestão aleatória.
+
+...fazemos tudo isso em **uma única linha simples**. 🤯 Você não ama Python? 🐍
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
+
+## Recapitulando { #recap }
+
+Você pode declarar validações adicionais e metadados para seus parâmetros.
+
+Validações e metadados genéricos:
* `alias`
* `title`
* `description`
* `deprecated`
-Validações específicas para textos:
+Validações específicas para strings:
* `min_length`
* `max_length`
-* `regex`
+* `pattern`
+
+Validações personalizadas usando `AfterValidator`.
-Nesses exemplos você viu como declarar validações em valores do tipo `str`.
+Nestes exemplos você viu como declarar validações para valores `str`.
-Leia os próximos capítulos para ver como declarar validação de outros tipos, como números.
+Veja os próximos capítulos para aprender a declarar validações para outros tipos, como números.
diff --git a/docs/pt/docs/tutorial/query-params.md b/docs/pt/docs/tutorial/query-params.md
index 8199de5af..8826602a2 100644
--- a/docs/pt/docs/tutorial/query-params.md
+++ b/docs/pt/docs/tutorial/query-params.md
@@ -1,8 +1,8 @@
-# Parâmetros de Consulta
+# Parâmetros de Consulta { #query-parameters }
Quando você declara outros parâmetros na função que não fazem parte dos parâmetros da rota, esses parâmetros são automaticamente interpretados como parâmetros de "consulta".
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *}
A consulta é o conjunto de pares chave-valor que vai depois de `?` na URL, separado pelo caractere `&`.
@@ -28,7 +28,7 @@ Todo o processo que era aplicado para parâmetros de rota também é aplicado pa
* Validação de dados
* Documentação automática
-## Valores padrão
+## Valores padrão { #defaults }
Como os parâmetros de consulta não são uma parte fixa da rota, eles podem ser opcionais e podem ter valores padrão.
@@ -57,7 +57,7 @@ Os valores dos parâmetros na sua função serão:
* `skip=20`: Por que você definiu isso na URL
* `limit=10`: Por que esse era o valor padrão
-## Parâmetros opcionais
+## Parâmetros opcionais { #optional-parameters }
Da mesma forma, você pode declarar parâmetros de consulta opcionais, definindo o valor padrão para `None`:
@@ -65,13 +65,13 @@ Da mesma forma, você pode declarar parâmetros de consulta opcionais, definindo
Nesse caso, o parâmetro da função `q` será opcional, e `None` será o padrão.
-/// check | Verificar
+/// check | Verifique
Você também pode notar que o **FastAPI** é esperto o suficiente para perceber que o parâmetro da rota `item_id` é um parâmetro da rota, e `q` não é, portanto, `q` é o parâmetro de consulta.
///
-## Conversão dos tipos de parâmetros de consulta
+## Conversão dos tipos de parâmetros de consulta { #query-parameter-type-conversion }
Você também pode declarar tipos `bool`, e eles serão convertidos:
@@ -109,7 +109,7 @@ http://127.0.0.1:8000/items/foo?short=yes
ou qualquer outra variação (tudo em maiúscula, primeira letra em maiúscula, etc), a sua função vai ver o parâmetro `short` com um valor `bool` de `True`. Caso contrário `False`.
-## Múltiplos parâmetros de rota e consulta
+## Múltiplos parâmetros de rota e consulta { #multiple-path-and-query-parameters }
Você pode declarar múltiplos parâmetros de rota e parâmetros de consulta ao mesmo tempo, o **FastAPI** vai saber o quê é o quê.
@@ -119,7 +119,7 @@ Eles serão detectados pelo nome:
{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## Parâmetros de consulta obrigatórios
+## Parâmetros de consulta obrigatórios { #required-query-parameters }
Quando você declara um valor padrão para parâmetros que não são de rota (até agora, nós vimos apenas parâmetros de consulta), então eles não são obrigatórios.
@@ -127,7 +127,7 @@ Caso você não queira adicionar um valor específico mas queira apenas torná-l
Porém, quando você quiser fazer com que o parâmetro de consulta seja obrigatório, você pode simplesmente não declarar nenhum valor como padrão.
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
Aqui o parâmetro de consulta `needy` é um valor obrigatório, do tipo `str`.
@@ -141,16 +141,17 @@ http://127.0.0.1:8000/items/foo-item
```JSON
{
- "detail": [
- {
- "loc": [
- "query",
- "needy"
- ],
- "msg": "field required",
- "type": "value_error.missing"
- }
- ]
+ "detail": [
+ {
+ "type": "missing",
+ "loc": [
+ "query",
+ "needy"
+ ],
+ "msg": "Field required",
+ "input": null
+ }
+ ]
}
```
@@ -181,6 +182,6 @@ Nesse caso, existem 3 parâmetros de consulta:
/// tip | Dica
-Você também poderia usar `Enum` da mesma forma que com [Path Parameters](path-params.md#valores-predefinidos){.internal-link target=_blank}.
+Você também poderia usar `Enum` da mesma forma que com [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
///
diff --git a/docs/pt/docs/tutorial/request-files.md b/docs/pt/docs/tutorial/request-files.md
index c22c1c513..5d0891163 100644
--- a/docs/pt/docs/tutorial/request-files.md
+++ b/docs/pt/docs/tutorial/request-files.md
@@ -1,4 +1,4 @@
-# Arquivos de Requisição
+# Arquivos de Requisição { #request-files }
Você pode definir arquivos para serem enviados pelo cliente usando `File`.
@@ -16,13 +16,13 @@ Isso é necessário, visto que os arquivos enviados são enviados como "dados de
///
-## Importe `File`
+## Importe `File` { #import-file }
Importe `File` e `UploadFile` de `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## Definir Parâmetros `File`
+## Definir Parâmetros `File` { #define-file-parameters }
Crie parâmetros de arquivo da mesma forma que você faria para `Body` ou `Form`:
@@ -50,7 +50,7 @@ Mantenha em mente que isso significa que todo o conteúdo será armazenado na me
Mas há muitos casos em que você pode se beneficiar do uso de `UploadFile`.
-## Parâmetros de Arquivo com `UploadFile`
+## Parâmetros de Arquivo com `UploadFile` { #file-parameters-with-uploadfile }
Defina um parâmetro de arquivo com um tipo de `UploadFile`:
@@ -66,12 +66,12 @@ Utilizar `UploadFile` tem várias vantagens sobre `bytes`:
* Ele tem uma file-like interface `assíncrona`.
* Ele expõe um objeto python `SpooledTemporaryFile` que você pode passar diretamente para outras bibliotecas que esperam um objeto semelhante a um arquivo("file-like").
-### `UploadFile`
+### `UploadFile` { #uploadfile }
`UploadFile` tem os seguintes atributos:
* `filename`: Uma `str` com o nome do arquivo original que foi enviado (por exemplo, `myimage.jpg`).
-* `content_type`: Uma `str` com o tipo de conteúdo (tipo MIME / tipo de mídia) (por exemplo, `image/jpeg`).
+* `content_type`: Uma `str` com o tipo de conteúdo (MIME type / media type) (por exemplo, `image/jpeg`).
* `file`: Um `SpooledTemporaryFile` (um file-like objeto). Este é o objeto de arquivo Python que você pode passar diretamente para outras funções ou bibliotecas que esperam um objeto semelhante a um arquivo("file-like").
`UploadFile` tem os seguintes métodos `assíncronos`. Todos eles chamam os métodos de arquivo correspondentes por baixo dos panos (usando o `SpooledTemporaryFile` interno).
@@ -105,11 +105,11 @@ Quando você usa os métodos `async`, o **FastAPI** executa os métodos de arqui
/// note | Detalhes Técnicos do Starlette
-O `UploadFile` do ***FastAPI** herda diretamente do `UploadFile` do **Starlette** , mas adiciona algumas partes necessárias para torná-lo compatível com o **Pydantic** e as outras partes do FastAPI.
+O `UploadFile` do **FastAPI** herda diretamente do `UploadFile` do **Starlette**, mas adiciona algumas partes necessárias para torná-lo compatível com o **Pydantic** e as outras partes do FastAPI.
///
-## O que é "Form Data"
+## O que é "Form Data" { #what-is-form-data }
O jeito que os formulários HTML (``) enviam os dados para o servidor normalmente usa uma codificação "especial" para esses dados, a qual é diferente do JSON.
@@ -117,15 +117,15 @@ O jeito que os formulários HTML (``) enviam os dados para o servid
/// note | Detalhes Técnicos
-Dados de formulários normalmente são codificados usando o "media type" (tipo de mídia) `application/x-www-form-urlencoded` quando não incluem arquivos.
+Dados de formulários normalmente são codificados usando o "media type" `application/x-www-form-urlencoded` quando não incluem arquivos.
Mas quando o formulário inclui arquivos, ele é codificado como `multipart/form-data`. Se você usar `File`, o **FastAPI** saberá que tem que pegar os arquivos da parte correta do corpo da requisição.
-Se você quiser ler mais sobre essas codificações e campos de formulário, vá para a MDN web docs para POST.
+Se você quiser ler mais sobre essas codificações e campos de formulário, vá para a MDN web docs para POST.
///
-/// warning | Aviso
+/// warning | Atenção
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`.
@@ -133,19 +133,19 @@ Isso não é uma limitação do **FastAPI**, é parte do protocolo HTTP.
///
-## Upload de Arquivo Opcional
+## Upload de Arquivo Opcional { #optional-file-upload }
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
+## `UploadFile` com Metadados Adicionais { #uploadfile-with-additional-metadata }
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
+## Uploads de Múltiplos Arquivos { #multiple-file-uploads }
É possível realizar o upload de vários arquivos ao mesmo tempo.
@@ -165,12 +165,12 @@ Você pode também pode usar `from starlette.responses import HTMLResponse`.
///
-### Uploads de Múltiplos Arquivos com Metadados Adicionais
+### Uploads de Múltiplos Arquivos com Metadados Adicionais { #multiple-file-uploads-with-additional-metadata }
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
+## Recapitulando { #recap }
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
index ea0e63d38..8eeffac2a 100644
--- a/docs/pt/docs/tutorial/request-form-models.md
+++ b/docs/pt/docs/tutorial/request-form-models.md
@@ -1,4 +1,4 @@
-# Modelos de Formulários
+# Modelos de Formulários { #form-models }
Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários** no FastAPI.
@@ -20,7 +20,7 @@ Isto é suportado desde a versão `0.113.0` do FastAPI. 🤓
///
-## Modelos Pydantic para Formulários
+## Modelos Pydantic para Formulários { #pydantic-models-for-forms }
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`:
@@ -28,7 +28,7 @@ Você precisa apenas declarar um **modelo Pydantic** com os campos que deseja re
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
+## Confira os Documentos { #check-the-docs }
Você pode verificar na UI de documentação em `/docs`:
@@ -36,7 +36,7 @@ Você pode verificar na UI de documentação em `/docs`:
POST.
+Se você quiser ler mais sobre essas codificações e campos de formulário, vá para o MDN web docs para POST.
///
-/// warning | Aviso
+/// warning | Atenção
-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`.
+Você pode declarar vários parâmetros `Form` em uma *operação de rota*, mas não pode declarar campos `Body` que espera receber como JSON, pois a requisiçã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.
+Isso não é uma limitação do **FastAPI**, é parte do protocolo HTTP.
///
-## Recapitulando
+## Recapitulando { #recap }
Use `Form` para declarar os parâmetros de entrada de dados de formulário.
diff --git a/docs/pt/docs/tutorial/request_files.md b/docs/pt/docs/tutorial/request_files.md
deleted file mode 100644
index 15c1ad825..000000000
--- a/docs/pt/docs/tutorial/request_files.md
+++ /dev/null
@@ -1,172 +0,0 @@
-# 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
index 6726a20a7..8a7a71248 100644
--- a/docs/pt/docs/tutorial/response-model.md
+++ b/docs/pt/docs/tutorial/response-model.md
@@ -1,6 +1,6 @@
-# Modelo de resposta - Tipo de retorno
+# Modelo de resposta - Tipo de retorno { #response-model-return-type }
-Você pode declarar o tipo usado para a resposta anotando o **tipo de retorno** *da função de operação de rota*.
+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.
@@ -10,7 +10,7 @@ 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.
+* Adicionar um **JSON Schema** 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.
@@ -19,7 +19,7 @@ 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`
+## Parâmetro `response_model` { #response-model-parameter }
Existem alguns casos em que você precisa ou deseja retornar alguns dados que não são exatamente o que o tipo declara.
@@ -27,7 +27,7 @@ Por exemplo, você pode querer **retornar um dicionário** ou um objeto de banco
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.
+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*:
@@ -45,7 +45,7 @@ Observe que `response_model` é um parâmetro do método "decorator" (`get`, `po
///
-`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]`.
+`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 `list` 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.
@@ -57,7 +57,7 @@ Dessa forma, você diz ao editor que está retornando qualquer coisa intencional
///
-### Prioridade `response_model`
+### Prioridade `response_model` { #response-model-priority }
Se você declarar tanto um tipo de retorno quanto um `response_model`, o `response_model` terá prioridade e será usado pelo FastAPI.
@@ -65,7 +65,7 @@ Dessa forma, você pode adicionar anotações de tipo corretas às suas funçõe
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
+## Retorne os mesmos dados de entrada { #return-the-same-input-data }
Aqui estamos declarando um modelo `UserIn`, ele conterá uma senha em texto simples:
@@ -99,13 +99,13 @@ Neste caso, pode não ser um problema, porque é o mesmo usuário enviando a sen
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
+/// danger | Cuidado
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
+## Adicione um modelo de saída { #add-an-output-model }
Podemos, em vez disso, criar um modelo de entrada com a senha em texto simples e um modelo de saída sem ela:
@@ -121,7 +121,7 @@ Aqui, embora nossa *função de operação de rota* esteja retornando o mesmo us
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
+### `response_model` ou Tipo de Retorno { #response-model-or-return-type }
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.
@@ -129,7 +129,7 @@ Neste caso, como os dois modelos são diferentes, se anotássemos o tipo de reto
...mas continue lendo abaixo para ver como superar isso.
-## Tipo de Retorno e Filtragem de Dados
+## Tipo de Retorno e Filtragem de Dados { #return-type-and-data-filtering }
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**.
@@ -147,7 +147,7 @@ Com isso, temos suporte de ferramentas, de editores e mypy, pois este código es
Como isso funciona? Vamos verificar. 🤓
-### Anotações de tipo e ferramentas
+### Anotações de tipo e ferramentas { #type-annotations-and-tooling }
Primeiro, vamos ver como editores, mypy e outras ferramentas veriam isso.
@@ -157,7 +157,7 @@ Anotamos o tipo de retorno da função como `BaseUser`, mas na verdade estamos r
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
+### Filtragem de dados FastAPI { #fastapi-data-filtering }
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.
@@ -165,7 +165,7 @@ O FastAPI faz várias coisas internamente com o Pydantic para garantir que essas
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
+## Veja na documentação { #see-it-in-the-docs }
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:
@@ -175,29 +175,29 @@ E ambos os modelos serão usados para a documentação interativa da API:
-## Outras anotações de tipo de retorno
+## Outras anotações de tipo de retorno { #other-return-type-annotations }
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
+### Retorne uma Response diretamente { #return-a-response-directly }
-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}.
+O caso mais comum seria [retornar uma Response 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] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.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
+### Anote uma subclasse de Response { #annotate-a-response-subclass }
Você também pode usar uma subclasse de `Response` na anotação de tipo:
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.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
+### Anotações de Tipo de Retorno Inválido { #invalid-return-type-annotations }
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á.
@@ -205,9 +205,9 @@ O mesmo aconteceria se você tivesse algo como uma
/// note | Nota
-
+Não importa o que você digite no formulário, ainda não vai funcionar. Mas nós vamos chegar lá.
///
- 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.
+Claro que este não é o frontend para os usuários finais, mas é uma ótima ferramenta automática para documentar interativamente toda a sua API.
-Pode ser usado pelo time de frontend (que pode ser você no caso).
+Pode ser usada pelo time de frontend (que pode ser você mesmo).
-Pode ser usado por aplicações e sistemas third party (de terceiros).
+Pode ser usada por aplicações e sistemas de terceiros.
-E também pode ser usada por você mesmo, para debugar, checar e testar a mesma aplicação.
+E também pode ser usada por você mesmo, para depurar, verificar e testar a mesma aplicação.
-## O Fluxo da `senha`
+## O fluxo de `password` { #the-password-flow }
Agora vamos voltar um pouco e entender o que é isso tudo.
-O "fluxo" da `senha` é um dos caminhos ("fluxos") definidos no OAuth2, para lidar com a segurança e autenticação.
+O "fluxo" `password` é uma das formas ("fluxos") definidas no OAuth2 para lidar com segurança e autenticação.
-OAuth2 foi projetado para que o backend ou a API pudesse ser independente do servidor que autentica o usuário.
+O OAuth2 foi projetado para que o backend ou a API pudesse ser independente do servidor que autentica o usuário.
-Mas nesse caso, a mesma aplicação **FastAPI** irá lidar com a API e a autenticação.
+Mas, neste caso, a mesma aplicação **FastAPI** irá lidar com a API e com a autenticação.
Então, vamos rever de um ponto de vista simplificado:
-* O usuário digita o `username` e a `senha` no frontend e aperta `Enter`.
-* O frontend (rodando no browser do usuário) manda o `username` e a `senha` para uma URL específica na sua API (declarada com `tokenUrl="token"`).
-* A API checa aquele `username` e `senha`, e responde com um "token" (nós não implementamos nada disso ainda).
- * Um "token" é apenas uma string com algum conteúdo que nós podemos utilizar mais tarde para verificar o usuário.
- * Normalmente, um token é definido para expirar depois de um tempo.
- * Então, o usuário terá que se logar de novo depois de um tempo.
- * E se o token for roubado, o risco é menor. Não é como se fosse uma chave permanente que vai funcionar para sempre (na maioria dos casos).
- * O frontend armazena aquele token temporariamente em algum lugar.
- * O usuário clica no frontend para ir à outra seção daquele frontend do aplicativo web.
- * O frontend precisa buscar mais dados daquela API.
- * Mas precisa de autenticação para aquele endpoint em específico.
- * Então, para autenticar com nossa API, ele manda um header de `Autorização` com o valor `Bearer` mais o token.
- * Se o token contém `foobar`, o conteúdo do header de `Autorização` será: `Bearer foobar`.
+* O usuário digita o `username` e o `password` no frontend e pressiona `Enter`.
+* O frontend (rodando no navegador do usuário) envia esse `username` e `password` para uma URL específica na nossa API (declarada com `tokenUrl="token"`).
+* A API verifica esse `username` e `password`, e responde com um "token" (ainda não implementamos nada disso).
+ * Um "token" é apenas uma string com algum conteúdo que podemos usar depois para verificar esse usuário.
+ * Normalmente, um token é definido para expirar depois de algum tempo.
+ * Então, o usuário terá que fazer login novamente em algum momento.
+ * E se o token for roubado, o risco é menor. Não é como uma chave permanente que funcionará para sempre (na maioria dos casos).
+* O frontend armazena esse token temporariamente em algum lugar.
+* O usuário clica no frontend para ir para outra seção do aplicativo web.
+* O frontend precisa buscar mais dados da API.
+ * Mas precisa de autenticação para aquele endpoint específico.
+ * Então, para autenticar com nossa API, ele envia um header `Authorization` com o valor `Bearer ` mais o token.
+ * Se o token contém `foobar`, o conteúdo do header `Authorization` seria: `Bearer foobar`.
-## **FastAPI**'s `OAuth2PasswordBearer`
+## O `OAuth2PasswordBearer` do **FastAPI** { #fastapis-oauth2passwordbearer }
-**FastAPI** fornece várias ferramentas, em diferentes níveis de abstração, para implementar esses recursos de segurança.
+O **FastAPI** fornece várias ferramentas, em diferentes níveis de abstração, para implementar essas funcionalidades de segurança.
-Neste exemplo, nós vamos usar o **OAuth2** com o fluxo de **Senha**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`.
+Neste exemplo, vamos usar **OAuth2**, com o fluxo **Password**, 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 para o nosso caso de uso.
-///
-
- Um token "bearer" não é a única opção.
+E pode ser a melhor para a maioria dos casos de uso, a menos que você seja um especialista em OAuth2 e saiba exatamente por que existe outra opção que se adapta melhor às suas necessidades.
- Mas é a melhor no nosso caso.
+Nesse caso, o **FastAPI** também fornece as ferramentas para construí-la.
- E talvez seja a melhor para a maioria dos casos, a não ser que você seja um especialista em OAuth2 e saiba exatamente o porquê de existir outras opções que se adequam melhor às suas necessidades.
-
- Nesse caso, **FastAPI** também fornece as ferramentas para construir.
+///
-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.
+Quando criamos uma instância da classe `OAuth2PasswordBearer`, passamos o parâmetro `tokenUrl`. Esse parâmetro contém a URL que o client (o frontend rodando no navegador do usuário) usará para enviar o `username` e o `password` para obter um token.
-{* ../../docs_src/security/tutorial001.py hl[6] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
/// tip | Dica
+Aqui `tokenUrl="token"` refere-se a uma URL relativa `token` que ainda não criamos. Como é uma URL relativa, é equivalente a `./token`.
+Como estamos usando uma URL relativa, se sua API estivesse localizada em `https://example.com/`, então se referiria a `https://example.com/token`. Mas se sua API estivesse localizada em `https://example.com/api/v1/`, então se referiria a `https://example.com/api/v1/token`.
-///
-
- 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`.
+Usar uma URL relativa é importante para garantir que sua aplicação continue funcionando mesmo em um caso de uso avançado como [Atrás de um Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
- Usar uma URL relativa é importante para garantir que sua aplicação continue funcionando, mesmo em um uso avançado tipo [Atrás de um Proxy](../../advanced/behind-a-proxy.md){.internal-link target=_blank}.
+///
-Esse parâmetro não cria um endpoint / *path operation*, mas declara que a URL `/token` vai ser aquela que o client deve usar para obter o token. Essa informação é usada no OpenAPI, e depois na API Interativa de documentação de sistemas.
+Esse parâmetro não cria aquele endpoint/operação de rota, mas declara que a URL `/token` será aquela que o client deve usar para obter o token. Essa informação é usada no OpenAPI e depois nos sistemas de documentação interativa da API.
-Em breve também criaremos o atual path operation.
+Em breve também criaremos a operação de rota real.
-/// info | informação
+/// info | Informação
+Se você é um "Pythonista" muito rigoroso, pode não gostar do estilo do nome do parâmetro `tokenUrl` em vez de `token_url`.
+Isso ocorre porque ele usa o mesmo nome da especificação do OpenAPI. Assim, se você precisar investigar mais sobre qualquer um desses esquemas de segurança, pode simplesmente copiar e colar para encontrar mais informações sobre isso.
///
- 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.
-
-A variável `oauth2_scheme` é um instância de `OAuth2PasswordBearer`, mas também é um "callable".
+A variável `oauth2_scheme` é uma instância de `OAuth2PasswordBearer`, mas também é "chamável" (callable).
-Pode ser chamada de:
+Ela pode ser chamada como:
```Python
oauth2_scheme(some, parameters)
```
-Então, pode ser usado com `Depends`.
+Então, pode ser usada com `Depends`.
-## Use-o
+### Use-o { #use-it }
-Agora você pode passar aquele `oauth2_scheme` em uma dependência com `Depends`.
+Agora você pode passar esse `oauth2_scheme` em uma dependência com `Depends`.
-{* ../../docs_src/security/tutorial001.py hl[10] *}
+{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
-Esse dependência vai fornecer uma `str` que é atribuído ao parâmetro `token da *função do path operation*
+Essa dependência fornecerá uma `str` que é atribuída ao parâmetro `token` da função de operação de rota.
-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).
+O **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema OpenAPI (e na documentação automática da API).
-/// info | Detalhes técnicos
+/// info | Detalhes Técnicos
+O **FastAPI** saberá que pode usar a classe `OAuth2PasswordBearer` (declarada em uma dependência) para definir o esquema de segurança no OpenAPI porque ela 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 o OpenAPI (e com a documentação automática da API) herdam de `SecurityBase`, é assim que o **FastAPI** sabe como integrá-los ao OpenAPI.
///
- **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.
-
-## O que ele faz
+## O que ele faz { #what-it-does }
-Ele irá e olhará na requisição para aquele header de `Autorização`, verificará se o valor é `Bearer` mais algum token, e vai retornar o token como uma `str`
+Ele irá procurar na requisição pelo header `Authorization`, verificar se o valor é `Bearer ` mais algum token e retornará o token como uma `str`.
-Se ele não ver o header de `Autorização` ou o valor não tem um token `Bearer`, vai responder com um código de erro 401 (`UNAUTHORIZED`) diretamente.
+Se não houver um header `Authorization`, ou se o valor não tiver um token `Bearer `, ele responderá diretamente com um erro de status 401 (`UNAUTHORIZED`).
-Você nem precisa verificar se o token existe para retornar um erro. Você pode ter certeza de que se a sua função for executada, ela terá um `str` nesse token.
+Você nem precisa verificar se o token existe para retornar um erro. Você pode ter certeza de que, se sua função for executada, ela terá uma `str` nesse token.
Você já pode experimentar na documentação interativa:
-Não estamos verificando a validade do token ainda, mas isso já é um começo
+Ainda não estamos verificando a validade do token, mas isso já é um começo.
-## Recapitulando
+## Recapitulando { #recap }
-Então, em apenas 3 ou 4 linhas extras, você já tem alguma forma primitiva de segurança.
+Então, com apenas 3 ou 4 linhas extras, você já tem alguma forma primitiva de segurança.
diff --git a/docs/pt/docs/tutorial/security/get-current-user.md b/docs/pt/docs/tutorial/security/get-current-user.md
index 1a2badb83..2135ae236 100644
--- a/docs/pt/docs/tutorial/security/get-current-user.md
+++ b/docs/pt/docs/tutorial/security/get-current-user.md
@@ -1,105 +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`.
-
+# Obter Usuário Atual { #get-current-user }
+
+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 { #create-a-user-model }
+
+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` { #create-a-get-current-user-dependency }
+
+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-the-user }
+
+`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 { #inject-the-current-user }
+
+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 { #other-models }
+
+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 { #code-size }
+
+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 { #recap }
+
+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 2ebb87fcd..d3de3e050 100644
--- a/docs/pt/docs/tutorial/security/index.md
+++ b/docs/pt/docs/tutorial/security/index.md
@@ -1,4 +1,4 @@
-# Segurança
+# Segurança { #security }
Há várias formas de lidar segurança, autenticação e autorização.
@@ -10,11 +10,11 @@ Em muitos frameworks e sistemas, apenas lidar com segurança e autenticação ex
Mas primeiro, vamos verificar alguns pequenos conceitos.
-## Está com pressa?
+## Está com pressa? { #in-a-hurry }
Se você não se importa com qualquer um desses termos e só precisa adicionar segurança com autenticação baseada em usuário e senha _agora_, pule para os próximos capítulos.
-## OAuth2
+## OAuth2 { #oauth2 }
OAuth2 é uma especificação que define várias formas para lidar com autenticação e autorização.
@@ -24,7 +24,7 @@ Ela inclui uma forma para autenticação usando “third party”/aplicações d
Isso é o que todos os sistemas com “Login with Facebook, Google, X (Twitter), GitHub” usam por baixo.
-### OAuth 1
+### OAuth 1 { #oauth-1 }
Havia um OAuth 1, que é bem diferente do OAuth2, e mais complexo, isso incluía diretamente as especificações de como criptografar a comunicação.
@@ -38,7 +38,7 @@ Na seção sobre **deployment** você irá ver como configurar HTTPS de modo gra
///
-## OpenID Connect
+## OpenID Connect { #openid-connect }
OpenID Connect é outra especificação, baseada em **OAuth2**.
@@ -48,7 +48,7 @@ Por exemplo, o login do Google usa OpenID Connect (que por baixo dos panos usa O
Mas o login do Facebook não tem suporte para OpenID Connect. Ele tem a própria implementação do OAuth2.
-### OpenID (não "OpenID Connect")
+### OpenID (não "OpenID Connect") { #openid-not-openid-connect }
Houve também uma especificação “OpenID”. Ela tentou resolver a mesma coisa que a **OpenID Connect**, mas não baseada em OAuth2.
@@ -56,7 +56,7 @@ Então, ela foi um sistema adicional completo.
Ela não é muito popular ou usada nos dias de hoje.
-## OpenAPI
+## OpenAPI { #openapi }
OpenAPI (anteriormente conhecido como Swagger) é a especificação aberta para a criação de APIs (agora parte da Linux Foundation).
@@ -97,7 +97,7 @@ O problema mais complexo é criar um provedor de autenticação/autorização co
///
-## **FastAPI** utilitários
+## **FastAPI** utilitários { #fastapi-utilities }
**FastAPI** fornece várias ferramentas para cada um desses esquemas de segurança no módulo `fastapi.security` que simplesmente usa esses mecanismos de segurança.
diff --git a/docs/pt/docs/tutorial/security/oauth2-jwt.md b/docs/pt/docs/tutorial/security/oauth2-jwt.md
index 7d80d12fa..f68b8c39e 100644
--- a/docs/pt/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/pt/docs/tutorial/security/oauth2-jwt.md
@@ -1,4 +1,4 @@
-# OAuth2 com Senha (e hashing), Bearer com tokens JWT
+# OAuth2 com Senha (e hashing), Bearer com tokens JWT { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
Agora que temos todo o fluxo de segurança, vamos tornar a aplicação realmente segura, usando tokens JWT e hashing de senhas seguras.
@@ -6,7 +6,7 @@ Este código é algo que você pode realmente usar na sua aplicação, salvar os
Vamos começar de onde paramos no capítulo anterior e incrementá-lo.
-## Sobre o JWT
+## Sobre o JWT { #about-jwt }
JWT significa "JSON Web Tokens".
@@ -26,7 +26,7 @@ Depois de uma semana, o token expirará e o usuário não estará autorizado, pr
Se você quiser brincar com tokens JWT e ver como eles funcionam, visite https://jwt.io.
-## Instalar `PyJWT`
+## Instalar `PyJWT` { #install-pyjwt }
Nós precisamos instalar o `PyJWT` para criar e verificar os tokens JWT em Python.
@@ -50,7 +50,7 @@ Você pode ler mais sobre isso na
```console
-$ pip install "passlib[bcrypt]"
+$ pip install "pwdlib[argon2]"
---> 100%
```
@@ -86,7 +86,7 @@ $ pip install "passlib[bcrypt]"
/// tip | Dica
-Com o `passlib`, você poderia até configurá-lo para ser capaz de ler senhas criadas pelo **Django**, um plug-in de segurança do **Flask** ou muitos outros.
+Com o `pwdlib`, você poderia até configurá-lo para ser capaz de ler senhas criadas pelo **Django**, um plug-in de segurança do **Flask** ou muitos outros.
Assim, você poderia, por exemplo, compartilhar os mesmos dados de um aplicativo Django em um banco de dados com um aplicativo FastAPI. Ou migrar gradualmente uma aplicação Django usando o mesmo banco de dados.
@@ -94,17 +94,17 @@ E seus usuários poderiam fazer login tanto pela sua aplicação Django quanto p
///
-## Criar o hash e verificar as senhas
+## Criar o hash e verificar as senhas { #hash-and-verify-the-passwords }
-Importe as ferramentas que nós precisamos de `passlib`.
+Importe as ferramentas que nós precisamos de `pwdlib`.
-Crie um "contexto" do PassLib. Este será usado para criar o hash e verificar as senhas.
+Crie uma instância de PasswordHash com as configurações recomendadas – ela será usada para criar o hash e verificar as senhas.
/// tip | Dica
-O contexto do PassLib também possui funcionalidades para usar diferentes algoritmos de hashing, incluindo algoritmos antigos que estão obsoletos, apenas para permitir verificá-los, etc.
+pwdlib também oferece suporte ao algoritmo de hashing bcrypt, mas não inclui algoritmos legados – para trabalhar com hashes antigos, é recomendado usar a biblioteca passlib.
-Por exemplo, você poderia usá-lo para ler e verificar senhas geradas por outro sistema (como Django), mas criar o hash de novas senhas com um algoritmo diferente, como o Bcrypt.
+Por exemplo, você poderia usá-lo para ler e verificar senhas geradas por outro sistema (como Django), mas criar o hash de novas senhas com um algoritmo diferente, como o Argon2 ou o Bcrypt.
E ser compatível com todos eles ao mesmo tempo.
@@ -120,11 +120,11 @@ E outra para autenticar e retornar um usuário.
/// note | Nota
-Se você verificar o novo banco de dados (falso) `fake_users_db`, você verá como o hash da senha se parece agora: `"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`.
+Se você verificar o novo banco de dados (falso) `fake_users_db`, você verá como o hash da senha se parece agora: `"$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc"`.
///
-## Manipular tokens JWT
+## Manipular tokens JWT { #handle-jwt-tokens }
Importe os módulos instalados.
@@ -154,7 +154,7 @@ Crie uma função utilitária para gerar um novo token de acesso.
{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
-## Atualize as dependências
+## Atualize as dependências { #update-the-dependencies }
Atualize `get_current_user` para receber o mesmo token de antes, mas desta vez, usando tokens JWT.
@@ -164,7 +164,7 @@ Se o token for inválido, retorne um erro HTTP imediatamente.
{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *}
-## Atualize a *operação de rota* `/token`
+## Atualize a *operação de rota* `/token` { #update-the-token-path-operation }
Crie um `timedelta` com o tempo de expiração do token.
@@ -172,7 +172,7 @@ Crie um token de acesso JWT real e o retorne.
{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *}
-### Detalhes técnicos sobre o "sujeito" `sub` do JWT
+### Detalhes técnicos sobre o "sujeito" `sub` do JWT { #technical-details-about-the-jwt-subject-sub }
A especificação JWT diz que existe uma chave `sub`, com o sujeito do token.
@@ -194,7 +194,7 @@ Então, para evitar colisões de ID, ao criar o token JWT para o usuário, você
O importante a se lembrar é que a chave `sub` deve ter um identificador único em toda a aplicação e deve ser uma string.
-## Testando
+## Verifique { #check-it }
Execute o servidor e vá para a documentação: http://127.0.0.1:8000/docs.
@@ -240,7 +240,7 @@ Perceba que o cabeçalho `Authorization`, com o valor que começa com `Bearer `.
///
-## Uso avançado com `scopes`
+## Uso avançado com `scopes` { #advanced-usage-with-scopes }
O OAuth2 tem a noção de "scopes" (escopos).
@@ -250,8 +250,7 @@ Então, você pode dar este token diretamente a um usuário ou a uma terceira pa
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
+## Recapitulação { #recap }
Com o que você viu até agora, você pode configurar uma aplicação **FastAPI** segura usando padrões como OAuth2 e JWT.
@@ -265,7 +264,7 @@ O **FastAPI** não faz nenhuma concessão com nenhum banco de dados, modelo de d
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.
+E você pode usar diretamente muitos pacotes bem mantidos e amplamente utilizados, como `pwdlib` 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.
diff --git a/docs/pt/docs/tutorial/security/simple-oauth2.md b/docs/pt/docs/tutorial/security/simple-oauth2.md
index 1cf05785e..902ae2d22 100644
--- a/docs/pt/docs/tutorial/security/simple-oauth2.md
+++ b/docs/pt/docs/tutorial/security/simple-oauth2.md
@@ -1,8 +1,8 @@
-# Simples OAuth2 com senha e Bearer
+# Simples OAuth2 com senha e Bearer { #simple-oauth2-with-password-and-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)
+## Obtenha o `username` e a `password` { #get-the-username-and-password }
É utilizado o utils de segurança da **FastAPI** para obter o `username` e a `password`.
@@ -18,9 +18,9 @@ Mas para a *operação de rota* de login, precisamos usar esses nomes para serem
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`
+### `scope` { #scope }
-A especificação também diz que o cliente pode enviar outro campo de formulário "`scope`" (Escopo).
+A especificação também diz que o cliente pode enviar outro campo de formulário "`scope`".
O nome do campo do formulário é `scope` (no singular), mas na verdade é uma longa string com "escopos" separados por espaços.
@@ -44,11 +44,11 @@ Para OAuth2 são apenas strings.
///
-## Código para conseguir o `username` e a `password`
+## Código para conseguir o `username` e a `password` { #code-to-get-the-username-and-password }
Agora vamos usar os utilitários fornecidos pelo **FastAPI** para lidar com isso.
-### `OAuth2PasswordRequestForm`
+### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }
Primeiro, importe `OAuth2PasswordRequestForm` e use-o como uma dependência com `Depends` na *operação de rota* para `/token`:
@@ -59,7 +59,7 @@ Primeiro, importe `OAuth2PasswordRequestForm` e use-o como uma dependência 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.
+* Um `grant_type` opcional.
/// tip | Dica
@@ -84,7 +84,7 @@ Mas como é um caso de uso comum, ele é fornecido diretamente pelo **FastAPI**,
///
-### Use os dados do formulário
+### Use os dados do formulário { #use-the-form-data }
/// tip | Dica
@@ -96,13 +96,13 @@ Não estamos usando `scopes` neste exemplo, mas a funcionalidade está disponív
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).
+Se não existir tal usuário, retornaremos um erro dizendo "Incorrect username or password".
Para o erro, usamos a exceção `HTTPException`:
{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
-### Confira a password (senha)
+### Confira a senha { #check-the-password }
Neste ponto temos os dados do usuário do nosso banco de dados, mas não verificamos a senha.
@@ -112,7 +112,7 @@ Você nunca deve salvar senhas em texto simples, portanto, usaremos o sistema de
Se as senhas não corresponderem, retornaremos o mesmo erro.
-#### Hashing de senha
+#### Hashing de senha { #password-hashing }
"Hashing" significa: converter algum conteúdo (uma senha neste caso) em uma sequência de bytes (apenas uma string) que parece algo sem sentido.
@@ -120,7 +120,7 @@ Sempre que você passa exatamente o mesmo conteúdo (exatamente a mesma senha),
Mas você não pode converter a sequência aleatória de caracteres de volta para a senha.
-##### Porque usar hashing de senha
+##### Porque usar hashing de senha { #why-use-password-hashing }
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.
@@ -128,11 +128,11 @@ Assim, o ladrão não poderá tentar usar essas mesmas senhas em outro sistema (
{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-#### Sobre `**user_dict`
+#### Sobre `**user_dict` { #about-user-dict }
`UserInDB(**user_dict)` significa:
-*Passe as keys (chaves) e values (valores) de `user_dict` diretamente como argumentos de valor-chave, equivalente a:*
+*Passe as chaves e valores de `user_dict` diretamente como argumentos de valor-chave, equivalente a:*
```Python
UserInDB(
@@ -146,11 +146,11 @@ UserInDB(
/// 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}.
+Para uma explicação mais completa de `**user_dict`, verifique [a documentação para **Extra Models**](../extra-models.md#about-user-in-dict){.internal-link target=_blank}.
///
-## Retorne o token
+## Retorne o token { #return-the-token }
A resposta do endpoint `token` deve ser um objeto JSON.
@@ -182,11 +182,11 @@ De resto, **FastAPI** cuida disso para você.
///
-## Atualize as dependências
+## Atualize as dependências { #update-the-dependencies }
Agora vamos atualizar nossas dependências.
-Queremos obter o `user_user` *somente* se este usuário estiver ativo.
+Queremos obter o `current_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.
@@ -214,11 +214,11 @@ Esse é o benefício dos padrões...
///
-## Veja em ação
+## Veja em ação { #see-it-in-action }
Abra o docs interativo: http://127.0.0.1:8000/docs.
-### Autenticação
+### Autentique-se { #authenticate }
Clique no botão "Authorize".
@@ -234,7 +234,7 @@ Após autenticar no sistema, você verá assim:
-### Obtenha seus próprios dados de usuário
+### Obtenha seus próprios dados de usuário { #get-your-own-user-data }
Agora use a operação `GET` com o caminho `/users/me`.
@@ -260,7 +260,7 @@ Se você clicar no ícone de cadeado, sair e tentar a mesma operação novamente
}
```
-### Usuário inativo
+### Usuário inativo { #inactive-user }
Agora tente com um usuário inativo, autentique-se com:
@@ -278,7 +278,7 @@ Você receberá um erro "Usuário inativo", como:
}
```
-## Recaptulando
+## Recapitulando { #recap }
Agora você tem as ferramentas para implementar um sistema de segurança completo baseado em `username` e `password` para sua API.
diff --git a/docs/pt/docs/tutorial/sql-databases.md b/docs/pt/docs/tutorial/sql-databases.md
index 3d76a532c..543e164e9 100644
--- a/docs/pt/docs/tutorial/sql-databases.md
+++ b/docs/pt/docs/tutorial/sql-databases.md
@@ -1,4 +1,4 @@
-# Bancos de Dados SQL (Relacionais)
+# Bancos de Dados SQL (Relacionais) { #sql-relational-databases }
**FastAPI** não exige que você use um banco de dados SQL (relacional). Mas você pode usar **qualquer banco de dados** que quiser.
@@ -8,7 +8,7 @@ Aqui veremos um exemplo usando "ORMs"), o FastAPI não obriga você a usar nada. 😎
+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. 😎
///
@@ -32,7 +32,7 @@ Existe um gerador de projetos oficial com **FastAPI** e **PostgreSQL** incluindo
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`
+## Instalar o `SQLModel` { #install-sqlmodel }
Primeiro, certifique-se de criar seu [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativá-lo e, em seguida, instalar o `sqlmodel`:
@@ -45,13 +45,13 @@ $ pip install sqlmodel
-## Criar o App com um Único Modelo
+## Criar o App com um Único Modelo { #create-the-app-with-a-single-model }
Vamos criar a primeira versão mais simples do app com um único modelo **SQLModel**.
Depois, vamos melhorá-lo aumentando a segurança e versatilidade com **múltiplos modelos** abaixo. 🤓
-### Criar Modelos
+### Criar Modelos { #create-models }
Importe o `SQLModel` e crie um modelo de banco de dados:
@@ -65,13 +65,13 @@ Existem algumas diferenças:
* `Field(primary_key=True)` informa ao SQLModel que o `id` é a **chave primária** no banco de dados SQL (você pode aprender mais sobre chaves primárias SQL na documentação do SQLModel).
- Ao ter o tipo como `int | None`, o SQLModel saberá que essa coluna deve ser um `INTEGER` no banco de dados SQL e que ela deve ser `NULLABLE`.
+ **Nota:** Usamos `int | None` para o campo de chave primária para que, no código Python, possamos *criar um objeto sem um `id`* (`id=None`), assumindo que o banco de dados irá *gerá-lo ao salvar*. O SQLModel entende que o banco de dados fornecerá o `id` e *define a coluna como um `INTEGER` não nulo* no esquema do banco de dados. Veja a documentação do SQLModel sobre chaves primárias para detalhes.
* `Field(index=True)` informa ao SQLModel que ele deve criar um **índice SQL** para essa coluna, o que permitirá buscas mais rápidas no banco de dados ao ler dados filtrados por essa coluna.
O SQLModel saberá que algo declarado como `str` será uma coluna SQL do tipo `TEXT` (ou `VARCHAR`, dependendo do banco de dados).
-### Criar um Engine
+### Criar um Engine { #create-an-engine }
Um `engine` SQLModel (por baixo dos panos, ele é na verdade um `engine` do SQLAlchemy) é o que **mantém as conexões** com o banco de dados.
Você teria **um único objeto `engine`** para todo o seu código se conectar ao mesmo banco de dados.
@@ -82,13 +82,13 @@ Usar `check_same_thread=False` permite que o FastAPI use o mesmo banco de dados
Não se preocupe, com a forma como o código está estruturado, garantiremos que usamos **uma única *sessão* SQLModel por requisição** mais tarde, isso é realmente o que o `check_same_thread` está tentando conseguir.
-### Criar as Tabelas
+### Criar as Tabelas { #create-the-tables }
Em seguida, adicionamos uma função que usa `SQLModel.metadata.create_all(engine)` para **criar as tabelas** para todos os *modelos de tabela*.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
-### Criar uma Dependência de Sessão
+### Criar uma Dependência de Sessão { #create-a-session-dependency }
Uma **`Session`** é o que armazena os **objetos na memória** e acompanha as alterações necessárias nos dados, para então **usar o `engine`** para se comunicar com o banco de dados.
@@ -98,7 +98,7 @@ Então, criamos uma dependência `Annotated` chamada `SessionDep` para simplific
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
-### Criar Tabelas de Banco de Dados na Inicialização
+### Criar Tabelas de Banco de Dados na Inicialização { #create-database-tables-on-startup }
Vamos criar as tabelas do banco de dados quando o aplicativo for iniciado.
@@ -114,7 +114,7 @@ O SQLModel terá utilitários de migração envolvendo o Alembic, mas por enquan
///
-### Criar um Hero
+### Criar um Hero { #create-a-hero }
Como cada modelo SQLModel também é um modelo Pydantic, você pode usá-lo nas mesmas **anotações de tipo** que usaria para modelos Pydantic.
@@ -124,29 +124,27 @@ Da mesma forma, você pode declará-lo como o **tipo de retorno** da função, e
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[40:45] hl[40:45] *}
-
-
Aqui, usamos a dependência `SessionDep` (uma `Session`) para adicionar o novo `Hero` à instância `Session`, fazer commit das alterações no banco de dados, atualizar os dados no `hero` e então retorná-lo.
-### Ler Heroes
+### Ler Heroes { #read-heroes }
Podemos **ler** `Hero`s do banco de dados usando um `select()`. Podemos incluir um `limit` e `offset` para paginar os resultados.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
-### Ler um Único Hero
+### Ler um Único Hero { #read-one-hero }
Podemos **ler** um único `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
-### Deletar um Hero
+### Deletar um Hero { #delete-a-hero }
Também podemos **deletar** um `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
-### Executar o App
+### Executar o App { #run-the-app }
Você pode executar o app:
@@ -166,7 +164,7 @@ Então, vá para a interface `/docs`, você verá que o **FastAPI** está usando
-## Atualizar o App com Múltiplos Modelos
+## Atualizar o App com Múltiplos Modelos { #update-the-app-with-multiple-models }
Agora vamos **refatorar** este app um pouco para aumentar a **segurança** e **versatilidade**.
@@ -178,7 +176,7 @@ Além disso, criamos um `secret_name` para o hero, mas até agora estamos retorn
Vamos corrigir essas coisas adicionando alguns **modelos extras**. Aqui é onde o SQLModel vai brilhar. ✨
-### Criar Múltiplos Modelos
+### Criar Múltiplos Modelos { #create-multiple-models }
No **SQLModel**, qualquer classe de modelo que tenha `table=True` é um **modelo de tabela**.
@@ -186,7 +184,7 @@ E qualquer classe de modelo que não tenha `table=True` é um **modelo de dados*
Com o SQLModel, podemos usar a **herança** para **evitar duplicação** de todos os campos em todos os casos.
-#### `HeroBase` - a classe base
+#### `HeroBase` - a classe base { #herobase-the-base-class }
Vamos começar com um modelo `HeroBase` que tem todos os **campos compartilhados** por todos os modelos:
@@ -195,7 +193,7 @@ Vamos começar com um modelo `HeroBase` que tem todos os **campos compartilhados
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *}
-#### `Hero` - o *modelo de tabela*
+#### `Hero` - o *modelo de tabela* { #hero-the-table-model }
Em seguida, vamos criar `Hero`, o verdadeiro *modelo de tabela*, com os **campos extras** que nem sempre estão nos outros modelos:
@@ -211,7 +209,7 @@ Como `Hero` herda de `HeroBase`, ele **também** tem os **campos** declarados em
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *}
-#### `HeroPublic` - o *modelo de dados* público
+#### `HeroPublic` - o *modelo de dados* público { #heropublic-the-public-data-model }
Em seguida, criamos um modelo `HeroPublic`, que será **retornado** para os clientes da API.
@@ -234,11 +232,10 @@ Todos os campos em `HeroPublic` são os mesmos que em `HeroBase`, com `id` decla
* `id`
* `name`
* `age`
-* `secret_name`
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *}
-#### `HeroCreate` - o *modelo de dados* para criar um hero
+#### `HeroCreate` - o *modelo de dados* para criar um hero { #herocreate-the-data-model-to-create-a-hero }
Agora criamos um modelo `HeroCreate`, este é o que **validará** os dados dos clientes.
@@ -262,7 +259,7 @@ Os campos de `HeroCreate` são:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *}
-#### `HeroUpdate` - o *modelo de dados* para atualizar um hero
+#### `HeroUpdate` - o *modelo de dados* para atualizar um hero { #heroupdate-the-data-model-to-update-a-hero }
Não tínhamos uma maneira de **atualizar um hero** na versão anterior do app, mas agora com **múltiplos modelos**, podemos fazer isso. 🎉
@@ -280,7 +277,7 @@ Os campos de `HeroUpdate` são:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *}
-### Criar com `HeroCreate` e retornar um `HeroPublic`
+### Criar com `HeroCreate` e retornar um `HeroPublic` { #create-with-herocreate-and-return-a-heropublic }
Agora que temos **múltiplos modelos**, podemos atualizar as partes do app que os utilizam.
@@ -302,19 +299,19 @@ Ao declará-lo no `response_model`, estamos dizendo ao **FastAPI** para fazer o
///
-### Ler Heroes com `HeroPublic`
+### Ler Heroes com `HeroPublic` { #read-heroes-with-heropublic }
Podemos fazer o mesmo que antes para **ler** `Hero`s, novamente, usamos `response_model=list[HeroPublic]` para garantir que os dados sejam validados e serializados corretamente.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *}
-### Ler Um Hero com `HeroPublic`
+### Ler Um Hero com `HeroPublic` { #read-one-hero-with-heropublic }
Podemos **ler** um único herói:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *}
-### Atualizar um Hero com `HeroUpdate`
+### Atualizar um Hero com `HeroUpdate` { #update-a-hero-with-heroupdate }
Podemos **atualizar um hero**. Para isso, usamos uma operação HTTP `PATCH`.
@@ -324,7 +321,7 @@ Em seguida, usamos `hero_db.sqlmodel_update(hero_data)` para atualizar o `hero_d
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *}
-### Deletar um Hero Novamente
+### Deletar um Hero Novamente { #delete-a-hero-again }
**Deletar** um hero permanece praticamente o mesmo.
@@ -332,7 +329,7 @@ Não vamos satisfazer o desejo de refatorar tudo neste aqui. 😅
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *}
-### Executar o App Novamente
+### Executar o App Novamente { #run-the-app-again }
Você pode executar o app novamente:
@@ -346,13 +343,13 @@ $ fastapi dev main.py
-If you go to the `/docs` API UI, you will see that it is now updated, and it won't expect to receive the `id` from the client when creating a hero, etc.
+Se você for para a interface `/docs` da API, verá que agora ela está atualizada e não esperará receber o `id` do cliente ao criar um hero, etc.
lt
+* XWT
+* PSGI
+
+### abbr даёт объяснение { #the-abbr-gives-an-explanation }
+
+* кластер
+* Глубокое обучение
+
+### abbr даёт полную расшифровку и объяснение { #the-abbr-gives-a-full-phrase-and-an-explanation }
+
+* MDN
+* I/O.
+
+////
+
+//// tab | Информация
+
+Атрибуты "title" элементов "abbr" переводятся по определённым правилам.
+
+Переводы могут добавлять свои собственные элементы "abbr", которые LLM не должна удалять. Например, чтобы объяснить английские слова.
+
+См. раздел `### HTML abbr elements` в общем промпте в `scripts/translate.py`.
+
+////
+
+## Заголовки { #headings }
+
+//// tab | Тест
+
+### Разработка веб‑приложения — руководство { #develop-a-webapp-a-tutorial }
+
+Привет.
+
+### Аннотации типов и -аннотации { #type-hints-and-annotations }
+
+Снова привет.
+
+### Супер- и подклассы { #super-and-subclasses }
+
+Снова привет.
+
+////
+
+//// tab | Информация
+
+Единственное жёсткое правило для заголовков — LLM должна оставить часть хеша в фигурных скобках без изменений, чтобы ссылки не ломались.
+
+См. раздел `### Headings` в общем промпте в `scripts/translate.py`.
+
+Для некоторых языковых инструкций см., например, раздел `### Headings` в `docs/de/llm-prompt.md`.
+
+////
+
+## Термины, используемые в документации { #terms-used-in-the-docs }
+
+//// tab | Тест
+
+* вы
+* ваш
+
+* например
+* и т.д.
+
+* `foo` как `int`
+* `bar` как `str`
+* `baz` как `list`
+
+* Учебник — Руководство пользователя
+* Расширенное руководство пользователя
+* Документация по SQLModel
+* Документация API
+* Автоматическая документация
+
+* Наука о данных
+* Глубокое обучение
+* Машинное обучение
+* Внедрение зависимостей
+* Аутентификация HTTP Basic
+* HTTP Digest
+* формат ISO
+* стандарт JSON Schema
+* JSON-схема
+* определение схемы
+* password flow
+* Мобильный
+
+* устаревший
+* спроектированный
+* некорректный
+* на лету
+* стандарт
+* по умолчанию
+* чувствительный к регистру
+* нечувствительный к регистру
+
+* обслуживать приложение
+* отдавать страницу
+
+* приложение
+* приложение
+
+* HTTP-запрос
+* HTTP-ответ
+* ответ с ошибкой
+
+* операция пути
+* декоратор операции пути
+* функция-обработчик пути
+
+* тело
+* тело запроса
+* тело ответа
+* JSON-тело
+* тело формы
+* тело файла
+* тело функции
+
+* параметр
+* body-параметр
+* path-параметр
+* query-параметр
+* cookie-параметр
+* параметр заголовка
+* параметр формы
+* параметр функции
+
+* событие
+* событие запуска
+* запуск сервера
+* событие остановки
+* событие lifespan
+
+* обработчик
+* обработчик события
+* обработчик исключений
+* обрабатывать
+
+* модель
+* Pydantic-модель
+* модель данных
+* модель базы данных
+* модель формы
+* объект модели
+
+* класс
+* базовый класс
+* родительский класс
+* подкласс
+* дочерний класс
+* родственный класс
+* метод класса
+
+* заголовок
+* HTTP-заголовки
+* заголовок авторизации
+* заголовок `Authorization`
+* заголовок `Forwarded`
+
+* система внедрения зависимостей
+* зависимость
+* зависимый объект
+* зависимый
+
+* ограниченный вводом/выводом
+* ограниченный процессором
+* конкурентность
+* параллелизм
+* многопроцессность
+
+* переменная окружения
+* переменная окружения
+* `PATH`
+* переменная `PATH`
+
+* аутентификация
+* провайдер аутентификации
+* авторизация
+* форма авторизации
+* провайдер авторизации
+* пользователь аутентифицируется
+* система аутентифицирует пользователя
+
+* CLI
+* интерфейс командной строки
+
+* сервер
+* клиент
+
+* облачный провайдер
+* облачный сервис
+
+* разработка
+* этапы разработки
+
+* dict
+* словарь
+* перечисление
+* enum
+* член перечисления
+
+* кодировщик
+* декодировщик
+* кодировать
+* декодировать
+
+* исключение
+* вызвать
+
+* выражение
+* оператор
+
+* фронтенд
+* бэкенд
+
+* обсуждение на GitHub
+* Issue на GitHub (тикет/обращение)
+
+* производительность
+* оптимизация производительности
+
+* тип возвращаемого значения
+* возвращаемое значение
+
+* безопасность
+* схема безопасности
+
+* задача
+* фоновая задача
+* функция задачи
+
+* шаблон
+* шаблонизатор
+
+* аннотация типов
+* аннотация типов
+
+* воркер сервера
+* воркер Uvicorn
+* воркер Gunicorn
+* воркер-процесс
+* класс воркера
+* рабочая нагрузка
+
+* деплой
+* развернуть
+
+* SDK
+* набор средств разработки ПО
+
+* `APIRouter`
+* `requirements.txt`
+* токен Bearer
+* несовместимое изменение
+* баг
+* кнопка
+* вызываемый объект
+* код
+* коммит
+* менеджер контекста
+* корутина
+* сессия базы данных
+* диск
+* домен
+* движок
+* фиктивный X
+* метод HTTP GET
+* элемент
+* библиотека
+* lifespan
+* блокировка
+* middleware (Промежуточный слой)
+* мобильное приложение
+* модуль
+* монтирование
+* сеть
+* origin (источник)
+* переопределение
+* полезная нагрузка
+* процессор
+* свойство
+* прокси
+* пулл-реквест (запрос на изменение)
+* запрос
+* ОЗУ
+* удалённая машина
+* статус-код
+* строка
+* тег
+* веб‑фреймворк
+* подстановочный знак
+* вернуть
+* валидировать
+
+////
+
+//// tab | Информация
+
+Это неполный и ненормативный список (в основном) технических терминов, встречающихся в документации. Он может помочь автору промпта понять, по каким терминам LLM нужна подсказка. Например, когда она продолжает возвращать действительно хороший перевод к неоптимальному. Или когда у неё возникают проблемы со склонением/спряжением термина на вашем языке.
+
+См., например, раздел `### List of English terms and their preferred German translations` в `docs/de/llm-prompt.md`.
+
+////
diff --git a/docs/ru/docs/about/index.md b/docs/ru/docs/about/index.md
index 1015b667a..4f48266a7 100644
--- a/docs/ru/docs/about/index.md
+++ b/docs/ru/docs/about/index.md
@@ -1,3 +1,3 @@
-# О проекте
+# О проекте { #about }
-FastAPI: внутреннее устройство, повлиявшие технологии и всё такое прочее. 🤓
+О FastAPI, его дизайне, источниках вдохновения и многом другом. 🤓
diff --git a/docs/ru/docs/advanced/additional-responses.md b/docs/ru/docs/advanced/additional-responses.md
new file mode 100644
index 000000000..fca4f072d
--- /dev/null
+++ b/docs/ru/docs/advanced/additional-responses.md
@@ -0,0 +1,247 @@
+# Дополнительные ответы в OpenAPI { #additional-responses-in-openapi }
+
+/// warning | Предупреждение
+
+Это довольно продвинутая тема.
+
+Если вы только начинаете работать с **FastAPI**, возможно, вам это пока не нужно.
+
+///
+
+Вы можете объявлять дополнительные ответы с дополнительными статус-кодами, типами содержимого, описаниями и т.д.
+
+Эти дополнительные ответы будут включены в схему OpenAPI, и поэтому появятся в документации API.
+
+Но для таких дополнительных ответов убедитесь, что вы возвращаете `Response`, например `JSONResponse`, напрямую, со своим статус-кодом и содержимым.
+
+## Дополнительный ответ с `model` { #additional-response-with-model }
+
+Вы можете передать вашим декораторам операции пути параметр `responses`.
+
+Он принимает `dict`: ключи — это статус-коды для каждого ответа (например, `200`), а значения — другие `dict` с информацией для каждого из них.
+
+Каждый из этих `dict` для ответа может иметь ключ `model`, содержащий Pydantic-модель, аналогично `response_model`.
+
+**FastAPI** возьмёт эту модель, сгенерирует для неё JSON‑схему и включит её в нужное место в OpenAPI.
+
+Например, чтобы объявить ещё один ответ со статус-кодом `404` и Pydantic-моделью `Message`, можно написать:
+
+{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *}
+
+/// note | Примечание
+
+Имейте в виду, что необходимо возвращать `JSONResponse` напрямую.
+
+///
+
+/// info | Информация
+
+Ключ `model` не является частью OpenAPI.
+
+**FastAPI** возьмёт Pydantic-модель оттуда, сгенерирует JSON‑схему и поместит её в нужное место.
+
+Нужное место:
+
+* В ключе `content`, значением которого является другой JSON‑объект (`dict`), содержащий:
+ * Ключ с типом содержимого, например `application/json`, значением которого является другой JSON‑объект, содержащий:
+ * Ключ `schema`, значением которого является JSON‑схема из модели — вот нужное место.
+ * **FastAPI** добавляет здесь ссылку на глобальные JSON‑схемы в другом месте вашего OpenAPI вместо того, чтобы включать схему напрямую. Так другие приложения и клиенты смогут использовать эти JSON‑схемы напрямую, предоставлять лучшие инструменты генерации кода и т.д.
+
+///
+
+Сгенерированные в OpenAPI ответы для этой операции пути будут такими:
+
+```JSON hl_lines="3-12"
+{
+ "responses": {
+ "404": {
+ "description": "Additional Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Message"
+ }
+ }
+ }
+ },
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Item"
+ }
+ }
+ }
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+Схемы даны как ссылки на другое место внутри схемы OpenAPI:
+
+```JSON hl_lines="4-16"
+{
+ "components": {
+ "schemas": {
+ "Message": {
+ "title": "Message",
+ "required": [
+ "message"
+ ],
+ "type": "object",
+ "properties": {
+ "message": {
+ "title": "Message",
+ "type": "string"
+ }
+ }
+ },
+ "Item": {
+ "title": "Item",
+ "required": [
+ "id",
+ "value"
+ ],
+ "type": "object",
+ "properties": {
+ "id": {
+ "title": "Id",
+ "type": "string"
+ },
+ "value": {
+ "title": "Value",
+ "type": "string"
+ }
+ }
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": [
+ "loc",
+ "msg",
+ "type"
+ ],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "msg": {
+ "title": "Message",
+ "type": "string"
+ },
+ "type": {
+ "title": "Error Type",
+ "type": "string"
+ }
+ }
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+## Дополнительные типы содержимого для основного ответа { #additional-media-types-for-the-main-response }
+
+Вы можете использовать этот же параметр `responses`, чтобы добавить разные типы содержимого для того же основного ответа.
+
+Например, вы можете добавить дополнительный тип содержимого `image/png`, объявив, что ваша операция пути может возвращать JSON‑объект (с типом содержимого `application/json`) или PNG‑изображение:
+
+{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *}
+
+/// note | Примечание
+
+Учтите, что изображение нужно возвращать напрямую, используя `FileResponse`.
+
+///
+
+/// info | Информация
+
+Если вы явно не укажете другой тип содержимого в параметре `responses`, FastAPI будет считать, что ответ имеет тот же тип содержимого, что и основной класс ответа (по умолчанию `application/json`).
+
+Но если вы указали пользовательский класс ответа с `None` в качестве его типа содержимого, FastAPI использует `application/json` для любого дополнительного ответа, у которого есть связанная модель.
+
+///
+
+## Комбинирование информации { #combining-information }
+
+Вы также можете комбинировать информацию об ответах из нескольких мест, включая параметры `response_model`, `status_code` и `responses`.
+
+Вы можете объявить `response_model`, используя статус-код по умолчанию `200` (или свой, если нужно), а затем объявить дополнительную информацию для этого же ответа в `responses`, напрямую в схеме OpenAPI.
+
+**FastAPI** сохранит дополнительную информацию из `responses` и объединит её с JSON‑схемой из вашей модели.
+
+Например, вы можете объявить ответ со статус-кодом `404`, который использует Pydantic-модель и имеет пользовательское `description`.
+
+А также ответ со статус-кодом `200`, который использует ваш `response_model`, но включает пользовательский `example`:
+
+{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *}
+
+Всё это будет объединено и включено в ваш OpenAPI и отображено в документации API:
+
+
+
+## Комбинирование предопределённых и пользовательских ответов { #combine-predefined-responses-and-custom-ones }
+
+Возможно, вы хотите иметь некоторые предопределённые ответы, применимые ко многим операциям пути, но при этом комбинировать их с пользовательскими ответами, необходимыми для каждой конкретной операции пути.
+
+В таких случаях вы можете использовать приём Python «распаковки» `dict` с помощью `**dict_to_unpack`:
+
+```Python
+old_dict = {
+ "old key": "old value",
+ "second old key": "second old value",
+}
+new_dict = {**old_dict, "new key": "new value"}
+```
+
+Здесь `new_dict` будет содержать все пары ключ-значение из `old_dict` плюс новую пару ключ-значение:
+
+```Python
+{
+ "old key": "old value",
+ "second old key": "second old value",
+ "new key": "new value",
+}
+```
+
+Вы можете использовать этот приём, чтобы переиспользовать некоторые предопределённые ответы в ваших операциях пути и комбинировать их с дополнительными пользовательскими.
+
+Например:
+
+{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *}
+
+## Дополнительная информация об ответах OpenAPI { #more-information-about-openapi-responses }
+
+Чтобы увидеть, что именно можно включать в ответы, посмотрите эти разделы спецификации OpenAPI:
+
+* Объект Responses OpenAPI, он включает `Response Object`.
+* Объект Response OpenAPI, вы можете включить всё из этого объекта напрямую в каждый ответ внутри вашего параметра `responses`. Включая `description`, `headers`, `content` (внутри него вы объявляете разные типы содержимого и JSON‑схемы) и `links`.
diff --git a/docs/ru/docs/advanced/additional-status-codes.md b/docs/ru/docs/advanced/additional-status-codes.md
index aab1f8ee3..7c73cf5d5 100644
--- a/docs/ru/docs/advanced/additional-status-codes.md
+++ b/docs/ru/docs/advanced/additional-status-codes.md
@@ -1,28 +1,28 @@
-# Дополнительные статус коды
+# Дополнительные статус-коды { #additional-status-codes }
-По умолчанию **FastAPI** возвращает ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`.
+По умолчанию **FastAPI** будет возвращать ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`.
-Он будет использовать код статуса по умолчанию или тот, который вы укажете в вашей *операции пути*.
+Он будет использовать статус-код по умолчанию или тот, который вы укажете в вашей *операции пути*.
-## Дополнительные статус коды
+## Дополнительные статус-коды { #additional-status-codes_1 }
-Если вы хотите возвращать дополнительный статус код помимо основного, вы можете сделать это, возвращая объект `Response` напрямую, как `JSONResponse`, и устанавливая нужный статус код напрямую.
+Если вы хотите возвращать дополнительные статус-коды помимо основного, вы можете сделать это, возвращая `Response` напрямую, например `JSONResponse`, и устанавливая дополнительный статус-код напрямую.
-Например, скажем, вы хотите создать *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP-код 200 "OK" при успешном выполнении.
+Например, предположим, что вы хотите иметь *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP статус-код 200 «OK» при успешном выполнении.
-Но вы также хотите, чтобы она принимала новые элементы. И если элемент ранее не существовал, он создаётся, и возвращался HTTP-код 201 "Created".
+Но вы также хотите, чтобы она принимала новые элементы. И если элементы ранее не существовали, она создаёт их и возвращает HTTP статус-код 201 «Created».
-Чтобы реализовать это, импортируйте `JSONResponse` и возвращайте ваш контент напрямую, устанавливая нужный `status_code`:
+Чтобы добиться этого, импортируйте `JSONResponse` и верните туда свой контент напрямую, установив нужный вам `status_code`:
{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *}
/// warning | Внимание
-Когда вы возвращаете объект `Response` напрямую, как в примере выше, он будет возвращён как есть.
+Когда вы возвращаете `Response` напрямую, как в примере выше, он будет возвращён как есть.
-Он не будет сериализован при помощи модели и т.д.
+Он не будет сериализован с помощью модели и т.п.
-Убедитесь, что в нём содержатся именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`).
+Убедитесь, что в нём именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`).
///
@@ -30,12 +30,12 @@
Вы также можете использовать `from starlette.responses import JSONResponse`.
-**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. То же самое касается и `status`.
+**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства как разработчика. Но большинство доступных Response-классов приходят напрямую из Starlette. То же самое со `status`.
///
-## OpenAPI и документация API
+## OpenAPI и документация API { #openapi-and-api-docs }
-Если вы возвращаете дополнительные коды статусов и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что FastAPI не может заранее знать, что вы собираетесь вернуть.
+Если вы возвращаете дополнительные статус-коды и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что у FastAPI нет способа заранее знать, что вы собираетесь вернуть.
-Но вы можете задокументировать это в вашем коде, используя: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.
+Но вы можете задокументировать это в своём коде, используя: [Дополнительные ответы](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/advanced/advanced-dependencies.md b/docs/ru/docs/advanced/advanced-dependencies.md
new file mode 100644
index 000000000..cc6691b30
--- /dev/null
+++ b/docs/ru/docs/advanced/advanced-dependencies.md
@@ -0,0 +1,163 @@
+# Продвинутые зависимости { #advanced-dependencies }
+
+## Параметризованные зависимости { #parameterized-dependencies }
+
+Все зависимости, которые мы видели, — это конкретная функция или класс.
+
+Но бывают случаи, когда нужно задавать параметры зависимости, не объявляя много разных функций или классов.
+
+Представим, что нам нужна зависимость, которая проверяет, содержит ли query-параметр `q` некоторое фиксированное содержимое.
+
+Но при этом мы хотим иметь возможность параметризовать это фиксированное содержимое.
+
+## «Вызываемый» экземпляр { #a-callable-instance }
+
+В Python есть способ сделать экземпляр класса «вызываемым» объектом.
+
+Не сам класс (он уже является вызываемым), а экземпляр этого класса.
+
+Для этого объявляем метод `__call__`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[12] *}
+
+В этом случае именно `__call__` **FastAPI** использует для проверки дополнительных параметров и подзависимостей, и именно он будет вызван, чтобы позже передать значение параметру в вашей *функции-обработчике пути*.
+
+## Параметризуем экземпляр { #parameterize-the-instance }
+
+Теперь мы можем использовать `__init__`, чтобы объявить параметры экземпляра, с помощью которых будем «параметризовать» зависимость:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[9] *}
+
+В этом случае **FastAPI** вовсе не трогает `__init__` и не зависит от него — мы используем его напрямую в нашем коде.
+
+## Создаём экземпляр { #create-an-instance }
+
+Мы можем создать экземпляр этого класса так:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[18] *}
+
+Так мы «параметризуем» нашу зависимость: теперь внутри неё хранится "bar" в атрибуте `checker.fixed_content`.
+
+## Используем экземпляр как зависимость { #use-the-instance-as-a-dependency }
+
+Затем мы можем использовать этот `checker` в `Depends(checker)` вместо `Depends(FixedContentQueryChecker)`, потому что зависимостью является экземпляр `checker`, а не сам класс.
+
+И при разрешении зависимости **FastAPI** вызовет `checker` примерно так:
+
+```Python
+checker(q="somequery")
+```
+
+…и передаст возвращённое значение как значение зависимости в нашу *функцию-обработчике пути* в параметр `fixed_content_included`:
+
+{* ../../docs_src/dependencies/tutorial011_an_py39.py hl[22] *}
+
+/// tip | Совет
+
+Все это может показаться притянутым за уши. И пока может быть не совсем понятно, чем это полезно.
+
+Эти примеры намеренно простые, но они показывают, как всё устроено.
+
+В главах про безопасность есть вспомогательные функции, реализованные тем же способом.
+
+Если вы поняли всё выше, вы уже знаете, как «под капотом» работают эти утилиты для безопасности.
+
+///
+
+## Зависимости с `yield`, `HTTPException`, `except` и фоновыми задачами { #dependencies-with-yield-httpexception-except-and-background-tasks }
+
+/// warning | Предупреждение
+
+Скорее всего, вам не понадобятся эти технические детали.
+
+Они полезны главным образом, если у вас было приложение FastAPI версии ниже 0.121.0 и вы столкнулись с проблемами зависимостей с `yield`.
+
+///
+
+Зависимости с `yield` со временем изменялись, чтобы учитывать разные случаи применения и исправлять проблемы. Ниже — краткое резюме изменений.
+
+### Зависимости с `yield` и `scope` { #dependencies-with-yield-and-scope }
+
+В версии 0.121.0 FastAPI добавил поддержку `Depends(scope="function")` для зависимостей с `yield`.
+
+При использовании `Depends(scope="function")` код после `yield` выполняется сразу после завершения *функции-обработчика пути*, до отправки ответа клиенту.
+
+А при использовании `Depends(scope="request")` (значение по умолчанию) код после `yield` выполняется после отправки ответа.
+
+Подробнее читайте в документации: [Зависимости с `yield` — раннее завершение и `scope`](../tutorial/dependencies/dependencies-with-yield.md#early-exit-and-scope).
+
+### Зависимости с `yield` и `StreamingResponse`, технические детали { #dependencies-with-yield-and-streamingresponse-technical-details }
+
+До FastAPI 0.118.0, если вы использовали зависимость с `yield`, код после `yield` выполнялся после возврата из *функции-обработчика пути*, но прямо перед отправкой ответа.
+
+Идея состояла в том, чтобы не удерживать ресурсы дольше необходимого, пока ответ «путешествует» по сети.
+
+Это изменение также означало, что если вы возвращали `StreamingResponse`, код после `yield` в зависимости уже успевал выполниться.
+
+Например, если у вас была сессия базы данных в зависимости с `yield`, `StreamingResponse` не смог бы использовать эту сессию во время стриминга данных, потому что сессия уже была закрыта в коде после `yield`.
+
+В версии 0.118.0 это поведение было возвращено к тому, что код после `yield` выполняется после отправки ответа.
+
+/// info | Информация
+
+Как вы увидите ниже, это очень похоже на поведение до версии 0.106.0, но с несколькими улучшениями и исправлениями краевых случаев.
+
+///
+
+#### Сценарии с ранним выполнением кода после `yield` { #use-cases-with-early-exit-code }
+
+Есть некоторые сценарии со специфическими условиями, которым могло бы помочь старое поведение — выполнение кода после `yield` перед отправкой ответа.
+
+Например, представьте, что вы используете сессию базы данных в зависимости с `yield` только для проверки пользователя, а в самой *функции-обработчике пути* эта сессия больше не используется, и при этом ответ отправляется долго, например, это `StreamingResponse`, который медленно отправляет данные и по какой-то причине не использует базу данных.
+
+В таком случае сессия базы данных будет удерживаться до завершения отправки ответа, хотя если вы её не используете, удерживать её не требуется.
+
+Это могло бы выглядеть так:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py *}
+
+Код после `yield`, автоматическое закрытие `Session` в:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *}
+
+…будет выполнен после того, как ответ закончит отправку медленных данных:
+
+{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *}
+
+Но поскольку `generate_stream()` не использует сессию базы данных, нет реальной необходимости держать сессию открытой во время отправки ответа.
+
+Если у вас именно такой сценарий с SQLModel (или SQLAlchemy), вы можете явно закрыть сессию, когда она больше не нужна:
+
+{* ../../docs_src/dependencies/tutorial014_an_py310.py ln[24:28] hl[28] *}
+
+Так сессия освободит подключение к базе данных, и другие запросы смогут его использовать.
+
+Если у вас есть другой сценарий, где нужно раннее завершение зависимости с `yield`, пожалуйста, создайте вопрос в GitHub Discussions с описанием конкретного кейса и почему вам было бы полезно иметь раннее закрытие для зависимостей с `yield`.
+
+Если появятся веские причины для раннего закрытия в зависимостях с `yield`, я рассмотрю добавление нового способа опционально включать раннее закрытие.
+
+### Зависимости с `yield` и `except`, технические детали { #dependencies-with-yield-and-except-technical-details }
+
+До FastAPI 0.110.0, если вы использовали зависимость с `yield`, затем перехватывали исключение с `except` в этой зависимости и не пробрасывали исключение снова, исключение автоматически пробрасывалось дальше к обработчикам исключений или к обработчику внутренней ошибки сервера.
+
+В версии 0.110.0 это было изменено, чтобы исправить неконтролируемое потребление памяти из‑за проброшенных исключений без обработчика (внутренние ошибки сервера) и привести поведение в соответствие с обычным поведением Python-кода.
+
+### Фоновые задачи и зависимости с `yield`, технические детали { #background-tasks-and-dependencies-with-yield-technical-details }
+
+До FastAPI 0.106.0 вызывать исключения после `yield` было невозможно: код после `yield` в зависимостях выполнялся уже после отправки ответа, поэтому [Обработчики исключений](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} к тому моменту уже отработали.
+
+Так было сделано в основном для того, чтобы можно было использовать те же объекты, «отданные» зависимостями через `yield`, внутри фоновых задач, потому что код после `yield` выполнялся после завершения фоновых задач.
+
+В FastAPI 0.106.0 это изменили, чтобы не удерживать ресурсы, пока ответ передаётся по сети.
+
+/// tip | Совет
+
+Кроме того, фоновая задача обычно — это самостоятельный фрагмент логики, который следует обрабатывать отдельно, со своими ресурсами (например, со своим подключением к базе данных).
+
+Так код, скорее всего, будет чище.
+
+///
+
+Если вы полагались на прежнее поведение, теперь ресурсы для фоновых задач следует создавать внутри самой фоновой задачи и использовать внутри неё только данные, которые не зависят от ресурсов зависимостей с `yield`.
+
+Например, вместо использования той же сессии базы данных, создайте новую сессию в фоновой задаче и получите объекты из базы данных с помощью этой новой сессии. И затем, вместо передачи объекта из базы данных параметром в функцию фоновой задачи, передавайте идентификатор этого объекта и заново получайте объект внутри функции фоновой задачи.
diff --git a/docs/ru/docs/advanced/async-tests.md b/docs/ru/docs/advanced/async-tests.md
index 7849ad109..e68970406 100644
--- a/docs/ru/docs/advanced/async-tests.md
+++ b/docs/ru/docs/advanced/async-tests.md
@@ -1,4 +1,4 @@
-# Асинхронное тестирование
+# Асинхронное тестирование { #async-tests }
Вы уже видели как тестировать **FastAPI** приложение, используя имеющийся класс `TestClient`. К этому моменту вы видели только как писать тесты в синхронном стиле без использования `async` функций.
@@ -6,11 +6,11 @@
Давайте рассмотрим, как мы можем это реализовать.
-## pytest.mark.anyio
+## pytest.mark.anyio { #pytest-mark-anyio }
Если мы хотим вызывать асинхронные функции в наших тестах, то наши тестовые функции должны быть асинхронными. AnyIO предоставляет для этого отличный плагин, который позволяет нам указывать, какие тестовые функции должны вызываться асинхронно.
-## HTTPX
+## HTTPX { #httpx }
Даже если **FastAPI** приложение использует обычные функции `def` вместо `async def`, это все равно `async` приложение 'под капотом'.
@@ -18,7 +18,7 @@
`TestClient` основан на HTTPX, и, к счастью, мы можем использовать его (`HTTPX`) напрямую для тестирования API.
-## Пример
+## Пример { #example }
В качестве простого примера, давайте рассмотрим файловую структуру, схожую с описанной в [Большие приложения](../tutorial/bigger-applications.md){.internal-link target=_blank} и [Тестирование](../tutorial/testing.md){.internal-link target=_blank}:
@@ -32,13 +32,13 @@
Файл `main.py`:
-{* ../../docs_src/async_tests/main.py *}
+{* ../../docs_src/async_tests/app_a_py39/main.py *}
Файл `test_main.py` содержит тесты для `main.py`, теперь он может выглядеть так:
-{* ../../docs_src/async_tests/test_main.py *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py *}
-## Запуск тестов
+## Запуск тестов { #run-it }
Вы можете запустить свои тесты как обычно:
@@ -52,11 +52,11 @@ $ pytest
-## Подробнее
+## Подробнее { #in-detail }
Маркер `@pytest.mark.anyio` говорит pytest, что тестовая функция должна быть вызвана асинхронно:
-{* ../../docs_src/async_tests/test_main.py hl[7] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[7] *}
/// tip | Подсказка
@@ -66,7 +66,7 @@ $ pytest
Затем мы можем создать `AsyncClient` со ссылкой на приложение и посылать асинхронные запросы, используя `await`.
-{* ../../docs_src/async_tests/test_main.py hl[9:12] *}
+{* ../../docs_src/async_tests/app_a_py39/test_main.py hl[9:12] *}
Это эквивалентно следующему:
@@ -88,7 +88,7 @@ response = client.get('/')
///
-## Вызов других асинхронных функций
+## Вызов других асинхронных функций { #other-asynchronous-function-calls }
Теперь тестовая функция стала асинхронной, поэтому внутри нее вы можете вызывать также и другие `async` функции, не связанные с отправлением запросов в ваше FastAPI приложение. Как если бы вы вызывали их в любом другом месте вашего кода.
diff --git a/docs/ru/docs/advanced/behind-a-proxy.md b/docs/ru/docs/advanced/behind-a-proxy.md
new file mode 100644
index 000000000..f78da01a0
--- /dev/null
+++ b/docs/ru/docs/advanced/behind-a-proxy.md
@@ -0,0 +1,466 @@
+# За прокси‑сервером { #behind-a-proxy }
+
+Во многих случаях перед приложением FastAPI используется прокси‑сервер, например Traefik или Nginx.
+
+Такие прокси могут обрабатывать HTTPS‑сертификаты и многое другое.
+
+## Пересылаемые заголовки прокси { #proxy-forwarded-headers }
+
+Прокси перед вашим приложением обычно на лету добавляет некоторые HTTP‑заголовки перед отправкой запроса на ваш сервер, чтобы сообщить ему, что запрос был переслан прокси, а также передать исходный (публичный) URL (включая домен), информацию об использовании HTTPS и т.д.
+
+Программа сервера (например, Uvicorn, запущенный через FastAPI CLI) умеет интерпретировать эти заголовки и передавать соответствующую информацию вашему приложению.
+
+Но из соображений безопасности, пока сервер не уверен, что находится за доверенным прокси, он не будет интерпретировать эти заголовки.
+
+/// note | Технические детали
+
+Заголовки прокси:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+### Включить пересылаемые заголовки прокси { #enable-proxy-forwarded-headers }
+
+Вы можете запустить FastAPI CLI с опцией командной строки `--forwarded-allow-ips` и передать IP‑адреса, которым следует доверять при чтении этих пересылаемых заголовков.
+
+Если указать `--forwarded-allow-ips="*"`, приложение будет доверять всем входящим IP.
+
+Если ваш сервер находится за доверенным прокси и только прокси обращается к нему, этого достаточно, чтобы он принимал IP этого прокси.
+
+
+
+А вот если открыть интерфейс документации по «официальному» URL через прокси на порту `9999`, по `/api/v1/docs`, всё работает корректно! 🎉
+
+Проверьте по адресу http://127.0.0.1:9999/api/v1/docs:
+
+
+
+Именно как и хотелось. ✔️
+
+Это потому, что FastAPI использует `root_path`, чтобы создать в OpenAPI сервер по умолчанию с URL из `root_path`.
+
+## Дополнительные серверы { #additional-servers }
+
+/// warning | Предупреждение
+
+Это более продвинутый сценарий. Можно пропустить.
+
+///
+
+По умолчанию FastAPI создаёт в схеме OpenAPI `server` с URL из `root_path`.
+
+Но вы также можете указать дополнительные `servers`, например, если хотите, чтобы один и тот же интерфейс документации работал и со стейджингом, и с продакшн.
+
+Если вы передадите свой список `servers` и при этом задан `root_path` (потому что ваш API работает за прокси), FastAPI вставит «server» с этим `root_path` в начало списка.
+
+Например:
+
+{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *}
+
+Будет сгенерирована схема OpenAPI примерно такая:
+
+```JSON hl_lines="5-7"
+{
+ "openapi": "3.1.0",
+ // Здесь ещё что-то
+ "servers": [
+ {
+ "url": "/api/v1"
+ },
+ {
+ "url": "https://stag.example.com",
+ "description": "Staging environment"
+ },
+ {
+ "url": "https://prod.example.com",
+ "description": "Production environment"
+ }
+ ],
+ "paths": {
+ // Здесь ещё что-то
+ }
+}
+```
+
+/// tip | Совет
+
+Обратите внимание на автоматически добавленный сервер с `url` равным `/api/v1`, взятым из `root_path`.
+
+///
+
+В интерфейсе документации по адресу http://127.0.0.1:9999/api/v1/docs это будет выглядеть так:
+
+
+
+/// tip | Совет
+
+Интерфейс документации будет взаимодействовать с сервером, который вы выберете.
+
+///
+
+/// note | Технические детали
+
+Свойство `servers` в спецификации OpenAPI является необязательным.
+
+Если вы не укажете параметр `servers`, а `root_path` равен `/`, то свойство `servers` в сгенерированной схеме OpenAPI по умолчанию будет опущено. Это эквивалентно серверу со значением `url` равным `/`.
+
+///
+
+### Отключить автоматическое добавление сервера из `root_path` { #disable-automatic-server-from-root-path }
+
+Если вы не хотите, чтобы FastAPI добавлял автоматический сервер, используя `root_path`, укажите параметр `root_path_in_servers=False`:
+
+{* ../../docs_src/behind_a_proxy/tutorial004_py39.py hl[9] *}
+
+и тогда этот сервер не будет добавлен в схему OpenAPI.
+
+## Монтирование вложенного приложения { #mounting-a-sub-application }
+
+Если вам нужно смонтировать вложенное приложение (как описано в [Вложенные приложения — монтирование](sub-applications.md){.internal-link target=_blank}), и при этом вы используете прокси с `root_path`, делайте это обычным образом — всё будет работать, как ожидается.
+
+FastAPI умно использует `root_path` внутри, так что всё просто работает. ✨
diff --git a/docs/ru/docs/advanced/custom-response.md b/docs/ru/docs/advanced/custom-response.md
new file mode 100644
index 000000000..49550b49f
--- /dev/null
+++ b/docs/ru/docs/advanced/custom-response.md
@@ -0,0 +1,312 @@
+# Кастомные ответы — HTML, поток, файл и другие { #custom-response-html-stream-file-others }
+
+По умолчанию **FastAPI** возвращает ответы с помощью `JSONResponse`.
+
+Вы можете переопределить это, вернув `Response` напрямую, как показано в разделе [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}.
+
+Но если вы возвращаете `Response` напрямую (или любой его подкласс, например `JSONResponse`), данные не будут автоматически преобразованы (даже если вы объявили `response_model`), и документация не будет автоматически сгенерирована (например, со специфичным «типом содержимого» в HTTP-заголовке `Content-Type` как частью сгенерированного OpenAPI).
+
+Но вы можете также объявить `Response`, который хотите использовать (например, любой подкласс `Response`), в декораторе операции пути, используя параметр `response_class`.
+
+Содержимое, которое вы возвращаете из своей функции-обработчика пути, будет помещено внутрь этого `Response`.
+
+И если у этого `Response` тип содержимого JSON (`application/json`), как в случае с `JSONResponse` и `UJSONResponse`, данные, которые вы возвращаете, будут автоматически преобразованы (и отфильтрованы) любым объявленным вами в декораторе операции пути Pydantic `response_model`.
+
+/// note | Примечание
+
+Если вы используете класс ответа без типа содержимого, FastAPI будет ожидать, что у вашего ответа нет содержимого, поэтому он не будет документировать формат ответа в сгенерированной документации OpenAPI.
+
+///
+
+## Используйте `ORJSONResponse` { #use-orjsonresponse }
+
+Например, если вы выжимаете максимум производительности, вы можете установить и использовать `orjson` и задать ответ как `ORJSONResponse`.
+
+Импортируйте класс (подкласс) `Response`, который вы хотите использовать, и объявите его в декораторе операции пути.
+
+Для больших ответов возвращать `Response` напрямую значительно быстрее, чем возвращать словарь.
+
+Это потому, что по умолчанию FastAPI проверяет каждый элемент внутри и убеждается, что он сериализуем в JSON, используя тот же [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}, объяснённый в руководстве. Это позволяет возвращать **произвольные объекты**, например модели из базы данных.
+
+Но если вы уверены, что содержимое, которое вы возвращаете, **сериализуемо в JSON**, вы можете передать его напрямую в класс ответа и избежать дополнительных накладных расходов, которые FastAPI понёс бы, пропуская возвращаемое содержимое через `jsonable_encoder` перед передачей в класс ответа.
+
+{* ../../docs_src/custom_response/tutorial001b_py39.py hl[2,7] *}
+
+/// info | Информация
+
+Параметр `response_class` также используется для указания «типа содержимого» ответа.
+
+В этом случае HTTP-заголовок `Content-Type` будет установлен в `application/json`.
+
+И это будет задокументировано как таковое в OpenAPI.
+
+///
+
+/// tip | Совет
+
+`ORJSONResponse` доступен только в FastAPI, а не в Starlette.
+
+///
+
+## HTML-ответ { #html-response }
+
+Чтобы вернуть ответ с HTML напрямую из **FastAPI**, используйте `HTMLResponse`.
+
+- Импортируйте `HTMLResponse`.
+- Передайте `HTMLResponse` в параметр `response_class` вашего декоратора операции пути.
+
+{* ../../docs_src/custom_response/tutorial002_py39.py hl[2,7] *}
+
+/// info | Информация
+
+Параметр `response_class` также используется для указания «типа содержимого» ответа.
+
+В этом случае HTTP-заголовок `Content-Type` будет установлен в `text/html`.
+
+И это будет задокументировано как таковое в OpenAPI.
+
+///
+
+### Вернуть `Response` { #return-a-response }
+
+Как показано в разделе [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}, вы также можете переопределить ответ прямо в своей операции пути, просто вернув его.
+
+Тот же пример сверху, возвращающий `HTMLResponse`, может выглядеть так:
+
+{* ../../docs_src/custom_response/tutorial003_py39.py hl[2,7,19] *}
+
+/// warning | Предупреждение
+
+`Response`, возвращённый напрямую вашей функцией-обработчиком пути, не будет задокументирован в OpenAPI (например, `Content-Type` нне будет задокументирова) и не будет виден в автоматически сгенерированной интерактивной документации.
+
+///
+
+/// info | Информация
+
+Разумеется, фактические заголовок `Content-Type`, статус-код и т.д. возьмутся из объекта `Response`, который вы вернули.
+
+///
+
+### Задокументировать в OpenAPI и переопределить `Response` { #document-in-openapi-and-override-response }
+
+Если вы хотите переопределить ответ внутри функции, но при этом задокументировать «тип содержимого» в OpenAPI, вы можете использовать параметр `response_class` И вернуть объект `Response`.
+
+Тогда `response_class` будет использоваться только для документирования *операции пути* в OpenAPI, а ваш `Response` будет использован как есть.
+
+#### Вернуть `HTMLResponse` напрямую { #return-an-htmlresponse-directly }
+
+Например, это может быть что-то вроде:
+
+{* ../../docs_src/custom_response/tutorial004_py39.py hl[7,21,23] *}
+
+В этом примере функция `generate_html_response()` уже генерирует и возвращает `Response` вместо возврата HTML в `str`.
+
+Возвращая результат вызова `generate_html_response()`, вы уже возвращаете `Response`, который переопределит поведение **FastAPI** по умолчанию.
+
+Но поскольку вы также передали `HTMLResponse` в `response_class`, **FastAPI** будет знать, как задокументировать это в OpenAPI и интерактивной документации как HTML с `text/html`:
+
+
+
+## Доступные ответы { #available-responses }
+
+Ниже перечислены некоторые доступные классы ответов.
+
+Учтите, что вы можете использовать `Response`, чтобы вернуть что угодно ещё, или даже создать собственный подкласс.
+
+/// note | Технические детали
+
+Вы также могли бы использовать `from starlette.responses import HTMLResponse`.
+
+**FastAPI** предоставляет те же `starlette.responses` как `fastapi.responses` для вашего удобства как разработчика. Но большинство доступных классов ответов приходят непосредственно из Starlette.
+
+///
+
+### `Response` { #response }
+
+Базовый класс `Response`, от него наследуются все остальные ответы.
+
+Его можно возвращать напрямую.
+
+Он принимает следующие параметры:
+
+- `content` — `str` или `bytes`.
+- `status_code` — целое число, HTTP статус-код.
+- `headers` — словарь строк.
+- `media_type` — строка, задающая тип содержимого. Например, `"text/html"`.
+
+FastAPI (фактически Starlette) автоматически добавит заголовок Content-Length. Также будет добавлен заголовок Content-Type, основанный на `media_type` и с добавлением charset для текстовых типов.
+
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
+
+### `HTMLResponse` { #htmlresponse }
+
+Принимает текст или байты и возвращает HTML-ответ, как описано выше.
+
+### `PlainTextResponse` { #plaintextresponse }
+
+Принимает текст или байты и возвращает ответ в виде простого текста.
+
+{* ../../docs_src/custom_response/tutorial005_py39.py hl[2,7,9] *}
+
+### `JSONResponse` { #jsonresponse }
+
+Принимает данные и возвращает ответ, кодированный как `application/json`.
+
+Это ответ по умолчанию, используемый в **FastAPI**, как было сказано выше.
+
+### `ORJSONResponse` { #orjsonresponse }
+
+Быстрая альтернативная реализация JSON-ответа с использованием `orjson`, как было сказано выше.
+
+/// info | Информация
+
+Требуется установка `orjson`, например командой `pip install orjson`.
+
+///
+
+### `UJSONResponse` { #ujsonresponse }
+
+Альтернативная реализация JSON-ответа с использованием `ujson`.
+
+/// info | Информация
+
+Требуется установка `ujson`, например командой `pip install ujson`.
+
+///
+
+/// warning | Предупреждение
+
+`ujson` менее аккуратен, чем встроенная реализация Python, в обработке некоторых крайних случаев.
+
+///
+
+{* ../../docs_src/custom_response/tutorial001_py39.py hl[2,7] *}
+
+/// tip | Совет
+
+Возможно, `ORJSONResponse` окажется более быстрым вариантом.
+
+///
+
+### `RedirectResponse` { #redirectresponse }
+
+Возвращает HTTP-редирект. По умолчанию использует статус-код 307 (Temporary Redirect — временное перенаправление).
+
+Вы можете вернуть `RedirectResponse` напрямую:
+
+{* ../../docs_src/custom_response/tutorial006_py39.py hl[2,9] *}
+
+---
+
+Или можно использовать его в параметре `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006b_py39.py hl[2,7,9] *}
+
+Если вы сделаете так, то сможете возвращать URL напрямую из своей функции-обработчика пути.
+
+В этом случае будет использован статус-код по умолчанию для `RedirectResponse`, то есть `307`.
+
+---
+
+Также вы можете использовать параметр `status_code` в сочетании с параметром `response_class`:
+
+{* ../../docs_src/custom_response/tutorial006c_py39.py hl[2,7,9] *}
+
+### `StreamingResponse` { #streamingresponse }
+
+Принимает асинхронный генератор или обычный генератор/итератор и отправляет тело ответа потоково.
+
+{* ../../docs_src/custom_response/tutorial007_py39.py hl[2,14] *}
+
+#### Использование `StreamingResponse` с файлоподобными объектами { #using-streamingresponse-with-file-like-objects }
+
+Если у вас есть файлоподобный объект (например, объект, возвращаемый `open()`), вы можете создать функцию-генератор для итерации по этому файлоподобному объекту.
+
+Таким образом, вам не нужно сначала читать всё в память, вы можете передать эту функцию-генератор в `StreamingResponse` и вернуть его.
+
+Это включает многие библиотеки для работы с облачным хранилищем, обработки видео и т.д.
+
+{* ../../docs_src/custom_response/tutorial008_py39.py hl[2,10:12,14] *}
+
+1. Это функция-генератор. Она является «функцией-генератором», потому что содержит оператор(ы) `yield` внутри.
+2. Используя блок `with`, мы гарантируем, что файлоподобный объект будет закрыт после завершения работы функции-генератора. То есть после того, как она закончит отправку ответа.
+3. Этот `yield from` говорит функции итерироваться по объекту с именем `file_like`. И затем, для каждой итерации, отдавать эту часть как исходящую из этой функции-генератора (`iterfile`).
+
+ Таким образом, это функция-генератор, которая внутренне передаёт работу по «генерации» чему-то другому.
+
+ Делая это таким образом, мы можем поместить её в блок `with` и тем самым гарантировать, что файлоподобный объект будет закрыт после завершения.
+
+/// tip | Совет
+
+Заметьте, что здесь мы используем стандартный `open()`, который не поддерживает `async` и `await`, поэтому объявляем операцию пути обычной `def`.
+
+///
+
+### `FileResponse` { #fileresponse }
+
+Асинхронно отправляет файл как ответ.
+
+Для создания экземпляра принимает иной набор аргументов, чем другие типы ответов:
+
+- `path` — путь к файлу, который будет отправлен.
+- `headers` — любые дополнительные заголовки для включения, в виде словаря.
+- `media_type` — строка, задающая тип содержимого. Если не задан, для определения типа содержимого будет использовано имя файла или путь.
+- `filename` — если задан, будет включён в заголовок ответа `Content-Disposition`.
+
+Файловые ответы будут содержать соответствующие заголовки `Content-Length`, `Last-Modified` и `ETag`.
+
+{* ../../docs_src/custom_response/tutorial009_py39.py hl[2,10] *}
+
+Вы также можете использовать параметр `response_class`:
+
+{* ../../docs_src/custom_response/tutorial009b_py39.py hl[2,8,10] *}
+
+В этом случае вы можете возвращать путь к файлу напрямую из своей функции-обработчика пути.
+
+## Пользовательский класс ответа { #custom-response-class }
+
+Вы можете создать собственный класс ответа, унаследовавшись от `Response`, и использовать его.
+
+Например, предположим, что вы хотите использовать `orjson`, но с некоторыми пользовательскими настройками, которые не используются во встроенном классе `ORJSONResponse`.
+
+Скажем, вы хотите, чтобы возвращался отформатированный JSON с отступами, то есть хотите использовать опцию orjson `orjson.OPT_INDENT_2`.
+
+Вы могли бы создать `CustomORJSONResponse`. Главное, что вам нужно сделать — реализовать метод `Response.render(content)`, который возвращает содержимое как `bytes`:
+
+{* ../../docs_src/custom_response/tutorial009c_py39.py hl[9:14,17] *}
+
+Теперь вместо того, чтобы возвращать:
+
+```json
+{"message": "Hello World"}
+```
+
+...этот ответ вернёт:
+
+```json
+{
+ "message": "Hello World"
+}
+```
+
+Разумеется, вы наверняка найдёте гораздо более полезные способы воспользоваться этим, чем просто форматирование JSON. 😉
+
+## Класс ответа по умолчанию { #default-response-class }
+
+При создании экземпляра класса **FastAPI** или `APIRouter` вы можете указать, какой класс ответа использовать по умолчанию.
+
+Параметр, который это определяет, — `default_response_class`.
+
+В примере ниже **FastAPI** будет использовать `ORJSONResponse` по умолчанию во всех операциях пути вместо `JSONResponse`.
+
+{* ../../docs_src/custom_response/tutorial010_py39.py hl[2,4] *}
+
+/// tip | Совет
+
+Вы по-прежнему можете переопределять `response_class` в операциях пути, как и раньше.
+
+///
+
+## Дополнительная документация { #additional-documentation }
+
+Вы также можете объявить тип содержимого и многие другие детали в OpenAPI с помощью `responses`: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/advanced/dataclasses.md b/docs/ru/docs/advanced/dataclasses.md
new file mode 100644
index 000000000..b3ced37c1
--- /dev/null
+++ b/docs/ru/docs/advanced/dataclasses.md
@@ -0,0 +1,95 @@
+# Использование dataclasses { #using-dataclasses }
+
+FastAPI построен поверх **Pydantic**, и я показывал вам, как использовать Pydantic-модели для объявления HTTP-запросов и HTTP-ответов.
+
+Но FastAPI также поддерживает использование `dataclasses` тем же способом:
+
+{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
+
+Это по-прежнему поддерживается благодаря **Pydantic**, так как в нём есть встроенная поддержка `dataclasses`.
+
+Так что даже если в коде выше Pydantic не используется явно, FastAPI использует Pydantic, чтобы конвертировать стандартные dataclasses в собственный вариант dataclasses от Pydantic.
+
+И, конечно, поддерживаются те же возможности:
+
+- валидация данных
+- сериализация данных
+- документирование данных и т.д.
+
+Это работает так же, как с Pydantic-моделями. И на самом деле под капотом это достигается тем же образом, с использованием Pydantic.
+
+/// info | Информация
+
+Помните, что dataclasses не умеют всего того, что умеют Pydantic-модели.
+
+Поэтому вам всё ещё может потребоваться использовать Pydantic-модели.
+
+Но если у вас уже есть набор dataclasses, это полезный приём — задействовать их для веб-API на FastAPI. 🤓
+
+///
+
+## Dataclasses в `response_model` { #dataclasses-in-response-model }
+
+Вы также можете использовать `dataclasses` в параметре `response_model`:
+
+{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *}
+
+Этот dataclass будет автоматически преобразован в Pydantic dataclass.
+
+Таким образом, его схема появится в интерфейсе документации API:
+
+
+
+## Dataclasses во вложенных структурах данных { #dataclasses-in-nested-data-structures }
+
+Вы также можете комбинировать `dataclasses` с другими аннотациями типов, чтобы создавать вложенные структуры данных.
+
+В некоторых случаях вам всё же может понадобиться использовать версию `dataclasses` из Pydantic. Например, если у вас возникают ошибки с автоматически генерируемой документацией API.
+
+В таком случае вы можете просто заменить стандартные `dataclasses` на `pydantic.dataclasses`, которая является полностью совместимой заменой (drop-in replacement):
+
+{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *}
+
+1. Мы по-прежнему импортируем `field` из стандартных `dataclasses`.
+
+2. `pydantic.dataclasses` — полностью совместимая замена (drop-in replacement) для `dataclasses`.
+
+3. Dataclass `Author` содержит список dataclass `Item`.
+
+4. Dataclass `Author` используется в параметре `response_model`.
+
+5. Вы можете использовать и другие стандартные аннотации типов вместе с dataclasses в качестве тела запроса.
+
+ В этом случае это список dataclass `Item`.
+
+6. Здесь мы возвращаем словарь, содержащий `items`, который является списком dataclass.
+
+ FastAPI по-прежнему способен сериализовать данные в JSON.
+
+7. Здесь `response_model` использует аннотацию типа — список dataclass `Author`.
+
+ Снова, вы можете комбинировать `dataclasses` со стандартными аннотациями типов.
+
+8. Обратите внимание, что эта *функция-обработчик пути* использует обычный `def` вместо `async def`.
+
+ Как и всегда в FastAPI, вы можете сочетать `def` и `async def` по необходимости.
+
+ Если хотите освежить в памяти, когда что использовать, посмотрите раздел _"Нет времени?"_ в документации про [`async` и `await`](../async.md#in-a-hurry){.internal-link target=_blank}.
+
+9. Эта *функция-обработчик пути* возвращает не dataclasses (хотя могла бы), а список словарей с внутренними данными.
+
+ FastAPI использует параметр `response_model` (в котором заданы dataclasses), чтобы преобразовать HTTP-ответ.
+
+Вы можете комбинировать `dataclasses` с другими аннотациями типов множеством способов, чтобы формировать сложные структуры данных.
+
+Смотрите подсказки в коде выше, чтобы увидеть более конкретные детали.
+
+## Узнать больше { #learn-more }
+
+Вы также можете комбинировать `dataclasses` с другими Pydantic-моделями, наследоваться от них, включать их в свои модели и т.д.
+
+Чтобы узнать больше, посмотрите документацию Pydantic о dataclasses.
+
+## Версия { #version }
+
+Доступно начиная с версии FastAPI `0.67.0`. 🔖
diff --git a/docs/ru/docs/advanced/events.md b/docs/ru/docs/advanced/events.md
new file mode 100644
index 000000000..db73d9094
--- /dev/null
+++ b/docs/ru/docs/advanced/events.md
@@ -0,0 +1,165 @@
+# События lifespan { #lifespan-events }
+
+Вы можете определить логику (код), которую нужно выполнить перед тем, как приложение начнет запускаться. Это означает, что этот код будет выполнен один раз, перед тем как приложение начнет получать HTTP-запросы.
+
+Аналогично, вы можете определить логику (код), которую нужно выполнить, когда приложение завершает работу. В этом случае код будет выполнен один раз, после обработки, возможно, многих запросов.
+
+Поскольку этот код выполняется до того, как приложение начинает принимать запросы, и сразу после того, как оно заканчивает их обрабатывать, он охватывает весь lifespan (жизненный цикл) приложения (слово «lifespan» станет важным через секунду 😉).
+
+Это может быть очень полезно для настройки ресурсов, которые нужны для всего приложения, которые разделяются между запросами и/или которые нужно затем очистить. Например, пул подключений к базе данных или загрузка общей модели Машинного обучения.
+
+## Вариант использования { #use-case }
+
+Начнем с примера варианта использования, а затем посмотрим, как это решить.
+
+Представим, что у вас есть несколько моделей Машинного обучения, которые вы хотите использовать для обработки запросов. 🤖
+
+Эти же модели разделяются между запросами, то есть это не одна модель на запрос, не одна на пользователя и т.п.
+
+Представим, что загрузка модели может занимать довольно много времени, потому что ей нужно прочитать много данных с диска. Поэтому вы не хотите делать это для каждого запроса.
+
+Вы могли бы загрузить её на верхнем уровне модуля/файла, но это означало бы, что модель загружается даже если вы просто запускаете простой автоматический тест; тогда этот тест будет медленным, так как ему придется ждать загрузки модели перед запуском независимой части кода.
+
+Именно это мы и решим: давайте загружать модель перед тем, как начнётся обработка запросов, но только непосредственно перед тем, как приложение начнет принимать запросы, а не во время загрузки кода.
+
+## Lifespan { #lifespan }
+
+Вы можете определить логику для startup и shutdown, используя параметр `lifespan` приложения `FastAPI` и «менеджер контекста» (через секунду покажу что это).
+
+Начнем с примера, а затем разберём его подробнее.
+
+Мы создаём асинхронную функцию `lifespan()` с `yield` примерно так:
+
+{* ../../docs_src/events/tutorial003_py39.py hl[16,19] *}
+
+Здесь мы симулируем дорогую операцию startup по загрузке модели, помещая (фиктивную) функцию модели в словарь с моделями Машинного обучения до `yield`. Этот код будет выполнен до того, как приложение начнет принимать запросы, во время startup.
+
+А затем сразу после `yield` мы выгружаем модель. Этот код будет выполнен после того, как приложение закончит обрабатывать запросы, непосредственно перед shutdown. Это может, например, освободить ресурсы, такие как память или GPU.
+
+/// tip | Совет
+
+`shutdown` произойдёт, когда вы останавливаете приложение.
+
+Возможно, вам нужно запустить новую версию, или вы просто устали от него. 🤷
+
+///
+
+### Функция lifespan { #lifespan-function }
+
+Первое, на что стоит обратить внимание, — мы определяем асинхронную функцию с `yield`. Это очень похоже на Зависимости с `yield`.
+
+{* ../../docs_src/events/tutorial003_py39.py hl[14:19] *}
+
+Первая часть функции, до `yield`, будет выполнена до запуска приложения.
+
+А часть после `yield` будет выполнена после завершения работы приложения.
+
+### Асинхронный менеджер контекста { #async-context-manager }
+
+Если присмотреться, функция декорирована `@asynccontextmanager`.
+
+Это превращает функцию в «асинхронный менеджер контекста».
+
+{* ../../docs_src/events/tutorial003_py39.py hl[1,13] *}
+
+Менеджер контекста в 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, чтобы он использовал его сам.
+
+Параметр `lifespan` приложения `FastAPI` принимает асинхронный менеджер контекста, поэтому мы можем передать ему наш новый асинхронный менеджер контекста `lifespan`.
+
+{* ../../docs_src/events/tutorial003_py39.py hl[22] *}
+
+## Альтернативные события (устаревшие) { #alternative-events-deprecated }
+
+/// warning | Предупреждение
+
+Рекомендуемый способ обрабатывать startup и shutdown — использовать параметр `lifespan` приложения `FastAPI`, как описано выше. Если вы укажете параметр `lifespan`, обработчики событий `startup` и `shutdown` больше вызываться не будут. Либо всё через `lifespan`, либо всё через события — не одновременно.
+
+Эту часть, скорее всего, можно пропустить.
+
+///
+
+Есть альтернативный способ определить логику, которую нужно выполнить во время startup и во время shutdown.
+
+Вы можете определить обработчики событий (функции), которые нужно выполнить до старта приложения или при его завершении.
+
+Эти функции можно объявить с `async def` или обычным `def`.
+
+### Событие `startup` { #startup-event }
+
+Чтобы добавить функцию, которую нужно запустить до старта приложения, объявите её как обработчик события `"startup"`:
+
+{* ../../docs_src/events/tutorial001_py39.py hl[8] *}
+
+В этом случае функция-обработчик события `startup` инициализирует «базу данных» items (это просто `dict`) некоторыми значениями.
+
+Вы можете добавить более одного обработчика события.
+
+И ваше приложение не начнет принимать запросы, пока все обработчики события `startup` не завершатся.
+
+### Событие `shutdown` { #shutdown-event }
+
+Чтобы добавить функцию, которую нужно запустить при завершении работы приложения, объявите её как обработчик события `"shutdown"`:
+
+{* ../../docs_src/events/tutorial002_py39.py hl[6] *}
+
+Здесь функция-обработчик события `shutdown` запишет строку текста `"Application shutdown"` в файл `log.txt`.
+
+/// info | Информация
+
+В функции `open()` параметр `mode="a"` означает «добавление» (append), то есть строка будет добавлена в конец файла, без перезаписи предыдущего содержимого.
+
+///
+
+/// tip | Совет
+
+Обратите внимание, что в этом случае мы используем стандартную Python-функцию `open()`, которая взаимодействует с файлом.
+
+То есть это I/O (ввод/вывод), требующий «ожидания» записи на диск.
+
+Но `open()` не использует `async` и `await`.
+
+Поэтому мы объявляем обработчик события обычным `def` вместо `async def`.
+
+///
+
+### `startup` и `shutdown` вместе { #startup-and-shutdown-together }
+
+С высокой вероятностью логика для вашего startup и shutdown связана: вы можете хотеть что-то запустить, а затем завершить, получить ресурс, а затем освободить его и т.д.
+
+Делать это в отдельных функциях, которые не разделяют общую логику или переменные, сложнее, так как придётся хранить значения в глобальных переменных или использовать похожие приёмы.
+
+Поэтому теперь рекомендуется использовать `lifespan`, как описано выше.
+
+## Технические детали { #technical-details }
+
+Немного технических подробностей для любопытных умников. 🤓
+
+Под капотом, в ASGI-технической спецификации, это часть Протокола Lifespan, и он определяет события `startup` и `shutdown`.
+
+/// info | Информация
+
+Вы можете прочитать больше про обработчики `lifespan` в Starlette в документации Starlette по Lifespan.
+
+Включая то, как работать с состоянием lifespan, которое можно использовать в других частях вашего кода.
+
+///
+
+## Подприложения { #sub-applications }
+
+🚨 Имейте в виду, что эти события lifespan (startup и shutdown) будут выполнены только для основного приложения, а не для [Подприложения — Mounts](sub-applications.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/advanced/generate-clients.md b/docs/ru/docs/advanced/generate-clients.md
new file mode 100644
index 000000000..00bdd31fe
--- /dev/null
+++ b/docs/ru/docs/advanced/generate-clients.md
@@ -0,0 +1,208 @@
+# Генерация SDK { #generating-sdks }
+
+Поскольку **FastAPI** основан на спецификации **OpenAPI**, его API можно описать в стандартном формате, понятном множеству инструментов.
+
+Это упрощает генерацию актуальной **документации**, клиентских библиотек (**SDKs**) на разных языках, а также **тестирования** или **воркфлоу автоматизации**, которые остаются синхронизированными с вашим кодом.
+
+В этом руководстве вы узнаете, как сгенерировать **TypeScript SDK** для вашего бэкенда на FastAPI.
+
+## Генераторы SDK с открытым исходным кодом { #open-source-sdk-generators }
+
+Гибкий вариант — OpenAPI Generator, который поддерживает **многие языки программирования** и умеет генерировать SDK из вашей спецификации OpenAPI.
+
+Для **TypeScript‑клиентов** Hey API — специализированное решение, обеспечивающее оптимальный опыт для экосистемы TypeScript.
+
+Больше генераторов SDK можно найти на OpenAPI.Tools.
+
+/// tip | Совет
+
+FastAPI автоматически генерирует спецификации **OpenAPI 3.1**, поэтому любой используемый инструмент должен поддерживать эту версию.
+
+///
+
+## Генераторы SDK от спонсоров FastAPI { #sdk-generators-from-fastapi-sponsors }
+
+В этом разделе представлены решения с **венчурной поддержкой** и **поддержкой компаний** от компаний, которые спонсируют FastAPI. Эти продукты предоставляют **дополнительные возможности** и **интеграции** сверх высококачественно генерируемых SDK.
+
+Благодаря ✨ [**спонсорству FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ эти компании помогают обеспечивать, чтобы фреймворк и его **экосистема** оставались здоровыми и **устойчивыми**.
+
+Их спонсорство также демонстрирует серьёзную приверженность **сообществу** FastAPI (вам), показывая, что им важно не только предоставлять **отличный сервис**, но и поддерживать **надёжный и процветающий фреймворк** FastAPI. 🙇
+
+Например, вы можете попробовать:
+
+* Speakeasy
+* Stainless
+* liblab
+
+Некоторые из этих решений также могут быть open source или иметь бесплатные тарифы, так что вы сможете попробовать их без финансовых затрат. Другие коммерческие генераторы SDK доступны и их можно найти онлайн. 🤓
+
+## Создать TypeScript SDK { #create-a-typescript-sdk }
+
+Начнём с простого приложения FastAPI:
+
+{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *}
+
+Обратите внимание, что *операции пути (обработчики пути)* определяют модели, которые они используют для полезной нагрузки запроса и полезной нагрузки ответа, с помощью моделей `Item` и `ResponseMessage`.
+
+### Документация API { #api-docs }
+
+Если перейти на `/docs`, вы увидите **схемы** данных, отправляемых в запросах и принимаемых в ответах:
+
+
+
+Вы видите эти схемы, потому что они были объявлены с моделями в приложении.
+
+Эта информация доступна в **схеме OpenAPI** приложения и затем отображается в документации API.
+
+Та же информация из моделей, включённая в OpenAPI, может использоваться для **генерации клиентского кода**.
+
+### Hey API { #hey-api }
+
+Как только у нас есть приложение FastAPI с моделями, мы можем использовать Hey API для генерации TypeScript‑клиента. Самый быстрый способ сделать это — через npx.
+
+```sh
+npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client
+```
+
+Это сгенерирует TypeScript SDK в `./src/client`.
+
+Вы можете узнать, как установить `@hey-api/openapi-ts` и почитать о сгенерированном результате на их сайте.
+
+### Использование SDK { #using-the-sdk }
+
+Теперь вы можете импортировать и использовать клиентский код. Это может выглядеть так, обратите внимание, что вы получаете автозавершение для методoв:
+
+
+
+Вы также получите автозавершение для отправляемой полезной нагрузки:
+
+
+
+/// tip | Совет
+
+Обратите внимание на автозавершение для `name` и `price`, это было определено в приложении FastAPI, в модели `Item`.
+
+///
+
+Вы получите ошибки прямо в редакторе для отправляемых данных:
+
+
+
+Объект ответа также будет иметь автозавершение:
+
+
+
+## Приложение FastAPI с тегами { #fastapi-app-with-tags }
+
+Во многих случаях ваше приложение FastAPI будет больше, и вы, вероятно, будете использовать теги, чтобы разделять разные группы *операций пути*.
+
+Например, у вас может быть раздел для **items** и другой раздел для **users**, и они могут быть разделены тегами:
+
+{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
+
+### Генерация TypeScript‑клиента с тегами { #generate-a-typescript-client-with-tags }
+
+Если вы генерируете клиент для приложения FastAPI с использованием тегов, обычно клиентский код также будет разделён по тегам.
+
+Таким образом вы сможете иметь всё правильно упорядоченным и сгруппированным в клиентском коде:
+
+
+
+В этом случае у вас есть:
+
+* `ItemsService`
+* `UsersService`
+
+### Имена методов клиента { #client-method-names }
+
+Сейчас сгенерированные имена методов вроде `createItemItemsPost` выглядят не очень аккуратно:
+
+```TypeScript
+ItemsService.createItemItemsPost({name: "Plumbus", price: 5})
+```
+
+...это потому, что генератор клиента использует внутренний **ID операции** OpenAPI для каждой *операции пути*.
+
+OpenAPI требует, чтобы каждый ID операции был уникален среди всех *операций пути*, поэтому FastAPI использует **имя функции**, **путь** и **HTTP‑метод/операцию** для генерации этого ID операции, так как таким образом можно гарантировать уникальность ID операций.
+
+Но далее я покажу, как это улучшить. 🤓
+
+## Пользовательские ID операций и лучшие имена методов { #custom-operation-ids-and-better-method-names }
+
+Вы можете **изменить** способ **генерации** этих ID операций, чтобы сделать их проще, а имена методов в клиентах — **более простыми**.
+
+В этом случае вам нужно будет обеспечить, чтобы каждый ID операции был **уникальным** другим способом.
+
+Например, вы можете гарантировать, что у каждой *операции пути* есть тег, и затем генерировать ID операции на основе **тега** и **имени** *операции пути* (имени функции).
+
+### Пользовательская функция генерации уникального ID { #custom-generate-unique-id-function }
+
+FastAPI использует **уникальный ID** для каждой *операции пути*, который применяется для **ID операции**, а также для имён любых необходимых пользовательских моделей запросов или ответов.
+
+Вы можете кастомизировать эту функцию. Она принимает `APIRoute` и возвращает строку.
+
+Например, здесь берётся первый тег (скорее всего у вас один тег) и имя *операции пути* (имя функции).
+
+Затем вы можете передать эту пользовательскую функцию в **FastAPI** через параметр `generate_unique_id_function`:
+
+{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
+
+### Генерация TypeScript‑клиента с пользовательскими ID операций { #generate-a-typescript-client-with-custom-operation-ids }
+
+Теперь, если снова сгенерировать клиент, вы увидите, что имена методов улучшились:
+
+
+
+Как видите, теперь имена методов содержат тег, а затем имя функции; больше они не включают информацию из URL‑пути и HTTP‑операции.
+
+### Предобработка спецификации OpenAPI для генератора клиента { #preprocess-the-openapi-specification-for-the-client-generator }
+
+Сгенерированном коде всё ещё есть **дублирующаяся информация**.
+
+Мы уже знаем, что этот метод относится к **items**, потому что это слово есть в `ItemsService` (взято из тега), но при этом имя тега всё ещё добавлено префиксом к имени метода. 😕
+
+Скорее всего мы захотим оставить это в OpenAPI в целом, так как это гарантирует, что ID операций будут **уникальны**.
+
+Но для сгенерированного клиента мы можем **модифицировать** ID операций OpenAPI непосредственно перед генерацией клиентов, чтобы сделать имена методов более приятными и **чистыми**.
+
+Мы можем скачать OpenAPI JSON в файл `openapi.json`, а затем **убрать этот префикс‑тег** таким скриптом:
+
+{* ../../docs_src/generate_clients/tutorial004_py39.py *}
+
+//// tab | Node.js
+
+```Javascript
+{!> ../../docs_src/generate_clients/tutorial004.js!}
+```
+
+////
+
+После этого ID операций будут переименованы с чего‑то вроде `items-get_items` просто в `get_items`, и генератор клиента сможет создавать более простые имена методов.
+
+### Генерация TypeScript‑клиента с предобработанным OpenAPI { #generate-a-typescript-client-with-the-preprocessed-openapi }
+
+Так как конечный результат теперь в файле `openapi.json`, нужно обновить входное расположение:
+
+```sh
+npx @hey-api/openapi-ts -i ./openapi.json -o src/client
+```
+
+После генерации нового клиента у вас будут **чистые имена методов**, со всем **автозавершением**, **ошибками прямо в редакторе** и т.д.:
+
+
+
+## Преимущества { #benefits }
+
+При использовании автоматически сгенерированных клиентов вы получите **автозавершение** для:
+
+* Методов.
+* Данных запроса — в теле запроса, query‑параметрах и т.д.
+* Данных ответа.
+
+У вас также будут **ошибки прямо в редакторе** для всего.
+
+И каждый раз, когда вы обновляете код бэкенда и **перегенерируете** фронтенд, в нём появятся новые *операции пути* как методы, старые будут удалены, а любые другие изменения отразятся в сгенерированном коде. 🤓
+
+Это также означает, что если что‑то изменилось, это будет **отражено** в клиентском коде автоматически. И если вы **соберёте** клиент, он завершится с ошибкой, если где‑то есть **несоответствие** в используемых данных.
+
+Таким образом, вы **обнаружите многие ошибки** очень рано в цикле разработки, вместо того чтобы ждать, когда ошибки проявятся у конечных пользователей в продакшн, и затем пытаться отладить, в чём проблема. ✨
diff --git a/docs/ru/docs/advanced/index.md b/docs/ru/docs/advanced/index.md
index b5cb733e7..c0a52c6c1 100644
--- a/docs/ru/docs/advanced/index.md
+++ b/docs/ru/docs/advanced/index.md
@@ -1,12 +1,12 @@
-# Расширенное руководство пользователя
+# Расширенное руководство пользователя { #advanced-user-guide }
-## Дополнительные возможности
+## Дополнительные возможности { #additional-features }
Основное [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} должно быть достаточно, чтобы познакомить вас со всеми основными функциями **FastAPI**.
В следующих разделах вы увидите другие варианты, конфигурации и дополнительные возможности.
-/// tip
+/// tip | Совет
Следующие разделы **не обязательно являются "продвинутыми"**.
@@ -14,7 +14,7 @@
///
-## Сначала прочитайте Учебник - Руководство пользователя
+## Сначала прочитайте Учебник - Руководство пользователя { #read-the-tutorial-first }
Вы все еще можете использовать большинство функций **FastAPI** со знаниями из [Учебник - Руководство пользователя](../tutorial/index.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/advanced/middleware.md b/docs/ru/docs/advanced/middleware.md
new file mode 100644
index 000000000..5ebe01078
--- /dev/null
+++ b/docs/ru/docs/advanced/middleware.md
@@ -0,0 +1,97 @@
+# Расширенное использование middleware { #advanced-middleware }
+
+В основном руководстве вы читали, как добавить [пользовательское middleware](../tutorial/middleware.md){.internal-link target=_blank} в ваше приложение.
+
+А затем — как работать с [CORS с помощью `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
+
+В этом разделе посмотрим, как использовать другие middleware.
+
+## Добавление ASGI middleware { #adding-asgi-middlewares }
+
+Так как **FastAPI** основан на Starlette и реализует спецификацию ASGI, вы можете использовать любое ASGI middleware.
+
+Middleware не обязательно должно быть сделано специально для FastAPI или Starlette — достаточно, чтобы оно соответствовало спецификации ASGI.
+
+В общем случае ASGI middleware — это классы, которые ожидают получить ASGI‑приложение первым аргументом.
+
+Поэтому в документации к сторонним ASGI middleware, скорее всего, вы увидите что‑то вроде:
+
+```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()` принимает класс middleware в качестве первого аргумента и любые дополнительные аргументы, которые будут переданы этому middleware.
+
+## Встроенные middleware { #integrated-middlewares }
+
+**FastAPI** включает несколько middleware для распространённых сценариев. Ниже рассмотрим, как их использовать.
+
+/// note | Технические детали
+
+В следующих примерах вы также можете использовать `from starlette.middleware.something import SomethingMiddleware`.
+
+**FastAPI** предоставляет несколько middleware в `fastapi.middleware` для удобства разработчика. Но большинство доступных middleware приходит напрямую из Starlette.
+
+///
+
+## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware }
+
+Гарантирует, что все входящие запросы должны использовать либо `https`, либо `wss`.
+
+Любой входящий запрос по `http` или `ws` будет перенаправлен на безопасную схему.
+
+{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *}
+
+## `TrustedHostMiddleware` { #trustedhostmiddleware }
+
+Гарантирует, что во всех входящих запросах корректно установлен `Host`‑заголовок, чтобы защититься от атак на HTTP‑заголовок Host.
+
+{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *}
+
+Поддерживаются следующие аргументы:
+
+- `allowed_hosts` — список доменных имён, которые следует разрешить как имена хостов. Подстановки вида `*.example.com` поддерживаются для сопоставления поддоменов. Чтобы разрешить любой хост, используйте либо `allowed_hosts=["*"]`, либо не добавляйте это middleware.
+- `www_redirect` — если установлено в True, запросы к не‑www версиям разрешённых хостов будут перенаправляться на их www‑аналоги. По умолчанию — `True`.
+
+Если входящий запрос не проходит валидацию, будет отправлен ответ `400`.
+
+## `GZipMiddleware` { #gzipmiddleware }
+
+Обрабатывает GZip‑ответы для любых запросов, которые включают `"gzip"` в заголовке `Accept-Encoding`.
+
+Это middleware обрабатывает как обычные, так и потоковые ответы.
+
+{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *}
+
+Поддерживаются следующие аргументы:
+
+- `minimum_size` — не сжимать GZip‑ом ответы, размер которых меньше этого минимального значения в байтах. По умолчанию — `500`.
+- `compresslevel` — уровень GZip‑сжатия. Целое число от 1 до 9. По умолчанию — `9`. Более низкое значение — быстреее сжатие, но больший размер файла; более высокое значение — более медленное сжатие, но меньший размер файла.
+
+## Другие middleware { #other-middlewares }
+
+Существует много других ASGI middleware.
+
+Например:
+
+- `ProxyHeadersMiddleware` от Uvicorn
+- MessagePack
+
+Чтобы увидеть другие доступные middleware, посмотрите документацию по middleware в Starlette и список ASGI Awesome.
diff --git a/docs/ru/docs/advanced/openapi-callbacks.md b/docs/ru/docs/advanced/openapi-callbacks.md
new file mode 100644
index 000000000..de7e28301
--- /dev/null
+++ b/docs/ru/docs/advanced/openapi-callbacks.md
@@ -0,0 +1,186 @@
+# Обратные вызовы в OpenAPI { #openapi-callbacks }
+
+Вы можете создать API с *операцией пути* (обработчиком пути), которая будет инициировать HTTP-запрос к *внешнему API*, созданному кем-то другим (скорее всего тем же разработчиком, который будет использовать ваш API).
+
+Процесс, происходящий, когда ваше приложение API обращается к *внешнему API*, называется «callback» (обратный вызов). Программное обеспечение, написанное внешним разработчиком, отправляет HTTP-запрос вашему API, а затем ваш API выполняет обратный вызов, отправляя HTTP-запрос во *внешний API* (который, вероятно, тоже создал тот же разработчик).
+
+В этом случае вам может понадобиться задокументировать, как должно выглядеть это внешнее API: какую *операцию пути* оно должно иметь, какое тело запроса ожидать, какой ответ возвращать и т.д.
+
+## Приложение с обратными вызовами { #an-app-with-callbacks }
+
+Давайте рассмотрим это на примере.
+
+Представьте, что вы разрабатываете приложение, позволяющее создавать счета.
+
+Эти счета будут иметь `id`, `title` (необязательный), `customer` и `total`.
+
+Пользователь вашего API (внешний разработчик) создаст счет в вашем API с помощью POST-запроса.
+
+Затем ваш API (предположим) сделает следующее:
+
+* Отправит счет клиенту внешнего разработчика.
+* Получит оплату.
+* Отправит уведомление обратно пользователю API (внешнему разработчику).
+ * Это будет сделано отправкой POST-запроса (из *вашего API*) в *внешний API*, предоставленный этим внешним разработчиком (это и есть «callback»).
+
+## Обычное приложение **FastAPI** { #the-normal-fastapi-app }
+
+Сначала посмотрим, как будет выглядеть обычное приложение API до добавления обратного вызова.
+
+В нём будет *операция пути*, которая получит тело запроса `Invoice`, и query-параметр `callback_url`, содержащий URL для обратного вызова.
+
+Эта часть вполне обычна, большая часть кода вам уже знакома:
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *}
+
+/// tip | Совет
+
+Query-параметр `callback_url` использует тип Pydantic Url.
+
+///
+
+Единственное новое — это `callbacks=invoices_callback_router.routes` в качестве аргумента *декоратора операции пути*. Далее разберёмся, что это такое.
+
+## Документирование обратного вызова { #documenting-the-callback }
+
+Реальный код обратного вызова будет сильно зависеть от вашего приложения API.
+
+И, вероятно, он будет заметно отличаться от одного приложения к другому.
+
+Это могут быть буквально одна-две строки кода, например:
+
+```Python
+callback_url = "https://example.com/api/v1/invoices/events/"
+httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
+```
+
+Но, возможно, самая важная часть обратного вызова — это убедиться, что пользователь вашего API (внешний разработчик) правильно реализует *внешний API* в соответствии с данными, которые *ваш API* будет отправлять в теле запроса обратного вызова и т.п.
+
+Поэтому далее мы добавим код, документирующий, как должен выглядеть этот *внешний API*, чтобы получать обратный вызов от *вашего API*.
+
+Эта документация отобразится в Swagger UI по адресу `/docs` в вашем API и позволит внешним разработчикам понять, как построить *внешний API*.
+
+В этом примере сам обратный вызов не реализуется (это может быть всего одна строка кода), реализуется только часть с документацией.
+
+/// tip | Совет
+
+Сам обратный вызов — это всего лишь HTTP-запрос.
+
+Реализуя обратный вызов, вы можете использовать, например, HTTPX или Requests.
+
+///
+
+## Напишите код документации обратного вызова { #write-the-callback-documentation-code }
+
+Этот код не будет выполняться в вашем приложении, он нужен только для *документирования* того, как должен выглядеть *внешний API*.
+
+Но вы уже знаете, как легко получить автоматическую документацию для API с **FastAPI**.
+
+Мы используем те же знания, чтобы задокументировать, как должен выглядеть *внешний API*... создав *операции пути*, которые внешний API должен реализовать (те, которые ваш API будет вызывать).
+
+/// tip | Совет
+
+Когда вы пишете код для документирования обратного вызова, полезно представить, что вы — тот самый *внешний разработчик*. И что вы сейчас реализуете *внешний API*, а не *свой API*.
+
+Временное принятие этой точки зрения (внешнего разработчика) поможет интуитивно понять, куда поместить параметры, какую Pydantic-модель использовать для тела запроса, для ответа и т.д. во *внешнем API*.
+
+///
+
+### Создайте `APIRouter` для обратного вызова { #create-a-callback-apirouter }
+
+Сначала создайте новый `APIRouter`, который будет содержать один или несколько обратных вызовов.
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *}
+
+### Создайте *операцию пути* для обратного вызова { #create-the-callback-path-operation }
+
+Чтобы создать *операцию пути* для обратного вызова, используйте тот же `APIRouter`, который вы создали выше.
+
+Она должна выглядеть как обычная *операция пути* FastAPI:
+
+* Вероятно, в ней должно быть объявление тела запроса, например `body: InvoiceEvent`.
+* А также может быть объявление модели ответа, например `response_model=InvoiceEventReceived`.
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *}
+
+Есть 2 основных отличия от обычной *операции пути*:
+
+* Ей не нужен реальный код, потому что ваше приложение никогда не будет вызывать эту функцию. Она используется только для документирования *внешнего API*. Поэтому в функции может быть просто `pass`.
+* *Путь* может содержать выражение OpenAPI 3 (подробнее ниже), где можно использовать переменные с параметрами и части исходного HTTP-запроса, отправленного *вашему API*.
+
+### Выражение пути для обратного вызова { #the-callback-path-expression }
+
+*Путь* обратного вызова может содержать выражение OpenAPI 3, которое может включать части исходного запроса, отправленного *вашему API*.
+
+В нашем случае это `str`:
+
+```Python
+"{$callback_url}/invoices/{$request.body.id}"
+```
+
+Итак, если пользователь вашего API (внешний разработчик) отправляет HTTP-запрос вашему API по адресу:
+
+```
+https://yourapi.com/invoices/?callback_url=https://www.external.org/events
+```
+
+с телом JSON:
+
+```JSON
+{
+ "id": "2expen51ve",
+ "customer": "Mr. Richie Rich",
+ "total": "9999"
+}
+```
+
+то *ваш API* обработает счёт и, в какой-то момент позже, отправит запрос обратного вызова на `callback_url` (*внешний API*):
+
+```
+https://www.external.org/events/invoices/2expen51ve
+```
+
+с телом JSON примерно такого вида:
+
+```JSON
+{
+ "description": "Payment celebration",
+ "paid": true
+}
+```
+
+и будет ожидать от *внешнего API* ответ с телом JSON вида:
+
+```JSON
+{
+ "ok": true
+}
+```
+
+/// tip | Совет
+
+Обратите внимание, что используемый URL обратного вызова содержит URL, полученный как query-параметр в `callback_url` (`https://www.external.org/events`), а также `id` счёта из тела JSON (`2expen51ve`).
+
+///
+
+### Подключите маршрутизатор обратного вызова { #add-the-callback-router }
+
+К этому моменту у вас есть необходимые *операции пути* обратного вызова (те, которые *внешний разработчик* должен реализовать во *внешнем API*) в созданном выше маршрутизаторе обратных вызовов.
+
+Теперь используйте параметр `callbacks` в *декораторе операции пути вашего API*, чтобы передать атрибут `.routes` (это, по сути, просто `list` маршрутов/*операций пути*) из этого маршрутизатора обратных вызовов:
+
+{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
+
+/// tip | Совет
+
+Обратите внимание, что вы передаёте не сам маршрутизатор (`invoices_callback_router`) в `callback=`, а его атрибут `.routes`, то есть `invoices_callback_router.routes`.
+
+///
+
+### Проверьте документацию { #check-the-docs }
+
+Теперь вы можете запустить приложение и перейти по адресу http://127.0.0.1:8000/docs.
+
+Вы увидите документацию, включающую раздел «Callbacks» для вашей *операции пути*, который показывает, как должен выглядеть *внешний API*:
+
+
diff --git a/docs/ru/docs/advanced/openapi-webhooks.md b/docs/ru/docs/advanced/openapi-webhooks.md
new file mode 100644
index 000000000..3a2b9fff7
--- /dev/null
+++ b/docs/ru/docs/advanced/openapi-webhooks.md
@@ -0,0 +1,55 @@
+# Вебхуки OpenAPI { #openapi-webhooks }
+
+Бывают случаи, когда вы хотите сообщить пользователям вашего API, что ваше приложение может вызвать их приложение (отправив HTTP-запрос) с некоторыми данными, обычно чтобы уведомить о каком-то событии.
+
+Это означает, что вместо обычного процесса, когда пользователи отправляют запросы вашему API, ваш API (или ваше приложение) может отправлять запросы в их систему (в их API, их приложение).
+
+Обычно это называется вебхуком.
+
+## Шаги вебхуков { #webhooks-steps }
+
+Обычно процесс таков: вы определяете в своем коде, какое сообщение вы будете отправлять, то есть тело запроса.
+
+Вы также определяете, в какие моменты (при каких событиях) ваше приложение будет отправлять эти запросы.
+
+А ваши пользователи каким-то образом (например, в веб‑панели) указывают URL-адрес, на который ваше приложение должно отправлять эти запросы.
+
+Вся логика регистрации URL-адресов для вебхуков и код, который реально отправляет эти запросы, целиком на вашей стороне. Вы пишете это так, как вам нужно, в своем собственном коде.
+
+## Документирование вебхуков с помощью FastAPI и OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }
+
+С FastAPI, используя OpenAPI, вы можете определить имена этих вебхуков, типы HTTP-операций, которые ваше приложение может отправлять (например, `POST`, `PUT` и т.д.), а также тела запросов, которые ваше приложение будет отправлять.
+
+Это значительно упростит вашим пользователям реализацию их API для приема ваших вебхук-запросов; возможно, они даже смогут автоматически сгенерировать часть кода своего API.
+
+/// info | Информация
+
+Вебхуки доступны в OpenAPI 3.1.0 и выше, поддерживаются в FastAPI `0.99.0` и новее.
+
+///
+
+## Приложение с вебхуками { #an-app-with-webhooks }
+
+При создании приложения на **FastAPI** есть атрибут `webhooks`, с помощью которого можно объявлять вебхуки так же, как вы объявляете операции пути (обработчики пути), например с `@app.webhooks.post()`.
+
+{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *}
+
+Определенные вами вебхуки попадут в схему **OpenAPI** и в автоматический **интерфейс документации**.
+
+/// info | Информация
+
+Объект `app.webhooks` на самом деле — это обычный `APIRouter`, тот же тип, который вы используете при структурировании приложения по нескольким файлам.
+
+///
+
+Обратите внимание: в случае с вебхуками вы на самом деле не объявляете путь (например, `/items/`), передаваемый туда текст — это лишь идентификатор вебхука (имя события). Например, в `@app.webhooks.post("new-subscription")` имя вебхука — `new-subscription`.
+
+Это связано с тем, что предполагается: фактический URL‑путь, по которому они хотят получать запрос вебхука, ваши пользователи укажут каким-то другим образом (например, в веб‑панели).
+
+### Посмотрите документацию { #check-the-docs }
+
+Теперь вы можете запустить приложение и перейти по ссылке http://127.0.0.1:8000/docs.
+
+Вы увидите, что в документации есть обычные операции пути, а также появились вебхуки:
+
+
diff --git a/docs/ru/docs/advanced/path-operation-advanced-configuration.md b/docs/ru/docs/advanced/path-operation-advanced-configuration.md
new file mode 100644
index 000000000..86d3a5b63
--- /dev/null
+++ b/docs/ru/docs/advanced/path-operation-advanced-configuration.md
@@ -0,0 +1,172 @@
+# Расширенная конфигурация операций пути { #path-operation-advanced-configuration }
+
+## OpenAPI operationId { #openapi-operationid }
+
+/// warning | Предупреждение
+
+Если вы не «эксперт» по OpenAPI, скорее всего, это вам не нужно.
+
+///
+
+Вы можете задать OpenAPI `operationId`, который будет использоваться в вашей *операции пути*, с помощью параметра `operation_id`.
+
+Нужно убедиться, что он уникален для каждой операции.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *}
+
+### Использование имени *функции-обработчика пути* как operationId { #using-the-path-operation-function-name-as-the-operationid }
+
+Если вы хотите использовать имена функций ваших API в качестве `operationId`, вы можете пройти по всем из них и переопределить `operation_id` каждой *операции пути* с помощью их `APIRoute.name`.
+
+Делать это следует после добавления всех *операций пути*.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *}
+
+/// tip | Совет
+
+Если вы вызываете `app.openapi()` вручную, обновите `operationId` до этого.
+
+///
+
+/// warning | Предупреждение
+
+Если вы делаете это, убедитесь, что каждая из ваших *функций-обработчиков пути* имеет уникальное имя.
+
+Даже если они находятся в разных модулях (файлах Python).
+
+///
+
+## Исключить из OpenAPI { #exclude-from-openapi }
+
+Чтобы исключить *операцию пути* из генерируемой схемы OpenAPI (а значит, и из автоматических систем документации), используйте параметр `include_in_schema` и установите его в `False`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *}
+
+## Расширенное описание из docstring { #advanced-description-from-docstring }
+
+Вы можете ограничить количество строк из docstring *функции-обработчика пути*, используемых для OpenAPI.
+
+Добавление `\f` (экранированного символа «form feed») заставит **FastAPI** обрезать текст, используемый для OpenAPI, в этой точке.
+
+Это не отобразится в документации, но другие инструменты (например, Sphinx) смогут использовать остальное.
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *}
+
+## Дополнительные ответы { #additional-responses }
+
+Вы, вероятно, уже видели, как объявлять `response_model` и `status_code` для *операции пути*.
+
+Это определяет метаданные об основном HTTP-ответе *операции пути*.
+
+Также можно объявлять дополнительные ответы с их моделями, статус-кодами и т.д.
+
+В документации есть целая глава об этом — [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+## Дополнительные данные OpenAPI { #openapi-extra }
+
+Когда вы объявляете *операцию пути* в своём приложении, **FastAPI** автоматически генерирует соответствующие метаданные об этой *операции пути* для включения в схему OpenAPI.
+
+/// note | Технические детали
+
+В спецификации OpenAPI это называется Объект операции.
+
+///
+
+Он содержит всю информацию об *операции пути* и используется для генерации автоматической документации.
+
+Там есть `tags`, `parameters`, `requestBody`, `responses` и т.д.
+
+Эта специфичная для *операции пути* схема OpenAPI обычно генерируется автоматически **FastAPI**, но вы также можете её расширить.
+
+/// tip | Совет
+
+Это низкоуровневая возможность расширения.
+
+Если вам нужно лишь объявить дополнительные ответы, удобнее сделать это через [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}.
+
+///
+
+Вы можете расширить схему OpenAPI для *операции пути* с помощью параметра `openapi_extra`.
+
+### Расширения OpenAPI { #openapi-extensions }
+
+`openapi_extra` может пригодиться, например, чтобы объявить [Расширения OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *}
+
+Если вы откроете автоматическую документацию API, ваше расширение появится внизу страницы конкретной *операции пути*.
+
+
+
+И если вы посмотрите на итоговый OpenAPI (по адресу `/openapi.json` вашего API), вы также увидите своё расширение в составе описания соответствующей *операции пути*:
+
+```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"
+ }
+ }
+ }
+}
+```
+
+### Пользовательская схема OpenAPI для *операции пути* { #custom-openapi-path-operation-schema }
+
+Словарь в `openapi_extra` будет глубоко объединён с автоматически сгенерированной схемой OpenAPI для *операции пути*.
+
+Таким образом, вы можете добавить дополнительные данные к автоматически сгенерированной схеме.
+
+Например, вы можете решить читать и валидировать HTTP-запрос своим кодом, не используя автоматические возможности FastAPI и Pydantic, но при этом захотите описать HTTP-запрос в схеме OpenAPI.
+
+Это можно сделать с помощью `openapi_extra`:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *}
+
+В этом примере мы не объявляли никакую Pydantic-модель. Фактически тело запроса даже не распарсено как JSON, оно читается напрямую как `bytes`, а функция `magic_data_reader()` будет отвечать за его парсинг каким-то способом.
+
+Тем не менее, мы можем объявить ожидаемую схему для тела запроса.
+
+### Пользовательский тип содержимого в OpenAPI { #custom-openapi-content-type }
+
+Используя тот же приём, вы можете воспользоваться Pydantic-моделью, чтобы определить JSON Schema, которая затем будет включена в пользовательский раздел схемы OpenAPI для *операции пути*.
+
+И вы можете сделать это, даже если тип данных в HTTP-запросе — не JSON.
+
+Например, в этом приложении мы не используем встроенную функциональность FastAPI для извлечения JSON Schema из моделей Pydantic, равно как и автоматическую валидацию JSON. Мы объявляем тип содержимого HTTP-запроса как YAML, а не JSON:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *}
+
+Тем не менее, хотя мы не используем встроенную функциональность по умолчанию, мы всё равно используем Pydantic-модель, чтобы вручную сгенерировать JSON Schema для данных, которые мы хотим получить в YAML.
+
+Затем мы работаем с HTTP-запросом напрямую и извлекаем тело как `bytes`. Это означает, что FastAPI даже не попытается распарсить полезную нагрузку HTTP-запроса как JSON.
+
+А затем в нашем коде мы напрямую парсим это содержимое YAML и снова используем ту же Pydantic-модель, чтобы валидировать YAML-содержимое:
+
+{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *}
+
+/// tip | Совет
+
+Здесь мы переиспользуем ту же Pydantic-модель.
+
+Но аналогично мы могли бы валидировать данные и каким-то другим способом.
+
+///
diff --git a/docs/ru/docs/advanced/response-change-status-code.md b/docs/ru/docs/advanced/response-change-status-code.md
index 37dade99f..85d9050ff 100644
--- a/docs/ru/docs/advanced/response-change-status-code.md
+++ b/docs/ru/docs/advanced/response-change-status-code.md
@@ -1,31 +1,31 @@
-# Response - Изменение cтатус кода
+# Response - Изменение статус-кода { #response-change-status-code }
-Вы, вероятно, уже читали о том, что можно установить [Состояние ответа по умолчанию](../tutorial/response-status-code.md){.internal-link target=_blank}.
+Вы, вероятно, уже читали о том, что можно установить [статус-код ответа по умолчанию](../tutorial/response-status-code.md){.internal-link target=_blank}.
-Но в некоторых случаях вам нужно вернуть код состояния, отличный от установленного по умолчанию.
+Но в некоторых случаях нужно вернуть другой статус-код, отличный от значения по умолчанию.
-## Пример использования
+## Пример использования { #use-case }
-Например, представьте, что вы хотите возвращать HTTP код состояния "OK" `200` по умолчанию.
+Например, представьте, что вы хотите по умолчанию возвращать HTTP статус-код «OK» `200`.
-Но если данные не существовали, вы хотите создать их и вернуть HTTP код состояния "CREATED" `201`.
+Но если данные не существовали, вы хотите создать их и вернуть HTTP статус-код «CREATED» `201`.
При этом вы всё ещё хотите иметь возможность фильтровать и преобразовывать возвращаемые данные с помощью `response_model`.
Для таких случаев вы можете использовать параметр `Response`.
-## Использование параметра `Response`
+## Использование параметра `Response` { #use-a-response-parameter }
-Вы можете объявить параметр типа `Response` в вашей *функции обработки пути* (так же как для cookies и headers).
+Вы можете объявить параметр типа `Response` в вашей *функции обработки пути* (как и для cookies и HTTP-заголовков).
И затем вы можете установить `status_code` в этом *временном* объекте ответа.
-{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *}
+{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *}
После этого вы можете вернуть любой объект, который вам нужен, как обычно (`dict`, модель базы данных и т.д.).
И если вы объявили `response_model`, он всё равно будет использоваться для фильтрации и преобразования возвращаемого объекта.
-**FastAPI** будет использовать этот *временный* ответ для извлечения кода состояния (а также cookies и headers) и поместит их в финальный ответ, который содержит возвращаемое вами значение, отфильтрованное любым `response_model`.
+**FastAPI** будет использовать этот *временный* ответ для извлечения статус-кода (а также cookies и HTTP-заголовков) и поместит их в финальный ответ, который содержит возвращаемое вами значение, отфильтрованное любым `response_model`.
-Вы также можете объявить параметр `Response` в зависимостях и установить код состояния в них. Но помните, что последнее установленное значение будет иметь приоритет.
+Вы также можете объявить параметр `Response` в зависимостях и установить в них статус-код. Но помните, что последнее установленное значение будет иметь приоритет.
diff --git a/docs/ru/docs/advanced/response-cookies.md b/docs/ru/docs/advanced/response-cookies.md
index e04ff577c..2872d6c0a 100644
--- a/docs/ru/docs/advanced/response-cookies.md
+++ b/docs/ru/docs/advanced/response-cookies.md
@@ -1,48 +1,51 @@
+# Cookies в ответе { #response-cookies }
-# Cookies в ответе
+## Использование параметра `Response` { #use-a-response-parameter }
-## Использование параметра `Response`
-
-Вы можете объявить параметр типа `Response` в вашей функции эндпоинта.
+Вы можете объявить параметр типа `Response` в вашей функции-обработчике пути.
Затем установить cookies в этом временном объекте ответа.
-{* ../../docs_src/response_cookies/tutorial002.py hl[1, 8:9] *}
+{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *}
После этого можно вернуть любой объект, как и раньше (например, `dict`, объект модели базы данных и так далее).
Если вы указали `response_model`, он всё равно будет использоваться для фильтрации и преобразования возвращаемого объекта.
-**FastAPI** извлечет cookies (а также заголовки и коды состояния) из временного ответа и включит их в окончательный ответ, содержащий ваше возвращаемое значение, отфильтрованное через `response_model`.
+**FastAPI** извлечет cookies (а также HTTP-заголовки и статус-код) из временного ответа и включит их в окончательный ответ, содержащий ваше возвращаемое значение, отфильтрованное через `response_model`.
-Вы также можете объявить параметр типа Response в зависимостях и устанавливать cookies (и заголовки) там.
+Вы также можете объявить параметр типа `Response` в зависимостях и устанавливать cookies (и HTTP-заголовки) там.
-## Возвращение `Response` напрямую
+## Возвращение `Response` напрямую { #return-a-response-directly }
-Вы также можете установить cookies, если возвращаете `Response` напрямую в вашем коде.
+Вы также можете установить Cookies, если возвращаете `Response` напрямую в вашем коде.
-Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md){.target=_blank}.
+Для этого создайте объект `Response`, как описано в разделе [Возвращение ответа напрямую](response-directly.md){.internal-link target=_blank}.
Затем установите cookies и верните этот объект:
-{* ../../docs_src/response_cookies/tutorial001.py hl[10:12] *}
+{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *}
+
+/// tip | Совет
-/// tip | Примечание
-Имейте в виду, что если вы возвращаете ответ напрямую, вместо использования параметра `Response`, **FastAPI** отправит его без дополнительной обработки.
+Имейте в виду, что если вы возвращаете ответ напрямую, вместо использования параметра `Response`, FastAPI вернёт его напрямую.
-Убедитесь, что ваши данные имеют корректный тип. Например, они должны быть совместимы с JSON, если вы используете `JSONResponse`.
+Убедитесь, что ваши данные имеют корректный тип. Например, они должны быть совместимы с JSON, если вы возвращаете `JSONResponse`.
Также убедитесь, что вы не отправляете данные, которые должны были быть отфильтрованы через `response_model`.
+
///
-### Дополнительная информация
+### Дополнительная информация { #more-info }
/// note | Технические детали
+
Вы также можете использовать `from starlette.responses import Response` или `from starlette.responses import JSONResponse`.
**FastAPI** предоставляет `fastapi.responses`, которые являются теми же объектами, что и `starlette.responses`, просто для удобства. Однако большинство доступных типов ответов поступает непосредственно из **Starlette**.
-Для установки заголовков и cookies `Response` используется часто, поэтому **FastAPI** также предоставляет его через `fastapi.responses`.
+И так как `Response` часто используется для установки HTTP-заголовков и cookies, **FastAPI** также предоставляет его как `fastapi.Response`.
+
///
-Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с документацией Starlette.
+Чтобы увидеть все доступные параметры и настройки, ознакомьтесь с документацией Starlette.
diff --git a/docs/ru/docs/advanced/response-directly.md b/docs/ru/docs/advanced/response-directly.md
index ee83d22b1..b45281071 100644
--- a/docs/ru/docs/advanced/response-directly.md
+++ b/docs/ru/docs/advanced/response-directly.md
@@ -1,4 +1,4 @@
-# Возврат ответа напрямую
+# Возврат ответа напрямую { #return-a-response-directly }
Когда вы создаёте **FastAPI** *операцию пути*, вы можете возвращать из неё любые данные: `dict`, `list`, Pydantic-модель, модель базы данных и т.д.
@@ -8,9 +8,9 @@
Но вы можете возвращать `JSONResponse` напрямую из ваших *операций пути*.
-Это может быть полезно, например, если нужно вернуть пользовательские заголовки или куки.
+Это может быть полезно, например, если нужно вернуть пользовательские HTTP-заголовки или cookie.
-## Возврат `Response`
+## Возврат `Response` { #return-a-response }
На самом деле, вы можете возвращать любой объект `Response` или его подкласс.
@@ -26,7 +26,7 @@
Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д.
-## Использование `jsonable_encoder` в `Response`
+## Использование `jsonable_encoder` в `Response` { #using-the-jsonable-encoder-in-a-response }
Поскольку **FastAPI** не изменяет объект `Response`, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке.
@@ -34,7 +34,7 @@
В таких случаях вы можете использовать `jsonable_encoder` для преобразования данных перед передачей их в ответ:
-{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *}
+{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
/// note | Технические детали
@@ -44,7 +44,7 @@
///
-## Возврат пользовательского `Response`
+## Возврат пользовательского `Response` { #returning-a-custom-response }
Пример выше показывает все необходимые части, но он пока не очень полезен, так как вы могли бы просто вернуть `item` напрямую, и **FastAPI** поместил бы его в `JSONResponse`, преобразовав в `dict` и т.д. Всё это происходит по умолчанию.
@@ -54,9 +54,9 @@
Вы можете поместить ваш XML-контент в строку, поместить её в `Response` и вернуть:
-{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
+{* ../../docs_src/response_directly/tutorial002_py39.py hl[1,18] *}
-## Примечания
+## Примечания { #notes }
Когда вы возвращаете объект `Response` напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически.
diff --git a/docs/ru/docs/advanced/response-headers.md b/docs/ru/docs/advanced/response-headers.md
new file mode 100644
index 000000000..8f24f05b0
--- /dev/null
+++ b/docs/ru/docs/advanced/response-headers.md
@@ -0,0 +1,41 @@
+# HTTP-заголовки ответа { #response-headers }
+
+## Использовать параметр `Response` { #use-a-response-parameter }
+
+Вы можете объявить параметр типа `Response` в вашей функции-обработчике пути (как можно сделать и для cookie).
+
+А затем вы можете устанавливать HTTP-заголовки в этом *временном* объекте ответа.
+
+{* ../../docs_src/response_headers/tutorial002_py39.py hl[1, 7:8] *}
+
+После этого вы можете вернуть любой нужный объект, как обычно (например, `dict`, модель из базы данных и т.д.).
+
+И, если вы объявили `response_model`, он всё равно будет использован для фильтрации и преобразования возвращённого объекта.
+
+**FastAPI** использует этот *временный* ответ, чтобы извлечь HTTP-заголовки (а также cookie и статус-код) и поместит их в финальный HTTP-ответ, который содержит возвращённое вами значение, отфильтрованное согласно `response_model`.
+
+Вы также можете объявлять параметр `Response` в зависимостях и устанавливать в них заголовки (и cookie).
+
+## Вернуть `Response` напрямую { #return-a-response-directly }
+
+Вы также можете добавить HTTP-заголовки, когда возвращаете `Response` напрямую.
+
+Создайте ответ, как описано в [Вернуть Response напрямую](response-directly.md){.internal-link target=_blank}, и передайте заголовки как дополнительный параметр:
+
+{* ../../docs_src/response_headers/tutorial001_py39.py hl[10:12] *}
+
+/// note | Технические детали
+
+Вы также можете использовать `from starlette.responses import Response` или `from starlette.responses import JSONResponse`.
+
+**FastAPI** предоставляет те же самые `starlette.responses` как `fastapi.responses` — для вашего удобства как разработчика. Но большинство доступных классов ответов поступают напрямую из Starlette.
+
+И поскольку `Response` часто используется для установки заголовков и cookie, **FastAPI** также предоставляет его как `fastapi.Response`.
+
+///
+
+## Пользовательские HTTP-заголовки { #custom-headers }
+
+Помните, что собственные проприетарные заголовки можно добавлять, используя префикс `X-`.
+
+Но если у вас есть пользовательские заголовки, которые вы хотите показывать клиенту в браузере, вам нужно добавить их в настройки CORS (подробнее см. в [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, описанный в документации Starlette по CORS.
diff --git a/docs/ru/docs/advanced/security/http-basic-auth.md b/docs/ru/docs/advanced/security/http-basic-auth.md
new file mode 100644
index 000000000..41e62d4bf
--- /dev/null
+++ b/docs/ru/docs/advanced/security/http-basic-auth.md
@@ -0,0 +1,107 @@
+# HTTP Basic Auth { #http-basic-auth }
+
+Для самых простых случаев можно использовать HTTP Basic Auth.
+
+При HTTP Basic Auth приложение ожидает HTTP-заголовок, который содержит имя пользователя и пароль.
+
+Если его нет, возвращается ошибка HTTP 401 «Unauthorized».
+
+Также возвращается заголовок `WWW-Authenticate` со значением `Basic` и необязательным параметром `realm`.
+
+Это говорит браузеру показать встроенное окно запроса имени пользователя и пароля.
+
+Затем, когда вы вводите эти данные, браузер автоматически отправляет их в заголовке.
+
+## Простой HTTP Basic Auth { #simple-http-basic-auth }
+
+* Импортируйте `HTTPBasic` и `HTTPBasicCredentials`.
+* Создайте «схему» `security` с помощью `HTTPBasic`.
+* Используйте эту `security` как зависимость в вашей *операции пути*.
+* Она возвращает объект типа `HTTPBasicCredentials`:
+ * Он содержит отправленные `username` и `password`.
+
+{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}
+
+Когда вы впервые откроете URL (или нажмёте кнопку «Execute» в документации), браузер попросит ввести имя пользователя и пароль:
+
+
+
+## Проверка имени пользователя { #check-the-username }
+
+Вот более полный пример.
+
+Используйте зависимость, чтобы проверить, корректны ли имя пользователя и пароль.
+
+Для этого используйте стандартный модуль Python `secrets` для проверки имени пользователя и пароля.
+
+`secrets.compare_digest()` должен получать `bytes` или `str`, который содержит только символы ASCII (английские символы). Это значит, что он не будет работать с символами вроде `á`, как в `Sebastián`.
+
+Чтобы это обработать, сначала преобразуем `username` и `password` в `bytes`, закодировав их в UTF-8.
+
+Затем можно использовать `secrets.compare_digest()`, чтобы убедиться, что `credentials.username` равен `"stanleyjobson"`, а `credentials.password` — `"swordfish"`.
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *}
+
+Это было бы похоже на:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+ # Вернуть ошибку
+ ...
+```
+
+Но используя `secrets.compare_digest()`, вы защитите код от атак типа «тайминговая атака» (атака по времени).
+
+### Тайминговые атаки { #timing-attacks }
+
+Что такое «тайминговая атака»?
+
+Представим, что злоумышленники пытаются угадать имя пользователя и пароль.
+
+И они отправляют запрос с именем пользователя `johndoe` и паролем `love123`.
+
+Тогда Python-код в вашем приложении будет эквивалентен чему-то вроде:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Но в момент, когда Python сравнит первую `j` в `johndoe` с первой `s` в `stanleyjobson`, он вернёт `False`, потому что уже ясно, что строки не совпадают, решив, что «нет смысла тратить ресурсы на сравнение остальных букв». И ваше приложение ответит «Неверное имя пользователя или пароль».
+
+Затем злоумышленники попробуют имя пользователя `stanleyjobsox` и пароль `love123`.
+
+И ваш код сделает что-то вроде:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Pythonу придётся сравнить весь общий префикс `stanleyjobso` в `stanleyjobsox` и `stanleyjobson`, прежде чем понять, что строки отличаются. Поэтому на ответ «Неверное имя пользователя или пароль» уйдёт на несколько микросекунд больше.
+
+#### Время ответа помогает злоумышленникам { #the-time-to-answer-helps-the-attackers }
+
+Замечая, что сервер прислал «Неверное имя пользователя или пароль» на несколько микросекунд позже, злоумышленники поймут, что какая-то часть была угадана — начальные буквы верны.
+
+Тогда они могут попробовать снова, зная, что правильнее что-то ближе к `stanleyjobsox`, чем к `johndoe`.
+
+#### «Профессиональная» атака { #a-professional-attack }
+
+Конечно, злоумышленники не будут делать всё это вручную — они напишут программу, возможно, с тысячами или миллионами попыток в секунду. И будут подбирать по одной дополнительной верной букве за раз.
+
+Так за минуты или часы они смогут угадать правильные имя пользователя и пароль — с «помощью» нашего приложения — используя лишь время, затраченное на ответ.
+
+#### Исправление с помощью `secrets.compare_digest()` { #fix-it-with-secrets-compare-digest }
+
+Но в нашем коде мы используем `secrets.compare_digest()`.
+
+Вкратце: сравнение `stanleyjobsox` с `stanleyjobson` займёт столько же времени, сколько и сравнение `johndoe` с `stanleyjobson`. То же относится и к паролю.
+
+Таким образом, используя `secrets.compare_digest()` в коде приложения, вы защитите его от всего этого класса атак на безопасность.
+
+### Возврат ошибки { #return-the-error }
+
+После того как обнаружено, что учётные данные некорректны, верните `HTTPException` со статус-кодом ответа 401 (тем же, что и при отсутствии учётных данных) и добавьте HTTP-заголовок `WWW-Authenticate`, чтобы браузер снова показал окно входа:
+
+{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *}
diff --git a/docs/ru/docs/advanced/security/index.md b/docs/ru/docs/advanced/security/index.md
new file mode 100644
index 000000000..912e4812a
--- /dev/null
+++ b/docs/ru/docs/advanced/security/index.md
@@ -0,0 +1,19 @@
+# Расширенная безопасность { #advanced-security }
+
+## Дополнительные возможности { #additional-features }
+
+Есть дополнительные возможности для работы с безопасностью помимо тех, что описаны в [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+/// tip | Совет
+
+Следующие разделы **не обязательно являются «продвинутыми»**.
+
+И возможно, что решение для вашего варианта использования находится в одном из них.
+
+///
+
+## Сначала прочитайте руководство { #read-the-tutorial-first }
+
+В следующих разделах предполагается, что вы уже прочитали основной [Учебник — Руководство пользователя: Безопасность](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+Все они основаны на тех же концепциях, но предоставляют дополнительные возможности.
diff --git a/docs/ru/docs/advanced/security/oauth2-scopes.md b/docs/ru/docs/advanced/security/oauth2-scopes.md
new file mode 100644
index 000000000..8788df199
--- /dev/null
+++ b/docs/ru/docs/advanced/security/oauth2-scopes.md
@@ -0,0 +1,274 @@
+# OAuth2 scopes { #oauth2-scopes }
+
+Вы можете использовать OAuth2 scopes (scope - область, рамки) напрямую с **FastAPI** — они интегрированы и работают бесшовно.
+
+Это позволит вам иметь более детальную систему разрешений по стандарту OAuth2, интегрированную в ваше OpenAPI‑приложение (и документацию API).
+
+OAuth2 со scopes — это механизм, который используют многие крупные провайдеры аутентификации: Facebook, Google, GitHub, Microsoft, X (Twitter) и т.д. Они применяют его, чтобы предоставлять конкретные разрешения пользователям и приложениям.
+
+Каждый раз, когда вы «входите через» Facebook, Google, GitHub, Microsoft, X (Twitter), это приложение использует OAuth2 со scopes.
+
+В этом разделе вы увидите, как управлять аутентификацией и авторизацией с теми же OAuth2 scopes в вашем приложении на **FastAPI**.
+
+/// warning | Предупреждение
+
+Это более-менее продвинутый раздел. Если вы только начинаете, можете пропустить его.
+
+Вам не обязательно нужны OAuth2 scopes — аутентификацию и авторизацию можно реализовать любым нужным вам способом.
+
+Но OAuth2 со scopes можно красиво интегрировать в ваш API (через OpenAPI) и документацию API.
+
+Так или иначе, вы все равно будете применять эти scopes или какие-то другие требования безопасности/авторизации, как вам нужно, в вашем коде.
+
+Во многих случаях OAuth2 со scopes может быть избыточным.
+
+Но если вы знаете, что это нужно, или вам просто интересно — продолжайте чтение.
+
+///
+
+## OAuth2 scopes и OpenAPI { #oauth2-scopes-and-openapi }
+
+Спецификация OAuth2 определяет «scopes» как список строк, разделённых пробелами.
+
+Содержимое каждой такой строки может иметь любой формат, но не должно содержать пробелов.
+
+Эти scopes представляют «разрешения».
+
+В OpenAPI (например, в документации API) можно определить «схемы безопасности» (security schemes).
+
+Когда одна из таких схем безопасности использует OAuth2, вы также можете объявлять и использовать scopes.
+
+Каждый «scope» — это просто строка (без пробелов).
+
+Обычно они используются для объявления конкретных разрешений безопасности, например:
+
+- `users:read` или `users:write` — распространённые примеры.
+- `instagram_basic` используется Facebook / Instagram.
+- `https://www.googleapis.com/auth/drive` используется Google.
+
+/// info | Информация
+
+В OAuth2 «scope» — это просто строка, объявляющая требуемое конкретное разрешение.
+
+Неважно, есть ли там другие символы, такие как `:`, или это URL.
+
+Эти детали зависят от реализации.
+
+Для OAuth2 это просто строки.
+
+///
+
+## Взгляд издалека { #global-view }
+
+Сначала быстро посмотрим, что изменилось по сравнению с примерами из основного раздела **Учебник - Руководство пользователя** — [OAuth2 с паролем (и хешированием), Bearer с JWT-токенами](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Теперь — с использованием OAuth2 scopes:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *}
+
+Теперь рассмотрим эти изменения шаг за шагом.
+
+## OAuth2 схема безопасности { #oauth2-security-scheme }
+
+Первое изменение — мы объявляем схему безопасности OAuth2 с двумя доступными scopes: `me` и `items`.
+
+Параметр `scopes` получает `dict`, где каждый scope — это ключ, а описание — значение:
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *}
+
+Так как теперь мы объявляем эти scopes, они появятся в документации API при входе/авторизации.
+
+И вы сможете выбрать, какие scopes вы хотите выдать доступ: `me` и `items`.
+
+Это тот же механизм, когда вы даёте разрешения при входе через Facebook, Google, GitHub и т.д.:
+
+
+
+## JWT-токены со scopes { #jwt-token-with-scopes }
+
+Теперь измените операцию пути, выдающую токен, чтобы возвращать запрошенные scopes.
+
+Мы всё ещё используем тот же `OAuth2PasswordRequestForm`. Он включает свойство `scopes` с `list` из `str` — каждый scope, полученный в запросе.
+
+И мы возвращаем scopes как часть JWT‑токена.
+
+/// danger | Опасность
+
+Для простоты здесь мы просто добавляем полученные scopes прямо в токен.
+
+Но в вашем приложении, в целях безопасности, следует убедиться, что вы добавляете только те scopes, которые пользователь действительно может иметь, или те, которые вы заранее определили.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *}
+
+## Объявление scopes в *обработчиках путей* и зависимостях { #declare-scopes-in-path-operations-and-dependencies }
+
+Теперь объявим, что операция пути для `/users/me/items/` требует scope `items`.
+
+Для этого импортируем и используем `Security` из `fastapi`.
+
+Вы можете использовать `Security` для объявления зависимостей (как `Depends`), но `Security` также принимает параметр `scopes` со списком scopes (строк).
+
+В этом случае мы передаём функцию‑зависимость `get_current_active_user` в `Security` (точно так же, как сделали бы с `Depends`).
+
+Но мы также передаём `list` scopes — в данном случае только один scope: `items` (их могло быть больше).
+
+И функция‑зависимость `get_current_active_user` тоже может объявлять подзависимости не только через `Depends`, но и через `Security`, объявляя свою подзависимость (`get_current_user`) и дополнительные требования по scopes.
+
+В данном случае требуется scope `me` (их также могло быть больше одного).
+
+/// note | Примечание
+
+Вам не обязательно добавлять разные scopes в разных местах.
+
+Мы делаем это здесь, чтобы показать, как **FastAPI** обрабатывает scopes, объявленные на разных уровнях.
+
+///
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *}
+
+/// info | Технические детали
+
+`Security` на самом деле является подклассом `Depends` и имеет всего один дополнительный параметр, который мы рассмотрим позже.
+
+Но используя `Security` вместо `Depends`, **FastAPI** будет знать, что можно объявлять security scopes, использовать их внутри и документировать API в OpenAPI.
+
+Однако когда вы импортируете `Query`, `Path`, `Depends`, `Security` и другие из `fastapi`, это на самом деле функции, возвращающие специальные классы.
+
+///
+
+## Использование `SecurityScopes` { #use-securityscopes }
+
+Теперь обновим зависимость `get_current_user`.
+
+Именно её используют зависимости выше.
+
+Здесь мы используем ту же схему OAuth2, созданную ранее, объявляя её как зависимость: `oauth2_scheme`.
+
+Поскольку у этой функции‑зависимости нет собственных требований по scopes, мы можем использовать `Depends` с `oauth2_scheme` — нам не нужно использовать `Security`, если не требуется указывать security scopes.
+
+Мы также объявляем специальный параметр типа `SecurityScopes`, импортированный из `fastapi.security`.
+
+Класс `SecurityScopes` похож на `Request` (через `Request` мы получали сам объект запроса).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
+
+## Использование `scopes` { #use-the-scopes }
+
+Параметр `security_scopes` будет типа `SecurityScopes`.
+
+У него есть свойство `scopes` со списком, содержащим все scopes, требуемые им самим и всеми зависимостями, использующими его как подзависимость. То есть всеми «зависящими»… это может звучать запутанно, ниже есть дополнительное объяснение.
+
+Объект `security_scopes` (класс `SecurityScopes`) также предоставляет атрибут `scope_str` — это одна строка с этими scopes, разделёнными пробелами (мы будем её использовать).
+
+Мы создаём `HTTPException`, который можем переиспользовать (`raise`) в нескольких местах.
+
+В этом исключении мы включаем требуемые scopes (если есть) в виде строки, разделённой пробелами (используя `scope_str`). Эту строку со scopes мы помещаем в HTTP‑заголовок `WWW-Authenticate` (это часть спецификации).
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
+
+## Проверка `username` и формата данных { #verify-the-username-and-data-shape }
+
+Мы проверяем, что получили `username`, и извлекаем scopes.
+
+Затем валидируем эти данные с помощью Pydantic‑модели (перехватывая исключение `ValidationError`), и если возникает ошибка при чтении JWT‑токена или при валидации данных с Pydantic, мы вызываем `HTTPException`, созданное ранее.
+
+Для этого мы обновляем Pydantic‑модель `TokenData`, добавляя новое свойство `scopes`.
+
+Валидируя данные с помощью Pydantic, мы можем удостовериться, что у нас, например, именно `list` из `str` со scopes и `str` с `username`.
+
+А не, скажем, `dict` или что‑то ещё — ведь это могло бы где‑то позже сломать приложение и создать риск для безопасности.
+
+Мы также проверяем, что существует пользователь с таким именем, и если нет — вызываем то же исключение, созданное ранее.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *}
+
+## Проверка `scopes` { #verify-the-scopes }
+
+Теперь проверяем, что все требуемые scopes — этой зависимостью и всеми зависящими (включая операции пути) — присутствуют среди scopes, предоставленных в полученном токене, иначе вызываем `HTTPException`.
+
+Для этого используем `security_scopes.scopes`, содержащий `list` со всеми этими scopes как `str`.
+
+{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *}
+
+## Дерево зависимостей и scopes { #dependency-tree-and-scopes }
+
+Ещё раз рассмотрим дерево зависимостей и scopes.
+
+Так как у зависимости `get_current_active_user` есть подзависимость `get_current_user`, scope `"me"`, объявленный в `get_current_active_user`, будет включён в список требуемых scopes в `security_scopes.scopes`, передаваемый в `get_current_user`.
+
+Сама операция пути тоже объявляет scope — `"items"`, поэтому он также будет в списке `security_scopes.scopes`, передаваемом в `get_current_user`.
+
+Иерархия зависимостей и scopes выглядит так:
+
+- Операция пути `read_own_items`:
+ - Запрашивает scopes `["items"]` с зависимостью:
+ - `get_current_active_user`:
+ - Функция‑зависимость `get_current_active_user`:
+ - Запрашивает scopes `["me"]` с зависимостью:
+ - `get_current_user`:
+ - Функция‑зависимость `get_current_user`:
+ - Собственных scopes не запрашивает.
+ - Имеет зависимость, использующую `oauth2_scheme`.
+ - Имеет параметр `security_scopes` типа `SecurityScopes`:
+ - Этот параметр `security_scopes` имеет свойство `scopes` с `list`, содержащим все объявленные выше scopes, то есть:
+ - `security_scopes.scopes` будет содержать `["me", "items"]` для операции пути `read_own_items`.
+ - `security_scopes.scopes` будет содержать `["me"]` для операции пути `read_users_me`, потому что он объявлен в зависимости `get_current_active_user`.
+ - `security_scopes.scopes` будет содержать `[]` (ничего) для операции пути `read_system_status`, потому что там не объявлялся `Security` со `scopes`, и его зависимость `get_current_user` тоже не объявляет `scopes`.
+
+/// tip | Совет
+
+Важный и «магический» момент здесь в том, что `get_current_user` будет иметь разный список `scopes` для проверки для каждой операции пути.
+
+Всё это зависит от `scopes`, объявленных в каждой операции пути и в каждой зависимости в дереве зависимостей конкретной операции пути.
+
+///
+
+## Больше деталей о `SecurityScopes` { #more-details-about-securityscopes }
+
+Вы можете использовать `SecurityScopes` в любой точке и в нескольких местах — необязательно в «корневой» зависимости.
+
+Он всегда будет содержать security scopes, объявленные в текущих зависимостях `Security`, и всеми зависящими — для этой конкретной операции пути и этого конкретного дерева зависимостей.
+
+Поскольку `SecurityScopes` будет содержать все scopes, объявленные зависящими, вы можете использовать его, чтобы централизованно проверять наличие требуемых scopes в токене в одной функции‑зависимости, а затем объявлять разные требования по scopes в разных операциях пути.
+
+Они будут проверяться независимо для каждой операции пути.
+
+## Проверим это { #check-it }
+
+Откройте документацию API — вы сможете аутентифицироваться и указать, какие scopes вы хотите авторизовать.
+
+
+
+Если вы не выберете ни один scope, вы будете «аутентифицированы», но при попытке доступа к `/users/me/` или `/users/me/items/` получите ошибку о недостаточных разрешениях. При этом доступ к `/status/` будет возможен.
+
+Если вы выберете scope `me`, но не `items`, вы сможете получить доступ к `/users/me/`, но не к `/users/me/items/`.
+
+Так и будет происходить со сторонним приложением, которое попытается обратиться к одной из этих операций пути с токеном, предоставленным пользователем, — в зависимости от того, сколько разрешений пользователь дал приложению.
+
+## О сторонних интеграциях { #about-third-party-integrations }
+
+В этом примере мы используем OAuth2 «password flow» (аутентификация по паролю).
+
+Это уместно, когда мы входим в наше собственное приложение, вероятно, с нашим собственным фронтендом.
+
+Мы можем ему доверять при получении `username` и `password`, потому что он под нашим контролем.
+
+Но если вы создаёте OAuth2‑приложение, к которому будут подключаться другие (т.е. вы строите провайдера аутентификации наподобие Facebook, Google, GitHub и т.п.), вам следует использовать один из других «flows».
+
+Самый распространённый — «implicit flow».
+
+Самый безопасный — «code flow», но он сложнее в реализации, так как требует больше шагов. Из‑за сложности многие провайдеры в итоге рекомендуют «implicit flow».
+
+/// note | Примечание
+
+Часто каждый провайдер аутентификации называет свои «flows» по‑разному — как часть бренда.
+
+Но в итоге они реализуют один и тот же стандарт OAuth2.
+
+///
+
+FastAPI включает утилиты для всех этих OAuth2‑flows в `fastapi.security.oauth2`.
+
+## `Security` в параметре `dependencies` декоратора { #security-in-decorator-dependencies }
+
+Точно так же, как вы можете определить `list` из `Depends` в параметре `dependencies` декоратора (см. [Зависимости в декораторах операции пути](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), вы можете использовать там и `Security` со `scopes`.
diff --git a/docs/ru/docs/advanced/settings.md b/docs/ru/docs/advanced/settings.md
new file mode 100644
index 000000000..8408faebf
--- /dev/null
+++ b/docs/ru/docs/advanced/settings.md
@@ -0,0 +1,302 @@
+# Настройки и переменные окружения { #settings-and-environment-variables }
+
+Во многих случаях вашему приложению могут понадобиться внешние настройки или конфигурации, например секретные ключи, учетные данные для базы данных, учетные данные для email‑сервисов и т.д.
+
+Большинство таких настроек являются изменяемыми (могут меняться), например URL базы данных. И многие из них могут быть «чувствительными», например секреты.
+
+По этой причине обычно их передают через переменные окружения, которые считываются приложением.
+
+/// tip | Совет
+
+Чтобы понять, что такое переменные окружения, вы можете прочитать [Переменные окружения](../environment-variables.md){.internal-link target=_blank}.
+
+///
+
+## Типы и валидация { #types-and-validation }
+
+Переменные окружения могут содержать только текстовые строки, так как они внешние по отношению к Python и должны быть совместимы с другими программами и остальной системой (и даже с разными операционными системами, такими как Linux, Windows, macOS).
+
+Это означает, что любое значение, прочитанное в Python из переменной окружения, будет `str`, а любые преобразования к другим типам или любая валидация должны выполняться в коде.
+
+## Pydantic `Settings` { #pydantic-settings }
+
+К счастью, Pydantic предоставляет отличную утилиту для работы с этими настройками, поступающими из переменных окружения, — Pydantic: управление настройками.
+
+### Установка `pydantic-settings` { #install-pydantic-settings }
+
+Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет `pydantic-settings`:
+
+
+
+Затем откройте документацию для подприложения по адресу http://127.0.0.1:8000/subapi/docs.
+
+Вы увидите автоматическую документацию API для подприложения, включающую только его собственные _операции пути_, все под корректным префиксом подпути `/subapi`:
+
+
+
+Если вы попробуете взаимодействовать с любым из двух интерфейсов, всё будет работать корректно, потому что браузер сможет обращаться к каждому конкретному приложению и подприложению.
+
+### Технические подробности: `root_path` { #technical-details-root-path }
+
+Когда вы монтируете подприложение, как описано выше, FastAPI позаботится о передаче пути монтирования для подприложения, используя механизм из спецификации ASGI под названием `root_path`.
+
+Таким образом подприложение будет знать, что для интерфейса документации нужно использовать этот префикс пути.
+
+У подприложения также могут быть свои собственные смонтированные подприложения, и всё будет работать корректно, потому что FastAPI автоматически обрабатывает все эти `root_path`.
+
+Вы узнаете больше о `root_path` и о том, как использовать его явно, в разделе [За прокси](behind-a-proxy.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/advanced/templates.md b/docs/ru/docs/advanced/templates.md
new file mode 100644
index 000000000..460e2e466
--- /dev/null
+++ b/docs/ru/docs/advanced/templates.md
@@ -0,0 +1,126 @@
+# Шаблоны { #templates }
+
+Вы можете использовать любой шаблонизатор вместе с **FastAPI**.
+
+Часто выбирают Jinja2 — тот же, что используется во Flask и других инструментах.
+
+Есть утилиты для простой настройки, которые вы можете использовать прямо в своем приложении **FastAPI** (предоставляются Starlette).
+
+## Установка зависимостей { #install-dependencies }
+
+Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и установили `jinja2`:
+
+
-## Обработка отключений и работа с несколькими клиентами
+## Обработка отключений и работа с несколькими клиентами { #handling-disconnections-and-multiple-clients }
Если веб-сокет соединение закрыто, то `await websocket.receive_text()` вызовет исключение `WebSocketDisconnect`, которое можно поймать и обработать как в этом примере:
@@ -168,7 +168,7 @@ $ fastapi dev main.py
Client #1596980209979 left the chat
```
-/// tip | Примечание
+/// tip | Подсказка
Приложение выше - это всего лишь простой минимальный пример, демонстрирующий обработку и передачу сообщений нескольким веб-сокет соединениям.
@@ -178,9 +178,9 @@ Client #1596980209979 left the chat
///
-## Дополнительная информация
+## Дополнительная информация { #more-info }
Для более глубокого изучения темы воспользуйтесь документацией Starlette:
-* The `WebSocket` class.
-* Class-based WebSocket handling.
+* The `WebSocket` class.
+* Class-based WebSocket handling.
diff --git a/docs/ru/docs/advanced/wsgi.md b/docs/ru/docs/advanced/wsgi.md
new file mode 100644
index 000000000..64d7c7a28
--- /dev/null
+++ b/docs/ru/docs/advanced/wsgi.md
@@ -0,0 +1,35 @@
+# Подключение WSGI — Flask, Django и другие { #including-wsgi-flask-django-others }
+
+Вы можете монтировать WSGI‑приложения, как вы видели в [Подприложения — Mounts](sub-applications.md){.internal-link target=_blank}, [За прокси‑сервером](behind-a-proxy.md){.internal-link target=_blank}.
+
+Для этого вы можете использовать `WSGIMiddleware` и обернуть им ваше WSGI‑приложение, например Flask, Django и т.д.
+
+## Использование `WSGIMiddleware` { #using-wsgimiddleware }
+
+Нужно импортировать `WSGIMiddleware`.
+
+Затем оберните WSGI‑приложение (например, Flask) в middleware (Промежуточный слой).
+
+После этого смонтируйте его на путь.
+
+{* ../../docs_src/wsgi/tutorial001_py39.py hl[2:3,3] *}
+
+## Проверьте { #check-it }
+
+Теперь каждый HTTP‑запрос по пути `/v1/` будет обрабатываться приложением Flask.
+
+А всё остальное будет обрабатываться **FastAPI**.
+
+Если вы запустите это и перейдёте по http://localhost:8000/v1/, вы увидите HTTP‑ответ от Flask:
+
+```txt
+Hello, World from Flask!
+```
+
+А если вы перейдёте по http://localhost:8000/v2, вы увидите HTTP‑ответ от FastAPI:
+
+```JSON
+{
+ "message": "Hello World"
+}
+```
diff --git a/docs/ru/docs/alternatives.md b/docs/ru/docs/alternatives.md
index 3c5147e79..17b54aad2 100644
--- a/docs/ru/docs/alternatives.md
+++ b/docs/ru/docs/alternatives.md
@@ -1,104 +1,94 @@
-# Альтернативы, источники вдохновения и сравнения
+# Альтернативы, источники вдохновения и сравнения { #alternatives-inspiration-and-comparisons }
-Что вдохновило на создание **FastAPI**, сравнение его с альтернативами и чему он научился у них.
+Что вдохновило **FastAPI**, сравнение с альтернативами и чему он у них научился.
-## Введение
+## Введение { #intro }
-**FastAPI** не существовал бы, если б не было более ранних работ других людей.
+**FastAPI** не существовал бы без предыдущих работ других людей.
-Они создали большое количество инструментов, которые вдохновили меня на создание **FastAPI**.
+Было создано множество инструментов, которые вдохновили на его появление.
-Я всячески избегал создания нового фреймворка в течение нескольких лет.
-Сначала я пытался собрать все нужные функции, которые ныне есть в **FastAPI**, используя множество различных фреймворков, плагинов и инструментов.
+Я несколько лет избегал создания нового фреймворка. Сначала пытался закрыть все возможности, которые сейчас предоставляет **FastAPI**, с помощью множества разных фреймворков, плагинов и инструментов.
-Но в какой-то момент не осталось другого выбора, кроме как создать что-то, что предоставляло бы все эти функции сразу.
-Взять самые лучшие идеи из предыдущих инструментов и, используя новые возможности Python (которых не было до версии 3.6, то есть подсказки типов), объединить их.
+Но в какой-то момент не осталось другого варианта, кроме как создать что-то, что включает все эти возможности, взяв лучшие идеи из прежних инструментов и совместив их максимально удачным образом, используя возможности языка, которых прежде не было (аннотации типов в Python 3.6+).
-## Предшествующие инструменты
+## Предшествующие инструменты { #previous-tools }
-### Django
+### Django { #django }
-Это самый популярный Python-фреймворк, и он пользуется доверием.
-Он используется для создания проектов типа Instagram.
+Это самый популярный Python-фреймворк, ему широко доверяют. Он используется для построения систем вроде Instagram.
-Django довольно тесно связан с реляционными базами данных (такими как MySQL или PostgreSQL), потому использовать NoSQL базы данных (например, Couchbase, MongoDB, Cassandra и т.п.) в качестве основного хранилища данных - непросто.
+Он относительно тесно связан с реляционными базами данных (например, MySQL или PostgreSQL), поэтому использовать NoSQL-базу данных (например, Couchbase, MongoDB, Cassandra и т. п.) в качестве основного хранилища не очень просто.
-Он был создан для генерации HTML-страниц на сервере, а не для создания API, используемых современными веб-интерфейсами (React, Vue.js, Angular и т.п.) или другими системами (например, IoT) взаимодействующими с сервером.
+Он был создан для генерации HTML на бэкенде, а не для создания API, используемых современным фронтендом (например, React, Vue.js и Angular) или другими системами (например, устройствами IoT), которые с ним общаются.
-### Django REST Framework
+### Django REST Framework { #django-rest-framework }
-Фреймворк Django REST был создан, как гибкий инструментарий для создания веб-API на основе Django.
+Django REST Framework был создан как гибкий набор инструментов для построения веб-API поверх Django, чтобы улучшить его возможности в части API.
-DRF использовался многими компаниями, включая Mozilla, Red Hat и Eventbrite.
+Он используется многими компаниями, включая Mozilla, Red Hat и Eventbrite.
-Это был один из первых примеров **автоматического документирования API** и это была одна из первых идей, вдохновивших на создание **FastAPI**.
+Это был один из первых примеров **автоматической документации API**, и именно эта идея одной из первых вдохновила на «поиск» **FastAPI**.
/// note | Заметка
-Django REST Framework был создан Tom Christie.
-Он же создал Starlette и Uvicorn, на которых основан **FastAPI**.
+Django REST Framework был создан Томом Кристи. Он же создал Starlette и Uvicorn, на которых основан **FastAPI**.
///
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Должно быть автоматическое создание документации API с пользовательским веб-интерфейсом.
+Наличие пользовательского веб-интерфейса с автоматической документацией API.
///
-### Flask
+### Flask { #flask }
-Flask - это "микрофреймворк", в нём нет интеграции с базами данных и многих других вещей, которые предустановлены в Django.
+Flask — это «микрофреймворк», он не включает интеграции с базами данных и многие другие вещи, которые в Django идут «из коробки».
-Его простота и гибкость дают широкие возможности, такие как использование баз данных NoSQL в качестве основной системы хранения данных.
+Эта простота и гибкость позволяет, например, использовать NoSQL-базы в качестве основной системы хранения данных.
-Он очень прост, его изучение интуитивно понятно, хотя в некоторых местах документация довольно техническая.
+Он очень прост, его относительно легко интуитивно освоить, хотя местами документация довольно техническая.
-Flask часто используется и для приложений, которым не нужна база данных, настройки прав доступа для пользователей и прочие из множества функций, предварительно встроенных в Django.
-Хотя многие из этих функций могут быть добавлены с помощью плагинов.
+Его также часто используют для приложений, которым не нужна база данных, управление пользователями или многие другие функции, предварительно встроенные в Django. Хотя многие из этих возможностей можно добавить плагинами.
-Такое разделение на части и то, что это "микрофреймворк", который можно расширить, добавляя необходимые возможности, было ключевой особенностью, которую я хотел сохранить.
+Такое разбиение на части и то, что это «микрофреймворк», который можно расширять ровно под нужды, — ключевая особенность, которую хотелось сохранить.
-Простота Flask, показалась мне подходящей для создания API.
-Но ещё нужно было найти "Django REST Framework" для Flask.
+С учётом простоты Flask он казался хорошим вариантом для создания API. Следующим было найти «Django REST Framework» для Flask.
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Это будет микрофреймворк. К нему легко будет добавить необходимые инструменты и части.
+Быть микро-фреймворком. Облегчить комбинирование необходимых инструментов и компонентов.
-Должна быть простая и лёгкая в использовании система маршрутизации запросов.
+Иметь простую и удобную систему маршрутизации.
///
-### Requests
+### Requests { #requests }
-На самом деле **FastAPI** не является альтернативой **Requests**.
-Их область применения очень разная.
+**FastAPI** на самом деле не альтернатива **Requests**. Их области применения очень различны.
-В принципе, можно использовать Requests *внутри* приложения FastAPI.
+Обычно Requests используют даже внутри приложения FastAPI.
-Но всё же я использовал в FastAPI некоторые идеи из Requests.
+И всё же **FastAPI** во многом вдохновлялся Requests.
-**Requests** - это библиотека для взаимодействия с API в качестве клиента,
-в то время как **FastAPI** - это библиотека для *создания* API (то есть сервера).
+**Requests** — это библиотека для взаимодействия с API (как клиент), а **FastAPI** — библиотека для создания API (как сервер).
-Они, так или иначе, диаметрально противоположны и дополняют друг друга.
+Они, в каком-то смысле, находятся на противоположных концах и дополняют друг друга.
-Requests имеет очень простой и понятный дизайн, очень прост в использовании и имеет разумные значения по умолчанию.
-И в то же время он очень мощный и настраиваемый.
+Requests имеет очень простой и понятный дизайн, им очень легко пользоваться, есть разумные значения по умолчанию. И при этом он очень мощный и настраиваемый.
-Вот почему на официальном сайте написано:
+Именно поэтому на официальном сайте сказано:
-> Requests - один из самых загружаемых пакетов Python всех времен
+> Requests — один из самых загружаемых Python-пакетов всех времён
-
-Использовать его очень просто. Например, чтобы выполнить запрос `GET`, Вы бы написали:
+Пользоваться им очень просто. Например, чтобы сделать запрос `GET`, вы бы написали:
```Python
response = requests.get("http://example.com/some/url")
```
-Противоположная *операция пути* в FastAPI может выглядеть следующим образом:
+Соответствующая в FastAPI API-операция пути могла бы выглядеть так:
```Python hl_lines="1"
@app.get("/some/url")
@@ -106,428 +96,390 @@ def read_url():
return {"message": "Hello World"}
```
-Глядите, как похоже `requests.get(...)` и `@app.get(...)`.
+Посмотрите, насколько похожи `requests.get(...)` и `@app.get(...)`.
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-* Должен быть простой и понятный API.
-* Нужно использовать названия HTTP-методов (операций) для упрощения понимания происходящего.
-* Должны быть разумные настройки по умолчанию и широкие возможности их кастомизации.
+* Иметь простой и понятный API.
+* Использовать названия HTTP-методов (операций) напрямую, простым и интуитивным образом.
+* Иметь разумные значения по умолчанию, но и мощные настройки.
///
-### Swagger / OpenAPI
+### Swagger / OpenAPI { #swagger-openapi }
-Главной функцией, которую я хотел унаследовать от Django REST Framework, была автоматическая документация API.
+Главной возможностью, которую хотелось взять из Django REST Framework, была автоматическая документация API.
-Но потом я обнаружил, что существует стандарт документирования API, использующий JSON (или YAML, расширение JSON) под названием Swagger.
+Затем я обнаружил, что есть стандарт для документирования API с использованием JSON (или YAML — расширения JSON), под названием Swagger.
-И к нему уже был создан пользовательский веб-интерфейс.
-Таким образом, возможность генерировать документацию Swagger для API позволила бы использовать этот интерфейс.
+И уже существовал веб-интерфейс для Swagger API. Поэтому возможность генерировать документацию Swagger для API позволила бы автоматически использовать этот веб-интерфейс.
В какой-то момент Swagger был передан Linux Foundation и переименован в OpenAPI.
-Вот почему, когда говорят о версии 2.0, обычно говорят "Swagger", а для версии 3+ "OpenAPI".
+Вот почему, говоря о версии 2.0, обычно говорят «Swagger», а о версии 3+ — «OpenAPI».
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Использовать открытые стандарты для спецификаций API вместо самодельных схем.
+Использовать открытый стандарт для спецификаций API вместо самодельной схемы.
-Совместимость с основанными на стандартах пользовательскими интерфейсами:
+И интегрировать основанные на стандартах инструменты пользовательского интерфейса:
* Swagger UI
* ReDoc
-Они были выбраны за популярность и стабильность.
-Но сделав беглый поиск, Вы можете найти десятки альтернативных пользовательских интерфейсов для OpenAPI, которые Вы можете использовать с **FastAPI**.
+Эти два инструмента выбраны за популярность и стабильность, но даже при беглом поиске можно найти десятки альтернативных интерфейсов для OpenAPI (которые можно использовать с **FastAPI**).
///
-### REST фреймворки для Flask
+### REST-фреймворки для Flask { #flask-rest-frameworks }
-Существует несколько REST фреймворков для Flask, но потратив время и усилия на их изучение, я обнаружил, что многие из них не обновляются или заброшены и имеют нерешённые проблемы из-за которых они непригодны к использованию.
+Существует несколько REST-фреймворков для Flask, но, вложив время и усилия в исследование, я обнаружил, что многие из них прекращены или заброшены, с несколькими нерешёнными Issue (тикет\обращение), из-за которых они непригодны.
-### Marshmallow
+### Marshmallow { #marshmallow }
-Одной из основных функций, необходимых системам API, является "сериализация" данных, то есть преобразование данных из кода (Python) во что-то, что может быть отправлено по сети.
-Например, превращение объекта содержащего данные из базы данных в объект JSON, конвертация объекта `datetime` в строку и т.п.
+Одна из основных возможностей, нужных системам API, — «сериализация» данных, то есть преобразование данных из кода (Python) во что-то, что можно отправить по сети. Например, преобразование объекта с данными из базы в JSON-объект. Преобразование объектов `datetime` в строки и т. п.
-Еще одна важная функция, необходимая API — проверка данных, позволяющая убедиться, что данные действительны и соответствуют заданным параметрам.
-Как пример, можно указать, что ожидаются данные типа `int`, а не какая-то произвольная строка.
-Это особенно полезно для входящих данных.
+Ещё одна важная возможность, востребованная API, — валидация данных: убеждаться, что данные валидны с учётом заданных параметров. Например, что какое-то поле — `int`, а не произвольная строка. Это особенно полезно для входящих данных.
-Без системы проверки данных Вам пришлось бы прописывать все проверки вручную.
+Без системы валидации данных вам пришлось бы выполнять все проверки вручную в коде.
-Именно для обеспечения этих функций и была создана Marshmallow.
-Это отличная библиотека и я много раз пользовался ею раньше.
+Именно для этих возможностей и был создан Marshmallow. Это отличная библиотека, я много ей пользовался раньше.
-Но она была создана до того, как появились подсказки типов Python.
-Итак, чтобы определить каждую схему,
-Вам нужно использовать определенные утилиты и классы, предоставляемые Marshmallow.
+Но она появилась до того, как в Python появились аннотации типов. Поэтому для определения каждой схемы нужно использовать специальные утилиты и классы, предоставляемые Marshmallow.
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Использовать код программы для автоматического создания "схем", определяющих типы данных и их проверку.
+Использовать код для автоматического определения «схем», задающих типы данных и их валидацию.
///
-### Webargs
+### Webargs { #webargs }
-Другая немаловажная функция API - парсинг данных из входящих запросов.
+Ещё одна важная возможность для API — парсинг данных из входящих HTTP-запросов.
-Webargs - это инструмент, который был создан для этого и поддерживает несколько фреймворков, включая Flask.
+Webargs — это инструмент, созданный для этого поверх нескольких фреймворков, включая Flask.
-Для проверки данных он использует Marshmallow и создан теми же авторами.
+Он использует Marshmallow для валидации данных. И создан теми же разработчиками.
-Это превосходный инструмент и я тоже часто пользовался им до **FastAPI**.
+Это отличный инструмент, и я тоже много им пользовался до появления **FastAPI**.
/// info | Информация
-Webargs бы создан разработчиками Marshmallow.
+Webargs был создан теми же разработчиками, что и Marshmallow.
///
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Должна быть автоматическая проверка входных данных.
+Автоматическую валидацию входящих данных HTTP-запроса.
///
-### APISpec
+### APISpec { #apispec }
-Marshmallow и Webargs осуществляют проверку, анализ и сериализацию данных как плагины.
+Marshmallow и Webargs предоставляют валидацию, парсинг и сериализацию как плагины.
-Но документации API всё ещё не было. Тогда был создан APISpec.
+Но документации всё ещё не было. Тогда появился APISpec.
-Это плагин для множества фреймворков, в том числе и для Starlette.
+Это плагин для многих фреймворков (есть плагин и для Starlette).
-Он работает так - Вы записываете определение схем, используя формат YAML, внутри докстринга каждой функции, обрабатывающей маршрут.
+Он работает так: вы пишете определение схемы в формате YAML внутри докстринга каждой функции, обрабатывающей маршрут.
-Используя эти докстринги, он генерирует схему OpenAPI.
+И он генерирует схемы OpenAPI.
-Так это работает для Flask, Starlette, Responder и т.п.
+Так это работает во Flask, Starlette, Responder и т. д.
-Но теперь у нас возникает новая проблема - наличие постороннего микро-синтаксиса внутри кода Python (большие YAML).
+Но у нас снова возникает проблема: появляется микро-синтаксис внутри строки Python (большой YAML).
-Редактор кода не особо может помочь в такой парадигме.
-А изменив какие-то параметры или схемы для Marshmallow можно забыть отредактировать докстринг с YAML и сгенерированная схема становится недействительной.
+Редактор кода мало чем может помочь. И если мы изменим параметры или схемы Marshmallow и забудем также изменить YAML в докстринге, сгенерированная схема устареет.
/// info | Информация
-APISpec тоже был создан авторами Marshmallow.
+APISpec был создан теми же разработчиками, что и Marshmallow.
///
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Необходима поддержка открытого стандарта для API - OpenAPI.
+Поддержку открытого стандарта для API — OpenAPI.
///
-### Flask-apispec
+### Flask-apispec { #flask-apispec }
-Это плагин для Flask, который связан с Webargs, Marshmallow и APISpec.
+Это плагин для Flask, который связывает Webargs, Marshmallow и APISpec.
-Он получает информацию от Webargs и Marshmallow, а затем использует APISpec для автоматического создания схемы OpenAPI.
+Он использует информацию из Webargs и Marshmallow, чтобы автоматически генерировать схемы OpenAPI с помощью APISpec.
-Это отличный, но крайне недооценённый инструмент.
-Он должен быть более популярен, чем многие плагины для Flask.
-Возможно, это связано с тем, что его документация слишком скудна и абстрактна.
+Отличный и недооценённый инструмент. Он заслуживает большей популярности, чем многие плагины для Flask. Возможно, из-за слишком краткой и абстрактной документации.
-Он избавил от необходимости писать чужеродный синтаксис YAML внутри докстрингов.
+Это решило проблему необходимости писать YAML (ещё один синтаксис) в докстрингах Python.
-Такое сочетание Flask, Flask-apispec, Marshmallow и Webargs было моим любимым стеком при построении бэкенда до появления **FastAPI**.
+Комбинация Flask, Flask-apispec с Marshmallow и Webargs была моим любимым бэкенд-стеком до создания **FastAPI**.
-Использование этого стека привело к созданию нескольких генераторов проектов. Я и некоторые другие команды до сих пор используем их:
+Его использование привело к созданию нескольких full-stack генераторов на Flask. Это основные стеки, которые я (и несколько внешних команд) использовали до сих пор:
* https://github.com/tiangolo/full-stack
* https://github.com/tiangolo/full-stack-flask-couchbase
* https://github.com/tiangolo/full-stack-flask-couchdb
-Эти генераторы проектов также стали основой для [Генераторов проектов с **FastAPI**](project-generation.md){.internal-link target=_blank}.
+И эти же full-stack генераторы стали основой для [Генераторов проектов **FastAPI**](project-generation.md){.internal-link target=_blank}.
/// info | Информация
-Как ни странно, но Flask-apispec тоже создан авторами Marshmallow.
+Flask-apispec был создан теми же разработчиками, что и Marshmallow.
///
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Схема OpenAPI должна создаваться автоматически и использовать тот же код, который осуществляет сериализацию и проверку данных.
+Автоматическую генерацию схемы OpenAPI из того же кода, который определяет сериализацию и валидацию.
///
-### NestJS (и Angular)
+### NestJS (и Angular) { #nestjs-and-angular }
-Здесь даже не используется Python. NestJS - этот фреймворк написанный на JavaScript (TypeScript), основанный на NodeJS и вдохновлённый Angular.
+Это даже не Python. NestJS — это JavaScript/TypeScript-фреймворк на NodeJS, вдохновлённый Angular.
-Он позволяет получить нечто похожее на то, что можно сделать с помощью Flask-apispec.
+Он достигает чего-то отчасти похожего на то, что можно сделать с Flask-apispec.
-В него встроена система внедрения зависимостей, ещё одна идея взятая от Angular.
-Однако требуется предварительная регистрация "внедрений" (как и во всех других известных мне системах внедрения зависимостей), что увеличивает количество и повторяемость кода.
+В нём встроена система внедрения зависимостей, вдохновлённая Angular 2. Требуется предварительная регистрация «инжектируемых» компонентов (как и во всех известных мне системах внедрения зависимостей), что добавляет многословности и повторяемости кода.
-Так как параметры в нём описываются с помощью типов TypeScript (аналогично подсказкам типов в Python), поддержка редактора работает довольно хорошо.
+Поскольку параметры описываются с помощью типов TypeScript (аналог аннотаций типов в Python), поддержка редактора весьма хороша.
-Но поскольку данные из TypeScript не сохраняются после компиляции в JavaScript, он не может полагаться на подсказки типов для определения проверки данных, сериализации и документации.
-Из-за этого и некоторых дизайнерских решений, для валидации, сериализации и автоматической генерации схем, приходится во многих местах добавлять декораторы.
-Таким образом, это становится довольно многословным.
+Но так как данные о типах TypeScript не сохраняются после компиляции в JavaScript, он не может полагаться на типы для одновременного определения валидации, сериализации и документации. Из‑за этого и некоторых проектных решений для получения валидации, сериализации и автоматической генерации схем приходится добавлять декораторы во многих местах. В итоге это становится довольно многословным.
-Кроме того, он не очень хорошо справляется с вложенными моделями.
-Если в запросе имеется объект JSON, внутренние поля которого, в свою очередь, являются вложенными объектами JSON, это не может быть должным образом задокументировано и проверено.
+Он плохо справляется с вложенными моделями. Если JSON-тело запроса — это объект JSON, содержащий внутренние поля, которые сами являются вложенными объектами JSON, это нельзя как следует задокументировать и провалидировать.
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Нужно использовать подсказки типов, чтоб воспользоваться поддержкой редактора кода.
+Использовать типы Python для отличной поддержки в редакторе кода.
-Нужна мощная система внедрения зависимостей. Необходим способ для уменьшения повторов кода.
+Иметь мощную систему внедрения зависимостей. Найти способ минимизировать повторение кода.
///
-### Sanic
+### Sanic { #sanic }
-Sanic был одним из первых чрезвычайно быстрых Python-фреймворков основанных на `asyncio`.
-Он был сделан очень похожим на Flask.
+Это был один из первых чрезвычайно быстрых Python-фреймворков на основе `asyncio`. Он был сделан очень похожим на Flask.
/// note | Технические детали
-В нём использован `uvloop` вместо стандартного цикла событий `asyncio`, что и сделало его таким быстрым.
+Он использовал `uvloop` вместо стандартного цикла `asyncio` в Python. Это и сделало его таким быстрым.
-Он явно вдохновил создателей Uvicorn и Starlette, которые в настоящее время быстрее Sanic в открытых бенчмарках.
+Он явно вдохновил Uvicorn и Starlette, которые сейчас быстрее Sanic в открытых бенчмарках.
///
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Должна быть сумасшедшая производительность.
+Поиск способа достичь сумасшедшей производительности.
-Для этого **FastAPI** основан на Starlette, самом быстром из доступных фреймворков (по замерам незаинтересованных лиц).
+Именно поэтому **FastAPI** основан на Starlette, так как это самый быстрый доступный фреймворк (по данным сторонних бенчмарков).
///
-### Falcon
+### Falcon { #falcon }
-Falcon - ещё один высокопроизводительный Python-фреймворк.
-В нём минимум функций и он создан, чтоб быть основой для других фреймворков, например, Hug.
+Falcon — ещё один высокопроизводительный Python-фреймворк, он минималистичен и служит основой для других фреймворков, таких как Hug.
-Функции в нём получают два параметра - "запрос к серверу" и "ответ сервера".
-Затем Вы "читаете" часть запроса и "пишите" часть ответа.
-Из-за такой конструкции невозможно объявить параметры запроса и тела сообщения со стандартными подсказками типов Python в качестве параметров функции.
+Он спроектирован так, что функции получают два параметра: «request» и «response». Затем вы «читаете» части из запроса и «пишете» части в ответ. Из‑за такого дизайна невозможно объявить параметры запроса и тело запроса стандартными аннотациями типов Python как параметры функции.
-Таким образом, и валидацию данных, и их сериализацию, и документацию нужно прописывать вручную.
-Либо эти функции должны быть встроены во фреймворк, сконструированный поверх Falcon, как в Hug.
-Такая же особенность присутствует и в других фреймворках, вдохновлённых идеей Falcon, использовать только один объект запроса и один объект ответа.
+Поэтому валидация данных, сериализация и документация должны выполняться в коде вручную, не автоматически. Либо должны быть реализованы во фреймворке поверх Falcon, как в Hug. Та же особенность есть и в других фреймворках, вдохновлённых дизайном Falcon — с одним объектом запроса и одним объектом ответа в параметрах.
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Найдите способы добиться отличной производительности.
+Поиск способов получить отличную производительность.
-Объявлять параметры `ответа сервера` в функциях, как в Hug.
+Вместе с Hug (так как Hug основан на Falcon) вдохновило **FastAPI** объявлять параметр `response` в функциях.
-Хотя в FastAPI это необязательно и используется в основном для установки заголовков, куки и альтернативных кодов состояния.
+Хотя в FastAPI это необязательно, и используется в основном для установки HTTP-заголовков, cookie и альтернативных статус-кодов.
///
-### Molten
+### Molten { #molten }
-Molten мне попался на начальной стадии написания **FastAPI**. В нём были похожие идеи:
+Я обнаружил Molten на ранних этапах создания **FastAPI**. И у него были очень похожие идеи:
-* Использование подсказок типов.
-* Валидация и документация исходя из этих подсказок.
+* Основан на аннотациях типов Python.
+* Валидация и документация из этих типов.
* Система внедрения зависимостей.
-В нём не используются сторонние библиотеки (такие, как Pydantic) для валидации, сериализации и документации.
-Поэтому переиспользовать эти определения типов непросто.
+Он не использует стороннюю библиотеку для валидации, сериализации и документации, такую как Pydantic, — у него своя. Поэтому такие определения типов данных будет сложнее переиспользовать.
-Также требуется более подробная конфигурация и используется стандарт WSGI, который не предназначен для использования с высокопроизводительными инструментами, такими как Uvicorn, Starlette и Sanic, в отличие от ASGI.
+Требуются более многословные конфигурации. И так как он основан на WSGI (вместо ASGI), он не предназначен для использования преимуществ высокой производительности инструментов вроде Uvicorn, Starlette и Sanic.
-Его система внедрения зависимостей требует предварительной регистрации, и зависимости определяются, как объявления типов.
-Из-за этого невозможно объявить более одного "компонента" (зависимости), который предоставляет определенный тип.
+Система внедрения зависимостей требует предварительной регистрации зависимостей, а зависимости разрешаются по объявленным типам. Поэтому невозможно объявить более одного «компонента», предоставляющего определённый тип.
-Маршруты объявляются в единственном месте с использованием функций, объявленных в других местах (вместо использования декораторов, в которые могут быть обёрнуты функции, обрабатывающие конкретные ресурсы).
-Это больше похоже на Django, чем на Flask и Starlette.
-Он разделяет в коде вещи, которые довольно тесно связаны.
+Маршруты объявляются в одном месте, используя функции, объявленные в других местах (вместо декораторов, которые можно разместить прямо над функцией, обрабатывающей эндпоинт). Это ближе к тому, как это делает Django, чем Flask (и Starlette). Это разделяет в коде вещи, которые довольно тесно связаны.
-/// check | Идея для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Определить дополнительные проверки типов данных, используя значения атрибутов модели "по умолчанию".
-Это улучшает помощь редактора и раньше это не было доступно в Pydantic.
+Определять дополнительные проверки типов данных, используя значение «по умолчанию» атрибутов модели. Это улучшает поддержку в редакторе кода, и раньше этого не было в Pydantic.
-Фактически это подтолкнуло на обновление Pydantic для поддержки одинакового стиля проверок (теперь этот функционал уже доступен в Pydantic).
+Фактически это вдохновило на обновление частей Pydantic, чтобы поддерживать такой же стиль объявления валидации (вся эта функциональность теперь уже есть в Pydantic).
///
-### Hug
+### Hug { #hug }
-Hug был одним из первых фреймворков, реализовавших объявление параметров API с использованием подсказок типов Python.
-Эта отличная идея была использована и другими инструментами.
+Hug был одним из первых фреймворков, реализовавших объявление типов параметров API с использованием аннотаций типов Python. Это была отличная идея, которая вдохновила и другие инструменты.
-При объявлении параметров вместо стандартных типов Python использовались собственные типы, но всё же это был огромный шаг вперед.
+Он использовал собственные типы в объявлениях вместо стандартных типов Python, но это всё равно был огромный шаг вперёд.
-Это также был один из первых фреймворков, генерировавших полную API-схему в формате JSON.
+Он также был одним из первых фреймворков, генерировавших собственную схему, описывающую весь API в JSON.
-Данная схема не придерживалась стандартов вроде OpenAPI и JSON Schema.
-Поэтому было бы непросто совместить её с другими инструментами, такими как Swagger UI.
-Но опять же, это была очень инновационная идея.
+Он не был основан на стандартах вроде OpenAPI и JSON Schema. Поэтому интегрировать его с другими инструментами, такими как Swagger UI, было бы непросто. Но, опять же, это была очень инновационная идея.
-Ещё у него есть интересная и необычная функция: используя один и тот же фреймворк можно создавать и API, и CLI.
+У него есть интересная и необычная особенность: с помощью одного и того же фреймворка можно создавать и API, и CLI.
-Поскольку он основан на WSGI, старом стандарте для синхронных веб-фреймворков, он не может работать с веб-сокетами и другими модными штуками, но всё равно обладает высокой производительностью.
+Так как он основан на предыдущем стандарте для синхронных веб-фреймворков Python (WSGI), он не может работать с WebSocket и прочим, хотя также демонстрирует высокую производительность.
/// info | Информация
-Hug создан Timothy Crosley, автором `isort`, отличного инструмента для автоматической сортировки импортов в Python-файлах.
+Hug был создан Тимоти Кросли, тем же автором `isort`, отличного инструмента для автоматической сортировки импортов в файлах Python.
///
-/// check | Идеи для **FastAPI**
+/// check | Идеи, вдохновившие **FastAPI**
-Hug повлиял на создание некоторых частей APIStar и был одним из инструментов, которые я счел наиболее многообещающими, наряду с APIStar.
+Hug вдохновил части APIStar и был одним из наиболее многообещающих инструментов, которые я нашёл, наряду с APIStar.
-Hug натолкнул на мысли использовать в **FastAPI** подсказки типов Python для автоматического создания схемы, определяющей API и его параметры.
+Hug помог вдохновить **FastAPI** использовать аннотации типов Python для объявления параметров и автоматически генерировать схему, определяющую API.
-Hug вдохновил **FastAPI** объявить параметр `ответа` в функциях для установки заголовков и куки.
+Hug вдохновил **FastAPI** объявлять параметр `response` в функциях для установки HTTP-заголовков и cookie.
///
-### APIStar (<= 0.5)
+### APIStar (<= 0.5) { #apistar-0-5 }
-Непосредственно перед тем, как принять решение о создании **FastAPI**, я обнаружил **APIStar**.
-В нем было почти все, что я искал и у него был отличный дизайн.
+Прямо перед решением строить **FastAPI** я нашёл сервер **APIStar**. В нём было почти всё, что я искал, и отличный дизайн.
-Это была одна из первых реализаций фреймворка, использующего подсказки типов для объявления параметров и запросов, которые я когда-либо видел (до NestJS и Molten).
-Я нашёл его примерно в то же время, что и Hug, но APIStar использовал стандарт OpenAPI.
+Это была одна из первых реализаций фреймворка, использующего аннотации типов Python для объявления параметров и запросов (до NestJS и Molten), которые я видел. Я обнаружил его примерно в то же время, что и Hug. Но APIStar использовал стандарт OpenAPI.
-В нём были автоматические проверка и сериализация данных и генерация схемы OpenAPI основанные на подсказках типов в нескольких местах.
+В нём были автоматические валидация данных, сериализация данных и генерация схемы OpenAPI на основе тех же аннотаций типов в нескольких местах.
-При определении схемы тела сообщения не использовались подсказки типов, как в Pydantic, это больше похоже на Marshmallow, поэтому помощь редактора была недостаточно хорошей, но всё же APIStar был лучшим доступным вариантом.
+Определение схемы тела запроса не использовало те же аннотации типов Python, как в Pydantic, — это было ближе к Marshmallow, поэтому поддержка редактора была бы хуже, но всё равно APIStar оставался лучшим доступным вариантом.
-На тот момент у него были лучшие показатели производительности (проигрывающие только Starlette).
+На тот момент у него были лучшие показатели в бенчмарках (его превосходил только Starlette).
-Изначально у него не было автоматической документации API для веб-интерфейса, но я знал, что могу добавить к нему Swagger UI.
+Сначала у него не было веб‑UI для автоматической документации API, но я знал, что могу добавить к нему Swagger UI.
-В APIStar была система внедрения зависимостей, которая тоже требовала предварительную регистрацию компонентов, как и ранее описанные инструменты.
-Но, тем не менее, это была отличная штука.
+У него была система внедрения зависимостей. Она требовала предварительной регистрации компонентов, как и другие инструменты, обсуждавшиеся выше. Но всё же это была отличная возможность.
-Я не смог использовать его в полноценном проекте, так как были проблемы со встраиванием функций безопасности в схему OpenAPI, из-за которых невозможно было встроить все функции, применяемые в генераторах проектов на основе Flask-apispec.
-Я добавил в свой список задач создание пул-реквеста, добавляющего эту функциональность.
+Мне так и не удалось использовать его в полном проекте, поскольку не было интеграции с системой безопасности, поэтому я не мог заменить все возможности, которые имел с full-stack генераторами на основе Flask-apispec. В моём бэклоге было создать пулл-реквест (запрос на изменение), добавляющий эту функциональность.
-В дальнейшем фокус проекта сместился.
+Затем фокус проекта сместился.
-Это больше не был API-фреймворк, так как автор сосредоточился на Starlette.
+Это перестал быть веб-фреймворк для API, так как автору нужно было сосредоточиться на Starlette.
-Ныне APIStar - это набор инструментов для проверки спецификаций OpenAPI.
+Сейчас APIStar — это набор инструментов для валидации спецификаций OpenAPI, а не веб-фреймворк.
/// info | Информация
-APIStar был создан Tom Christie. Тот самый парень, который создал:
+APIStar был создан Томом Кристи. Тем самым человеком, который создал:
* Django REST Framework
* Starlette (на котором основан **FastAPI**)
-* Uvicorn (используемый в Starlette и **FastAPI**)
+* Uvicorn (используется Starlette и **FastAPI**)
///
-/// check | Идеи для **FastAPI**
+/// check | Вдохновило **FastAPI** на
-Воплощение.
+Существование.
-Мне казалось блестящей идеей объявлять множество функций (проверка данных, сериализация, документация) с помощью одних и тех же типов Python, которые при этом обеспечивают ещё и помощь редактора кода.
+Идея объявлять сразу несколько вещей (валидацию данных, сериализацию и документацию) с помощью одних и тех же типов Python, которые одновременно обеспечивают отличную поддержку в редакторе кода, показалась мне блестящей.
-После долгих поисков среди похожих друг на друга фреймворков и сравнения их различий, APIStar стал самым лучшим выбором.
+После долгих поисков похожего фреймворка и тестирования множества альтернатив APIStar был лучшим доступным вариантом.
-Но APIStar перестал быть фреймворком для создания веб-сервера, зато появился Starlette, новая и лучшая основа для построения подобных систем.
-Это была последняя капля, сподвигнувшая на создание **FastAPI**.
+Затем APIStar перестал существовать как сервер, а был создан Starlette — новая и лучшая основа для такой системы. Это стало окончательным вдохновением для создания **FastAPI**.
-Я считаю **FastAPI** "духовным преемником" APIStar, улучившим его возможности благодаря урокам, извлечённым из всех упомянутых выше инструментов.
+Я считаю **FastAPI** «духовным преемником» APIStar, который улучшает и расширяет возможности, систему типов и другие части, опираясь на уроки от всех этих предыдущих инструментов.
///
-## Что используется в **FastAPI**
+## Что используется в **FastAPI** { #used-by-fastapi }
+
+### Pydantic { #pydantic }
-### Pydantic
+Pydantic — это библиотека для определения валидации данных, сериализации и документации (с использованием JSON Schema) на основе аннотаций типов Python.
-Pydantic - это библиотека для валидации данных, сериализации и документирования (используя JSON Schema), основываясь на подсказках типов Python, что делает его чрезвычайно интуитивным.
+Благодаря этому он чрезвычайно интуитивен.
-Его можно сравнить с Marshmallow, хотя в бенчмарках Pydantic быстрее, чем Marshmallow.
-И он основан на тех же подсказках типов, которые отлично поддерживаются редакторами кода.
+Его можно сравнить с Marshmallow. Хотя в бенчмарках он быстрее Marshmallow. И поскольку он основан на тех же аннотациях типов Python, поддержка в редакторе кода отличная.
-/// check | **FastAPI** использует Pydantic
+/// check | **FastAPI** использует его для
-Для проверки данных, сериализации данных и автоматической документации моделей (на основе JSON Schema).
+Обработки всей валидации данных, сериализации данных и автоматической документации моделей (на основе JSON Schema).
-Затем **FastAPI** берёт эти схемы JSON и помещает их в схему OpenAPI, не касаясь других вещей, которые он делает.
+Затем **FastAPI** берёт эти данные JSON Schema и помещает их в OpenAPI, помимо всех прочих функций.
///
-### Starlette
+### Starlette { #starlette }
-Starlette - это легковесный ASGI фреймворк/набор инструментов, который идеален для построения высокопроизводительных асинхронных сервисов.
+Starlette — это лёгкий ASGI фреймворк/набор инструментов, идеально подходящий для создания высокопроизводительных asyncio‑сервисов.
-Starlette очень простой и интуитивный.
-Он разработан таким образом, чтобы быть легко расширяемым и иметь модульные компоненты.
+Он очень простой и интуитивный. Спроектирован так, чтобы его было легко расширять, и чтобы компоненты были модульными.
В нём есть:
* Впечатляющая производительность.
-* Поддержка веб-сокетов.
-* Фоновые задачи.
-* Обработка событий при старте и финише приложения.
-* Тестовый клиент на основе HTTPX.
-* Поддержка CORS, сжатие GZip, статические файлы, потоковая передача данных.
-* Поддержка сессий и куки.
+* Поддержка WebSocket.
+* Фоновые задачи, выполняемые в том же процессе.
+* События запуска и завершения.
+* Тестовый клиент на базе HTTPX.
+* CORS, GZip, статические файлы, потоковые ответы.
+* Поддержка сессий и cookie.
* 100% покрытие тестами.
-* 100% аннотированный код.
-* Несколько жёстких зависимостей.
+* 100% кодовой базы с аннотациями типов.
+* Мало жёстких зависимостей.
+
+В настоящее время Starlette — самый быстрый из протестированных Python-фреймворков. Его превосходит только Uvicorn, который не фреймворк, а сервер.
-В настоящее время Starlette показывает самую высокую скорость среди Python-фреймворков в тестовых замерах.
-Быстрее только Uvicorn, который является сервером, а не фреймворком.
+Starlette предоставляет весь базовый функционал веб-микрофреймворка.
-Starlette обеспечивает весь функционал микрофреймворка, но не предоставляет автоматическую валидацию данных, сериализацию и документацию.
+Но он не предоставляет автоматическую валидацию данных, сериализацию или документацию.
-**FastAPI** добавляет эти функции используя подсказки типов Python и Pydantic.
-Ещё **FastAPI** добавляет систему внедрения зависимостей, утилиты безопасности, генерацию схемы OpenAPI и т.д.
+Это одна из главных вещей, которые **FastAPI** добавляет поверх, всё на основе аннотаций типов Python (с использованием Pydantic). Плюс система внедрения зависимостей, утилиты безопасности, генерация схемы OpenAPI и т. д.
/// note | Технические детали
-ASGI - это новый "стандарт" разработанный участниками команды Django.
-Он пока что не является "стандартом в Python" (то есть принятым PEP), но процесс принятия запущен.
+ASGI — это новый «стандарт», разрабатываемый участниками core-команды Django. Он всё ещё не является «стандартом Python» (PEP), хотя процесс идёт.
-Тем не менее он уже используется в качестве "стандарта" несколькими инструментами.
-Это значительно улучшает совместимость, поскольку Вы можете переключиться с Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или Вы можете добавить ASGI-совместимые инструменты, такие как `python-socketio`.
+Тем не менее его уже используют как «стандарт» несколько инструментов. Это сильно улучшает совместимость: вы можете заменить Uvicorn на любой другой ASGI-сервер (например, Daphne или Hypercorn) или добавить совместимые с ASGI инструменты, такие как `python-socketio`.
///
-/// check | **FastAPI** использует Starlette
+/// check | **FastAPI** использует его для
-В качестве ядра веб-сервиса для обработки запросов, добавив некоторые функции сверху.
+Обработки всех основных веб-частей. Добавляя возможности поверх.
-Класс `FastAPI` наследуется напрямую от класса `Starlette`.
+Класс `FastAPI` напрямую наследуется от класса `Starlette`.
-Таким образом, всё что Вы могли делать со Starlette, Вы можете делать с **FastAPI**, по сути это прокачанный Starlette.
+Так что всё, что вы можете сделать со Starlette, вы можете сделать напрямую с **FastAPI**, по сути это «Starlette на стероидах».
///
-### Uvicorn
+### Uvicorn { #uvicorn }
-Uvicorn - это молниеносный ASGI-сервер, построенный на uvloop и httptools.
+Uvicorn — молниеносный ASGI-сервер, построенный на uvloop и httptools.
-Uvicorn является сервером, а не фреймворком.
-Например, он не предоставляет инструментов для маршрутизации запросов по ресурсам.
-Для этого нужна надстройка, такая как Starlette (или **FastAPI**).
+Это не веб-фреймворк, а сервер. Например, он не предоставляет инструменты для маршрутизации по путям. Это предоставляет сверху фреймворк, такой как Starlette (или **FastAPI**).
-Он рекомендуется в качестве сервера для Starlette и **FastAPI**.
+Это рекомендуемый сервер для Starlette и **FastAPI**.
-/// check | **FastAPI** рекомендует его
+/// check | **FastAPI** рекомендует его как
-Как основной сервер для запуска приложения **FastAPI**.
+Основной веб-сервер для запуска приложений **FastAPI**.
-Вы можете объединить его с Gunicorn, чтобы иметь асинхронный многопроцессный сервер.
+Также вы можете использовать опцию командной строки `--workers`, чтобы получить асинхронный многопроцессный сервер.
-Узнать больше деталей можно в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}.
+Подробнее см. раздел [Развёртывание](deployment/index.md){.internal-link target=_blank}.
///
-## Тестовые замеры и скорость
+## Бенчмарки и скорость { #benchmarks-and-speed }
-Чтобы понять, сравнить и увидеть разницу между Uvicorn, Starlette и FastAPI, ознакомьтесь с разделом [Тестовые замеры](benchmarks.md){.internal-link target=_blank}.
+Чтобы понять, сравнить и увидеть разницу между Uvicorn, Starlette и FastAPI, см. раздел о [Бенчмарках](benchmarks.md){.internal-link target=_blank}.
diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md
index 813836d36..15d4e108a 100644
--- a/docs/ru/docs/async.md
+++ b/docs/ru/docs/async.md
@@ -1,18 +1,18 @@
-# Конкурентность и async / await
+# Конкурентность и async / await { #concurrency-and-async-await }
-Здесь приведена подробная информация об использовании синтаксиса `async def` при написании *функций обработки пути*, а также рассмотрены основы асинхронного программирования, конкурентности и параллелизма.
+Подробности о синтаксисе `async def` для *функций-обработчиков пути* и немного фона об асинхронном коде, конкурентности и параллелизме.
-## Нет времени?
+## Нет времени? { #in-a-hurry }
-TL;DR:
+TL;DR:
-Допустим, вы используете сторонюю библиотеку, которая требует вызова с ключевым словом `await`:
+Если вы используете сторонние библиотеки, которые нужно вызывать с `await`, например:
```Python
results = await some_library()
```
-В этом случае *функции обработки пути* необходимо объявлять с использованием синтаксиса `async def`:
+Тогда объявляйте *функции-обработчики пути* с `async def`, например:
```Python hl_lines="2"
@app.get('/')
@@ -21,18 +21,15 @@ async def read_results():
return results
```
-/// note
+/// note | Примечание
-`await` можно использовать только внутри функций, объявленных с использованием `async def`.
+`await` можно использовать только внутри функций, объявленных с `async def`.
///
---
-Если вы обращаетесь к сторонней библиотеке, которая с чем-то взаимодействует
-(с базой данных, API, файловой системой и т. д.), и не имеет поддержки синтаксиса `await`
-(что относится сейчас к большинству библиотек для работы с базами данных), то
-объявляйте *функции обработки пути* обычным образом с помощью `def`, например:
+Если вы используете стороннюю библиотеку, которая взаимодействует с чем-то (база данных, API, файловая система и т.д.) и не поддерживает использование `await` (сейчас это относится к большинству библиотек для БД), тогда объявляйте *функции-обработчики пути* как обычно, просто с `def`, например:
```Python hl_lines="2"
@app.get('/')
@@ -43,310 +40,283 @@ def results():
---
-Если вашему приложению (странным образом) не нужно ни с чем взаимодействовать и, соответственно,
-ожидать ответа, используйте `async def`.
+Если вашему приложению (по какой-то причине) не нужно ни с чем взаимодействовать и ждать ответа, используйте `async def`, даже если внутри не нужен `await`.
---
-Если вы не уверены, используйте обычный синтаксис `def`.
+Если вы просто не уверены, используйте обычный `def`.
---
-**Примечание**: при необходимости можно смешивать `def` и `async def` в *функциях обработки пути*
-и использовать в каждом случае наиболее подходящий синтаксис. А FastAPI сделает с этим всё, что нужно.
+**Примечание**: вы можете смешивать `def` и `async def` в *функциях-обработчиках пути* столько, сколько нужно, и объявлять каждую так, как лучше для вашего случая. FastAPI сделает с ними всё как надо.
-В любом из описанных случаев FastAPI работает асинхронно и очень быстро.
+В любом из случаев выше FastAPI всё равно работает асинхронно и очень быстро.
-Однако придерживаясь указанных советов, можно получить дополнительную оптимизацию производительности.
+Но следуя этим шагам, он сможет выполнить некоторые оптимизации производительности.
-## Технические подробности
+## Технические подробности { #technical-details }
-Современные версии Python поддерживают разработку так называемого **"асинхронного кода"** посредством написания **"сопрограмм"** с использованием синтаксиса **`async` и `await`**.
+Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**.
-Ниже разберём эту фразу по частям:
+Разберём эту фразу по частям в разделах ниже:
* **Асинхронный код**
* **`async` и `await`**
* **Сопрограммы**
-## Асинхронный код
+## Асинхронный код { #asynchronous-code }
-Асинхронный код означает, что в языке 💬 есть возможность сообщить машине / программе 🤖,
-что в определённой точке кода ей 🤖 нужно будет ожидать завершения выполнения *чего-то ещё* в другом месте. Допустим это *что-то ещё* называется "медленный файл" 📝.
+Асинхронный код значит, что в языке 💬 есть способ сказать компьютеру/программе 🤖, что в некоторый момент кода ему 🤖 придётся подождать, пока *что-то ещё* где-то в другом месте завершится. Назовём это *что-то ещё* «медленный файл» 📝.
-И пока мы ждём завершения работы с "медленным файлом" 📝, компьютер может переключиться для выполнения других задач.
+И пока мы ждём завершения работы с «медленныи файлом» 📝, компьютер может заняться другой работой.
-Но при каждой возможности компьютер / программа 🤖 будет возвращаться обратно. Например, если он 🤖 опять окажется в режиме ожидания, или когда закончит всю работу. В этом случае компьютер 🤖 проверяет, не завершена ли какая-нибудь из текущих задач.
+Затем компьютер/программа 🤖 будет возвращаться каждый раз, когда появится возможность (пока снова где-то идёт ожидание), или когда 🤖 завершит всю текущую работу. И он 🤖 проверит, не завершилась ли какая-либо из задач, которых он ждал, и сделает то, что нужно.
-Потом он 🤖 берёт первую выполненную задачу (допустим, наш "медленный файл" 📝) и продолжает работу, производя с ней необходимые действия.
+Далее он 🤖 возьмёт первую завершившуюся задачу (скажем, наш «медленный файл» 📝) и продолжит делать с ней то, что требуется.
-Вышеупомянутое "что-то ещё", завершения которого приходится ожидать, обычно относится к достаточно "медленным" операциям I/O (по сравнению со скоростью работы процессора и оперативной памяти), например:
+Это «ожидание чего-то ещё» обычно относится к операциям I/O, которые относительно «медленные» (по сравнению со скоростью процессора и оперативной памяти), например ожидание:
-* отправка данных от клиента по сети
-* получение клиентом данных, отправленных вашей программой по сети
-* чтение системой содержимого файла с диска и передача этих данных программе
-* запись на диск данных, которые программа передала системе
-* обращение к удалённому API
-* ожидание завершения операции с базой данных
-* получение результатов запроса к базе данных
-* и т. д.
+* отправки данных клиентом по сети
+* получения клиентом данных, отправленных вашей программой по сети
+* чтения системой содержимого файла на диске и передачи этих данных вашей программе
+* записи на диск содержимого, которое ваша программа передала системе
+* операции удалённого API
+* завершения операции базы данных
+* возврата результатов запроса к базе данных
+* и т.д.
-Поскольку в основном время тратится на ожидание выполнения операций I/O,
-их обычно называют операциями, ограниченными скоростью ввода-вывода.
+Поскольку основное время выполнения уходит на ожидание операций I/O, их называют операциями, «ограниченными вводом-выводом» (I/O bound).
-Код называют "асинхронным", потому что компьютеру / программе не требуется "синхронизироваться" с медленной задачей и,
-будучи в простое, ожидать момента её завершения, с тем чтобы забрать результат и продолжить работу.
+Это называется «асинхронным», потому что компьютеру/программе не нужно «синхронизироваться» с медленной задачей, простаивая и выжидая точный момент её завершения, чтобы забрать результат и продолжить работу.
-Вместо этого в "асинхронной" системе завершённая задача может немного подождать (буквально несколько микросекунд),
-пока компьютер / программа занимается другими важными вещами, с тем чтобы потом вернуться,
-забрать результаты выполнения и начать их обрабатывать.
+Вместо этого, в «асинхронной» системе, уже завершившаяся задача может немного подождать (несколько микросекунд) в очереди, пока компьютер/программа завершит то, чем занимался, и затем вернётся, чтобы забрать результаты и продолжить работу с ними.
-"Синхронное" исполнение (в противовес "асинхронному") также называют "последовательным",
-потому что компьютер / программа последовательно выполняет все требуемые шаги перед тем, как перейти к следующей задаче,
-даже если в процессе приходится ждать.
+Для «синхронного» (в противоположность «асинхронному») исполнения часто используют термин «последовательный», потому что компьютер/программа выполняет все шаги по порядку, прежде чем переключиться на другую задачу, даже если эти шаги включают ожидание.
-### Конкурентность и бургеры
+### Конкурентность и бургеры { #concurrency-and-burgers }
-Тот **асинхронный** код, о котором идёт речь выше, иногда называют **"конкурентностью"**. Она отличается от **"параллелизма"**.
+Та идея **асинхронного** кода, описанная выше, иногда также называется **«конкурентностью»**. Она отличается от **«параллелизма»**.
-Да, **конкурентность** и **параллелизм** подразумевают, что разные вещи происходят примерно в одно время.
+И **конкурентность**, и **параллелизм** относятся к «разным вещам, происходящим примерно одновременно».
-Но внутреннее устройство **конкурентности** и **параллелизма** довольно разное.
+Но различия между *конкурентностью* и *параллелизмом* довольно существенные.
-Чтобы это понять, представьте такую картину:
+Чтобы их увидеть, представьте следующую историю про бургеры:
-### Конкурентные бургеры
+### Конкурентные бургеры { #concurrent-burgers }
-
+Вы идёте со своей возлюбленной за фастфудом, вы стоите в очереди, пока кассир принимает заказы у людей перед вами. 😍
-Вы идёте со своей возлюбленной 😍 в фастфуд 🍔 и становитесь в очередь, в это время кассир 💁 принимает заказы у посетителей перед вами.
+
-Когда наконец подходит очередь, вы заказываете парочку самых вкусных и навороченных бургеров 🍔, один для своей возлюбленной 😍, а другой себе.
+Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя. 🍔🍔
-Отдаёте деньги 💸.
+
-Кассир 💁 что-то говорит поварам на кухне 👨🍳, теперь они знают, какие бургеры нужно будет приготовить 🍔
-(но пока они заняты бургерами предыдущих клиентов).
+Кассир говорит что-то повару на кухне, чтобы они знали, что нужно приготовить ваши бургеры (хотя сейчас они готовят бургеры для предыдущих клиентов).
-Кассир 💁 отдаёт вам чек с номером заказа.
+
-В ожидании еды вы идёте со своей возлюбленной 😍 выбрать столик, садитесь и довольно продолжительное время общаетесь 😍
-(поскольку ваши бургеры самые навороченные, готовятся они не так быстро ✨🍔✨).
+Вы платите. 💸
-Сидя за столиком с возлюбленной 😍 в ожидании бургеров 🍔, вы отлично проводите время,
-восхищаясь её великолепием, красотой и умом ✨😍✨.
+Кассир выдаёт вам номер вашей очереди.
-Всё ещё ожидая заказ и болтая со своей возлюбленной 😍, время от времени вы проверяете,
-какой номер горит над прилавком, и не подошла ли уже ваша очередь.
+
-И вот наконец настаёт этот момент, и вы идёте к стойке, чтобы забрать бургеры 🍔 и вернуться за столик.
+Пока вы ждёте, вы вместе со своей возлюбленной идёте и выбираете столик, садитесь и долго болтаете (ваши бургеры очень «навороченные», поэтому им нужно время на приготовление).
-Вы со своей возлюбленной 😍 едите бургеры 🍔 и отлично проводите время ✨.
+Сидя за столиком со своей возлюбленной в ожидании бургеров, вы можете провести это время, восхищаясь тем, какая она классная, милая и умная ✨😍✨.
+
+
+
+Пока вы ждёте и разговариваете, время от времени вы поглядываете на номер на табло, чтобы понять, не подошла ли уже ваша очередь.
+
+И вот в какой-то момент ваша очередь наступает. Вы подходите к стойке, забираете свои бургеры и возвращаетесь к столику.
+
+
+
+Вы со своей возлюбленной едите бургеры и отлично проводите время. ✨
+
+
+
+/// info | Информация
+
+Прекрасные иллюстрации от Ketrina Thompson. 🎨
+
+///
---
-А теперь представьте, что в этой небольшой истории вы компьютер / программа 🤖.
+Представьте, что в этой истории вы — компьютер/программа 🤖.
-В очереди вы просто глазеете по сторонам 😴, ждёте и ничего особо "продуктивного" не делаете.
-Но очередь движется довольно быстро, поскольку кассир 💁 только принимает заказы (а не занимается приготовлением еды), так что ничего страшного.
+Пока вы стоите в очереди, вы просто бездействуете 😴, ждёте своей очереди и не делаете ничего особо «продуктивного». Но очередь движется быстро, потому что кассир только принимает заказы (а не готовит их), так что это нормально.
-Когда подходит очередь вы наконец предпринимаете "продуктивные" действия 🤓: просматриваете меню, выбираете в нём что-то, узнаёте, что хочет ваша возлюбленная 😍, собираетесь оплатить 💸, смотрите, какую достали карту, проверяете, чтобы с вас списали верную сумму, и что в заказе всё верно и т. д.
+Когда приходит ваша очередь, вы выполняете действительно «продуктивную» работу: просматриваете меню, решаете, чего хотите, учитываете выбор своей возлюбленной, платите, проверяете, что дали правильную купюру/карту, что сумма списана корректно, что в заказе верные позиции и т.д.
-И хотя вы всё ещё не получили бургеры 🍔, ваша работа с кассиром 💁 ставится "на паузу" ⏸,
-поскольку теперь нужно ждать 🕙, когда заказ приготовят.
+Но затем, хотя у вас ещё нет бургеров, ваша «работа» с кассиром поставлена «на паузу» ⏸, потому что нужно подождать 🕙, пока бургеры будут готовы.
-Но отойдя с номерком от прилавка, вы садитесь за столик и можете переключить 🔀 внимание
-на свою возлюбленную 😍 и "работать" ⏯ 🤓 уже над этим. И вот вы снова очень
-"продуктивны" 🤓, мило болтаете вдвоём и всё такое 😍.
+Но, отойдя от стойки и сев за столик с номерком, вы можете переключить 🔀 внимание на свою возлюбленную и «поработать» ⏯ 🤓 над этим. Снова очень «продуктивно» — флирт с вашей возлюбленной 😍.
-В какой-то момент кассир 💁 поместит на табло ваш номер, подразумевая, что бургеры готовы 🍔, но вы не станете подскакивать как умалишённый, лишь только увидев на экране свою очередь. Вы уверены, что ваши бургеры 🍔 никто не утащит, ведь у вас свой номерок, а у других свой.
+Потом кассир 💁 «говорит»: «Я закончил делать бургеры», — выводя ваш номер на табло, но вы не подпрыгиваете как сумасшедший в ту же секунду, как только номер сменился на ваш. Вы знаете, что ваши бургеры никто не украдёт, потому что у вас есть номер вашей очереди, а у других — их.
-Поэтому вы подождёте, пока возлюбленная 😍 закончит рассказывать историю (закончите текущую работу ⏯ / задачу в обработке 🤓),
-и мило улыбнувшись, скажете, что идёте забирать заказ ⏸.
+Поэтому вы дожидаетесь, пока ваша возлюбленная закончит историю (завершится текущая работа ⏯ / выполняемая задача 🤓), мягко улыбаетесь и говорите, что идёте за бургерами ⏸.
-И вот вы подходите к стойке 🔀, к первоначальной задаче, которая уже завершена ⏯, берёте бургеры 🍔, говорите спасибо и относите заказ за столик. На этом заканчивается этап / задача взаимодействия с кассой ⏹.
-В свою очередь порождается задача "поедание бургеров" 🔀 ⏯, но предыдущая ("получение бургеров") завершена ⏹.
+Затем вы идёте к стойке 🔀, к исходной задаче, которая теперь завершена ⏯, забираете бургеры, благодарите и несёте их к столику. На этом шаг/задача взаимодействия со стойкой завершён ⏹. Это, в свою очередь, создаёт новую задачу — «есть бургеры» 🔀 ⏯, но предыдущая «получить бургеры» — завершена ⏹.
-### Параллельные бургеры
+### Параллельные бургеры { #parallel-burgers }
-Теперь представим, что вместо бургерной "Конкурентные бургеры" вы решили сходить в "Параллельные бургеры".
+Теперь представим, что это не «Конкурентные бургеры», а «Параллельные бургеры».
-И вот вы идёте со своей возлюбленной 😍 отведать параллельного фастфуда 🍔.
+Вы идёте со своей возлюбленной за параллельным фастфудом.
-Вы становитесь в очередь пока несколько (пусть будет 8) кассиров, которые по совместительству ещё и повары 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳, принимают заказы у посетителей перед вами.
+Вы стоите в очереди, пока несколько (скажем, 8) кассиров, которые одновременно являются поварами, принимают заказы у людей перед вами.
-При этом клиенты не отходят от стойки и ждут 🕙 получения еды, поскольку каждый
-из 8 кассиров идёт на кухню готовить бургеры 🍔, а только потом принимает следующий заказ.
+Все перед вами ждут, пока их бургеры будут готовы, не отходя от стойки, потому что каждый из 8 кассиров сразу идёт готовить бургер перед тем, как принять следующий заказ.
-Наконец настаёт ваша очередь, и вы просите два самых навороченных бургера 🍔, один для дамы сердца 😍, а другой себе.
+
-Ни о чём не жалея, расплачиваетесь 💸.
+Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя.
-И кассир уходит на кухню 👨🍳.
+Вы платите 💸.
-Вам приходится ждать перед стойкой 🕙, чтобы никто по случайности не забрал ваши бургеры 🍔, ведь никаких номерков у вас нет.
+
-Поскольку вы с возлюбленной 😍 хотите получить заказ вовремя 🕙, и следите за тем, чтобы никто не вклинился в очередь,
-у вас не получается уделять должного внимание своей даме сердца 😞.
+Кассир уходит на кухню.
-Это "синхронная" работа, вы "синхронизированы" с кассиром/поваром 👨🍳. Приходится ждать 🕙 у стойки,
-когда кассир/повар 👨🍳 закончит делать бургеры 🍔 и вручит вам заказ, иначе его случайно может забрать кто-то другой.
+Вы ждёте, стоя у стойки 🕙, чтобы никто не забрал ваши бургеры раньше вас, так как никаких номерков нет.
-Наконец кассир/повар 👨🍳 возвращается с бургерами 🍔 после невыносимо долгого ожидания 🕙 за стойкой.
+
-Вы скорее забираете заказ 🍔 и идёте с возлюбленной 😍 за столик.
+Так как вы со своей возлюбленной заняты тем, чтобы никто не встал перед вами и не забрал ваши бургеры, как только они появятся, вы не можете уделить внимание своей возлюбленной. 😞
-Там вы просто едите эти бургеры, и на этом всё 🍔 ⏹.
+Это «синхронная» работа, вы «синхронизированы» с кассиром/поваром 👨🍳. Вам нужно ждать 🕙 и находиться там в точный момент, когда кассир/повар 👨🍳 закончит бургеры и вручит их вам, иначе их может забрать кто-то другой.
-Вам не особо удалось пообщаться, потому что большую часть времени 🕙 пришлось провести у кассы 😞.
+
----
+Затем ваш кассир/повар 👨🍳 наконец возвращается с вашими бургерами, после долгого ожидания 🕙 у стойки.
-В описанном сценарии вы компьютер / программа 🤖 с двумя исполнителями (вы и ваша возлюбленная 😍),
-на протяжении долгого времени 🕙 вы оба уделяете всё внимание ⏯ задаче "ждать на кассе".
+
-В этом ресторане быстрого питания 8 исполнителей (кассиров/поваров) 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳.
-Хотя в бургерной конкурентного типа было всего два (один кассир и один повар) 💁 👨🍳.
+Вы берёте бургеры и идёте со своей возлюбленной к столику.
-Несмотря на обилие работников, опыт в итоге получился не из лучших 😞.
+Вы просто их съедаете — и всё. ⏹
+
+
+
+Разговоров и флирта было немного, потому что большую часть времени вы ждали 🕙 у стойки. 😞
+
+/// info | Информация
+
+Прекрасные иллюстрации от Ketrina Thompson. 🎨
+
+///
---
-Так бы выглядел аналог истории про бургерную 🍔 в "параллельном" мире.
+В этом сценарии «параллельных бургеров» вы — компьютер/программа 🤖 с двумя процессорами (вы и ваша возлюбленная), оба ждут 🕙 и уделяют внимание ⏯ тому, чтобы «ждать у стойки» 🕙 долгое время.
+
+В ресторане 8 процессоров (кассиров/поваров). Тогда как в «конкурентных бургерах» могло быть только 2 (один кассир и один повар).
-Вот более реалистичный пример. Представьте себе банк.
+И всё же финальный опыт — не самый лучший. 😞
-До недавних пор в большинстве банков было несколько кассиров 👨💼👨💼👨💼👨💼 и длинные очереди 🕙🕙🕙🕙🕙🕙🕙🕙.
+---
-Каждый кассир обслуживал одного клиента, потом следующего 👨💼⏯.
+Это была параллельная версия истории про бургеры. 🍔
-Нужно было долгое время 🕙 стоять перед окошком вместе со всеми, иначе пропустишь свою очередь.
+Для более «жизненного» примера представьте банк.
-Сомневаюсь, что у вас бы возникло желание прийти с возлюбленной 😍 в банк 🏦 оплачивать налоги.
+До недавнего времени в большинстве банков было несколько кассиров 👨💼👨💼👨💼👨💼 и длинная очередь 🕙🕙🕙🕙🕙🕙🕙🕙.
-### Выводы о бургерах
+Все кассиры делают всю работу с одним клиентом за другим 👨💼⏯.
-В нашей истории про поход в фастфуд за бургерами приходится много ждать 🕙,
-поэтому имеет смысл организовать конкурентную систему ⏸🔀⏯.
+И вам приходится долго 🕙 стоять в очереди, иначе вы потеряете свою очередь.
-И то же самое с большинством веб-приложений.
+Вы вряд ли захотите взять свою возлюбленную 😍 с собой, чтобы заняться делами в банке 🏦.
-Пользователей очень много, но ваш сервер всё равно вынужден ждать 🕙 запросы по их слабому интернет-соединению.
+### Вывод про бургеры { #burger-conclusion }
-Потом снова ждать 🕙, пока вернётся ответ.
+В этом сценарии «фастфуда с вашей возлюбленной», так как много ожидания 🕙, гораздо логичнее иметь конкурентную систему ⏸🔀⏯.
-
-Это ожидание 🕙 измеряется микросекундами, но если всё сложить, то набегает довольно много времени.
+Так обстоит дело и с большинством веб-приложений.
-Вот почему есть смысл использовать асинхронное ⏸🔀⏯ программирование при построении веб-API.
+Очень много пользователей, но ваш сервер ждёт 🕙, пока их не самое хорошее соединение отправит их запросы.
-Большинство популярных фреймворков (включая Flask и Django) создавались
-до появления в Python новых возможностей асинхронного программирования. Поэтому
-их можно разворачивать с поддержкой параллельного исполнения или асинхронного
-программирования старого типа, которое не настолько эффективно.
+А затем снова ждёт 🕙, пока отправятся ответы.
-При том, что основная спецификация асинхронного взаимодействия Python с веб-сервером
-(ASGI)
-была разработана командой Django для внедрения поддержки веб-сокетов.
+Это «ожидание» 🕙 измеряется микросекундами, но если всё сложить, то в сумме получается много ожидания.
-Именно асинхронность сделала NodeJS таким популярным (несмотря на то, что он не параллельный),
-и в этом преимущество Go как языка программирования.
+Вот почему асинхронный ⏸🔀⏯ код очень уместен для веб-API.
-И тот же уровень производительности даёт **FastAPI**.
+Именно такая асинхронность сделала NodeJS популярным (хотя NodeJS — не параллельный), и это сильная сторона Go как языка программирования.
-Поскольку можно использовать преимущества параллелизма и асинхронности вместе,
-вы получаете производительность лучше, чем у большинства протестированных NodeJS фреймворков
-и на уровне с Go, который является компилируемым языком близким к C (всё благодаря Starlette).
+Того же уровня производительности вы получаете с **FastAPI**.
-### Получается, конкурентность лучше параллелизма?
+А так как можно одновременно использовать параллелизм и асинхронность, вы получаете производительность выше, чем у большинства протестированных фреймворков на NodeJS и на уровне Go, который — компилируемый язык, ближе к C (всё благодаря Starlette).
-Нет! Мораль истории совсем не в этом.
+### Конкурентность лучше параллелизма? { #is-concurrency-better-than-parallelism }
-Конкурентность отличается от параллелизма. Она лучше в **конкретных** случаях, где много времени приходится на ожидание.
-Вот почему она зачастую лучше параллелизма при разработке веб-приложений. Но это не значит, что конкурентность лучше в любых сценариях.
+Нет! Мораль истории не в этом.
-Давайте посмотрим с другой стороны, представьте такую картину:
+Конкурентность отличается от параллелизма. И она лучше в **конкретных** сценариях, где много ожидания. Поэтому при разработке веб-приложений она обычно намного лучше параллелизма. Но не во всём.
-> Вам нужно убраться в большом грязном доме.
+Чтобы уравновесить это, представьте такую короткую историю:
+
+> Вам нужно убрать большой грязный дом.
*Да, это вся история*.
---
-Тут не нужно нигде ждать 🕙, просто есть куча работы в разных частях дома.
+Здесь нигде нет ожидания 🕙, просто очень много работы в разных местах дома.
-Можно организовать очередь как в примере с бургерами, сначала гостиная, потом кухня,
-но это ни на что не повлияет, поскольку вы нигде не ждёте 🕙, а просто трёте да моете.
+Можно организовать «очереди» как в примере с бургерами — сначала гостиная, потом кухня, — но так как вы ничего не ждёте 🕙, а просто убираете и убираете, очереди ни на что не повлияют.
-И понадобится одинаковое количество времени с очередью (конкурентностью) и без неё,
-и работы будет сделано тоже одинаковое количество.
+На завершение уйдёт одинаковое время — с очередями (конкурентностью) и без них — и объём выполненной работы будет одинаковым.
-Однако в случае, если бы вы могли привести 8 бывших кассиров/поваров, а ныне уборщиков 👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳👩🍳👨🍳,
-и каждый из них (вместе с вами) взялся бы за свой участок дома,
-с такой помощью вы бы закончили намного быстрее, делая всю работу **параллельно**.
+Но в этом случае, если бы вы могли привести 8 бывших кассиров/поваров, а теперь — уборщиков, и каждый из них (плюс вы) взял бы свою зону дома для уборки, вы могли бы сделать всю работу **параллельно**, с дополнительной помощью, и завершить гораздо быстрее.
-В описанном сценарии каждый уборщик (включая вас) был бы исполнителем, занятым на своём участке работы.
+В этом сценарии каждый уборщик (включая вас) был бы процессором, выполняющим свою часть работы.
-И поскольку большую часть времени выполнения занимает реальная работа (а не ожидание),
-а работу в компьютере делает ЦП,
-такие задачи называют ограниченными производительностью процессора.
+И так как основное время выполнения уходит на реальную работу (а не ожидание), а работу в компьютере выполняет CPU, такие задачи называют «ограниченными процессором» (CPU bound).
---
-Ограничение по процессору проявляется в операциях, где требуется выполнять сложные математические вычисления.
+Типичные примеры CPU-bound операций — те, которые требуют сложной математической обработки.
Например:
-* Обработка **звука** или **изображений**.
-* **Компьютерное зрение**: изображение состоит из миллионов пикселей, в каждом пикселе 3 составляющих цвета,
-обработка обычно требует проведения расчётов по всем пикселям сразу.
-* **Машинное обучение**: здесь обычно требуется умножение "матриц" и "векторов".
-Представьте гигантскую таблицу с числами в Экселе, и все их надо одновременно перемножить.
-* **Глубокое обучение**: это область *машинного обучения*, поэтому сюда подходит то же описание.
-Просто у вас будет не одна таблица в Экселе, а множество. В ряде случаев используется
-специальный процессор для создания и / или использования построенных таким образом моделей.
+* Обработка **аудио** или **изображений**.
+* **Компьютерное зрение**: изображение состоит из миллионов пикселей, каждый пиксель имеет 3 значения/цвета; обычно требуется вычислить что-то для всех этих пикселей одновременно.
+* **Машинное обучение**: обычно требует множества умножений «матриц» и «векторов». Представьте огромную таблицу с числами и умножение всех этих чисел «одновременно».
+* **Глубокое обучение**: это подполе Машинного обучения, так что всё вышесказанное применимо. Просто это не одна таблица чисел, а их огромный набор, и во многих случаях вы используете специальный процессор, чтобы строить и/или использовать такие модели.
-### Конкурентность + параллелизм: Веб + машинное обучение
+### Конкурентность + параллелизм: Веб + Машинное обучение { #concurrency-parallelism-web-machine-learning }
-**FastAPI** предоставляет возможности конкуретного программирования,
-которое очень распространено в веб-разработке (именно этим славится NodeJS).
+С **FastAPI** вы можете использовать преимущества конкурентности, что очень распространено в веб-разработке (это та же основная «фишка» NodeJS).
-Кроме того вы сможете использовать все преимущества параллелизма и
-многопроцессорности (когда несколько процессов работают параллельно),
-если рабочая нагрузка предполагает **ограничение по процессору**,
-как, например, в системах машинного обучения.
+Но вы также можете использовать выгоды параллелизма и многопроцессности (когда несколько процессов работают параллельно) для рабочих нагрузок, **ограниченных процессором** (CPU bound), как в системах Машинного обучения.
-Необходимо также отметить, что Python является главным языком в области
-**дата-сайенс**,
-машинного обучения и, особенно, глубокого обучения. Всё это делает FastAPI
-отличным вариантом (среди многих других) для разработки веб-API и приложений
-в области дата-сайенс / машинного обучения.
+Плюс к этому простой факт, что Python — основной язык для **Data Science**, Машинного обучения и особенно Глубокого обучения, делает FastAPI очень хорошим выбором для веб-API и приложений в области Data Science / Машинного обучения (среди многих других).
-Как добиться такого параллелизма в эксплуатации описано в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}.
+Как добиться такого параллелизма в продакшн, см. раздел [Развёртывание](deployment/index.md){.internal-link target=_blank}.
-## `async` и `await`
+## `async` и `await` { #async-and-await }
-В современных версиях Python разработка асинхронного кода реализована очень интуитивно.
-Он выглядит как обычный "последовательный" код и самостоятельно выполняет "ожидание", когда это необходимо.
+В современных версиях Python есть очень интуитивный способ определять асинхронный код. Это делает его похожим на обычный «последовательный» код, а «ожидание» выполняется за вас в нужные моменты.
-Если некая операция требует ожидания перед тем, как вернуть результат, и
-поддерживает современные возможности Python, код можно написать следующим образом:
+Когда есть операция, которой нужно подождать перед тем, как вернуть результат, и она поддерживает эти новые возможности Python, вы можете написать так:
```Python
burgers = await get_burgers(2)
```
-Главное здесь слово `await`. Оно сообщает интерпретатору, что необходимо дождаться ⏸
-пока `get_burgers(2)` закончит свои дела 🕙, и только после этого сохранить результат в `burgers`.
-Зная это, Python может пока переключиться на выполнение других задач 🔀 ⏯
-(например получение следующего запроса).
+Ключ здесь — `await`. Он говорит Python, что нужно подождать ⏸, пока `get_burgers(2)` закончит своё дело 🕙, прежде чем сохранять результат в `burgers`. Благодаря этому Python будет знать, что за это время можно заняться чем-то ещё 🔀 ⏯ (например, принять другой запрос).
-Чтобы ключевое слово `await` сработало, оно должно находиться внутри функции,
-которая поддерживает асинхронность. Для этого вам просто нужно объявить её как `async def`:
+Чтобы `await` работал, он должен находиться внутри функции, которая поддерживает такую асинхронность. Для этого просто объявите её с `async def`:
```Python hl_lines="1"
async def get_burgers(number: int):
- # Готовим бургеры по специальному асинхронному рецепту
+ # Сделать что-то асинхронное, чтобы приготовить бургеры
return burgers
```
@@ -355,26 +325,22 @@ async def get_burgers(number: int):
```Python hl_lines="2"
# Это не асинхронный код
def get_sequential_burgers(number: int):
- # Готовим бургеры последовательно по шагам
+ # Сделать что-то последовательное, чтобы приготовить бургеры
return burgers
```
-Объявление `async def` указывает интерпретатору, что внутри этой функции
-следует ожидать выражений `await`, и что можно поставить выполнение такой функции на "паузу" ⏸ и
-переключиться на другие задачи 🔀, с тем чтобы вернуться сюда позже.
+С `async def` Python знает, что внутри этой функции нужно учитывать выражения `await` и что выполнение такой функции можно «приостанавливать» ⏸ и идти делать что-то ещё 🔀, чтобы потом вернуться.
-Если вы хотите вызвать функцию с `async def`, вам нужно "ожидать" её.
-Поэтому такое не сработает:
+Когда вы хотите вызвать функцию, объявленную с `async def`, нужно её «ожидать». Поэтому вот так не сработает:
```Python
-# Это не заработает, поскольку get_burgers объявлена с использованием async def
+# Это не сработает, потому что get_burgers определена с: async def
burgers = get_burgers(2)
```
---
-Если сторонняя библиотека требует вызывать её с ключевым словом `await`,
-необходимо писать *функции обработки пути* с использованием `async def`, например:
+Итак, если вы используете библиотеку, которую можно вызывать с `await`, вам нужно создать *функцию-обработчик пути*, которая её использует, с `async def`, например:
```Python hl_lines="2-3"
@app.get('/burgers')
@@ -383,129 +349,96 @@ async def read_burgers():
return burgers
```
-### Технические подробности
+### Более технические подробности { #more-technical-details }
+
+Вы могли заметить, что `await` можно использовать только внутри функций, определённых с `async def`.
-Как вы могли заметить, `await` может применяться только в функциях, объявленных с использованием `async def`.
+Но при этом функции, определённые с `async def`, нужно «ожидать». Значит, функции с `async def` тоже можно вызывать только из функций, определённых с `async def`.
-
-Но выполнение такой функции необходимо "ожидать" с помощью `await`.
-Это означает, что её можно вызвать только из другой функции, которая тоже объявлена с `async def`.
+Так что же с «яйцом и курицей» — как вызвать первую `async` функцию?
-Но как же тогда появилась первая курица? В смысле... как нам вызвать первую асинхронную функцию?
+Если вы работаете с **FastAPI**, вам не о чем беспокоиться, потому что этой «первой» функцией будет ваша *функция-обработчик пути*, а FastAPI знает, как сделать всё правильно.
-При работе с **FastAPI** просто не думайте об этом, потому что "первой" функцией является ваша *функция обработки пути*,
-и дальше с этим разберётся FastAPI.
+Но если вы хотите использовать `async` / `await` без FastAPI, вы тоже можете это сделать.
-Кроме того, если хотите, вы можете использовать синтаксис `async` / `await` и без FastAPI.
+### Пишите свой асинхронный код { #write-your-own-async-code }
-### Пишите свой асинхронный код
+Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми и со стандартной библиотекой Python asyncio, и с Trio.
-Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми как со стандартной библиотекой asyncio в Python, так и с Trio.
+В частности, вы можете напрямую использовать AnyIO для продвинутых сценариев конкурентности, где в вашем коде нужны более сложные паттерны.
-В частности, вы можете напрямую использовать AnyIO в тех проектах, где требуется более сложная логика работы с конкурентностью.
+И даже если вы не используете FastAPI, вы можете писать свои асинхронные приложения с AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например, *структурную конкурентность*).
-Даже если вы не используете FastAPI, вы можете писать асинхронные приложения с помощью AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например *структурную конкурентность*).
+Я создал ещё одну библиотеку поверх AnyIO, тонкий слой, чтобы немного улучшить аннотации типов и получить более качественное **автозавершение**, **ошибки прямо в редакторе** и т.д. Там также есть дружелюбное введение и руководство, чтобы помочь вам **понять** и писать **свой собственный асинхронный код**: Asyncer. Она особенно полезна, если вам нужно **комбинировать асинхронный код с обычным** (блокирующим/синхронным) кодом.
-### Другие виды асинхронного программирования
+### Другие формы асинхронного кода { #other-forms-of-asynchronous-code }
-Стиль написания кода с `async` и `await` появился в языке Python относительно недавно.
+Такой стиль использования `async` и `await` относительно новый в языке.
-Но он сильно облегчает работу с асинхронным кодом.
+Но он сильно упрощает работу с асинхронным кодом.
-Ровно такой же синтаксис (ну или почти такой же) недавно был включён в современные версии JavaScript (в браузере и NodeJS).
+Такой же (или почти такой же) синтаксис недавно появился в современных версиях JavaScript (в браузере и NodeJS).
-До этого поддержка асинхронного кода была реализована намного сложнее, и его было труднее воспринимать.
+До этого работа с асинхронным кодом была заметно сложнее и труднее для понимания.
-В предыдущих версиях Python для этого использовались потоки или Gevent. Но такой код намного сложнее понимать, отлаживать и мысленно представлять.
+В предыдущих версиях Python можно было использовать потоки или Gevent. Но такой код гораздо сложнее понимать, отлаживать и держать в голове.
-Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели
-"обратные вызовы". Что выливалось в
-"ад обратных вызовов".
+В прежних версиях NodeJS/браузерного JavaScript вы бы использовали «callbacks» (обратные вызовы), что приводит к «callback hell» (ад обратных вызовов).
-## Сопрограммы
+## Сопрограммы { #coroutines }
-**Корути́на** (или же сопрограмма) — это крутое словечко для именования той сущности,
-которую возвращает функция `async def`. Python знает, что её можно запустить, как и обычную функцию,
-но кроме того сопрограмму можно поставить на паузу ⏸ в том месте, где встретится слово `await`.
+**Сопрограмма** (coroutine) — это просто «навороченное» слово для того, что возвращает функция `async def`. Python знает, что это похоже на функцию: её можно запустить, она когда-нибудь завершится, но её выполнение может приостанавливаться ⏸ внутри, когда встречается `await`.
-Всю функциональность асинхронного программирования с использованием `async` и `await`
-часто обобщают словом "корутины". Они аналогичны "горутинам", ключевой особенности
-языка Go.
+Часто всю функциональность использования асинхронного кода с `async` и `await` кратко называют «сопрограммами». Это сопоставимо с ключевой особенностью Go — «goroutines».
-## Заключение
+## Заключение { #conclusion }
-В самом начале была такая фраза:
+Вернёмся к той же фразе:
-> Современные версии Python поддерживают разработку так называемого
-**"асинхронного кода"** посредством написания **"сопрограмм"** с использованием
-синтаксиса **`async` и `await`**.
+> Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**.
-Теперь всё должно звучать понятнее. ✨
+Теперь это должно звучать понятнее. ✨
-На этом основана работа FastAPI (посредством Starlette), и именно это
-обеспечивает его высокую производительность.
+Именно это «движет» FastAPI (через Starlette) и обеспечивает столь впечатляющую производительность.
-## Очень технические подробности
+## Очень технические подробности { #very-technical-details }
-/// warning
+/// warning | Предупреждение
-Этот раздел читать не обязательно.
+Скорее всего, этот раздел можно пропустить.
-Здесь приводятся подробности внутреннего устройства **FastAPI**.
+Здесь — очень технические подробности о том, как **FastAPI** работает «под капотом».
-Но если вы обладаете техническими знаниями (корутины, потоки, блокировка и т. д.)
-и вам интересно, как FastAPI обрабатывает `async def` в отличие от обычных `def`,
-читайте дальше.
+Если у вас есть достаточно технических знаний (сопрограммы, потоки, блокировки и т.д.) и вам интересно, как FastAPI обрабатывает `async def` по сравнению с обычным `def`, — вперёд.
///
-### Функции обработки пути
+### Функции-обработчики пути { #path-operation-functions }
-Когда вы объявляете *функцию обработки пути* обычным образом с ключевым словом `def`
-вместо `async def`, FastAPI ожидает её выполнения, запустив функцию во внешнем
-пуле потоков, а не напрямую (это бы заблокировало сервер).
+Когда вы объявляете *функцию-обработчик пути* обычным `def` вместо `async def`, она запускается во внешнем пуле потоков, который затем «ожидается», вместо прямого вызова (прямой вызов заблокировал бы сервер).
-Если ранее вы использовали другой асинхронный фреймворк, который работает иначе,
-и привыкли объявлять простые вычислительные *функции* через `def` ради
-незначительного прироста скорости (порядка 100 наносекунд), обратите внимание,
-что с **FastAPI** вы получите противоположный эффект. В таком случае больше подходит
-`async def`, если только *функция обработки пути* не использует код, приводящий
-к блокировке I/O.
-
+Если вы пришли из другого async-фреймворка, который работает иначе, и привыкли объявлять тривиальные *функции-обработчики пути*, выполняющие только вычисления, через простой `def` ради крошечной выгоды в производительности (около 100 наносекунд), обратите внимание: в **FastAPI** эффект будет противоположным. В таких случаях лучше использовать `async def`, если только ваши *функции-обработчики пути* не используют код, выполняющий блокирующий I/O.
-
-Но в любом случае велика вероятность, что **FastAPI** [окажется быстрее](index.md#_11){.internal-link target=_blank}
-другого фреймворка (или хотя бы на уровне с ним).
+Тем не менее, в обоих случаях велика вероятность, что **FastAPI** [всё равно будет быстрее](index.md#performance){.internal-link target=_blank} (или как минимум сопоставим) с вашим предыдущим фреймворком.
-### Зависимости
+### Зависимости { #dependencies }
-То же относится к зависимостям. Если это обычная функция `def`, а не `async def`,
-она запускается во внешнем пуле потоков.
+То же относится к [зависимостям](tutorial/dependencies/index.md){.internal-link target=_blank}. Если зависимость — это обычная функция `def`, а не `async def`, она запускается во внешнем пуле потоков.
-### Подзависимости
+### Подзависимости { #sub-dependencies }
-Вы можете объявить множество ссылающихся друг на друга зависимостей и подзависимостей
-(в виде параметров при определении функции). Какие-то будут созданы с помощью `async def`,
-другие обычным образом через `def`, и такая схема вполне работоспособна. Функции,
-объявленные с помощью `def` будут запускаться на внешнем потоке (из пула),
-а не с помощью `await`.
+У вас может быть несколько зависимостей и [подзависимостей](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank}, которые требуют друг друга (в виде параметров определений функций): часть из них может быть объявлена с `async def`, а часть — обычным `def`. Всё будет работать, а те, что объявлены обычным `def`, будут вызываться во внешнем потоке (из пула), а не «ожидаться».
-### Другие служебные функции
+### Другие служебные функции { #other-utility-functions }
-Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять
-с использованием `def` или `async def`. FastAPI не будет влиять на то, как вы
-их запускаете.
+Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять обычным `def` или `async def`, и FastAPI не будет влиять на то, как вы их вызываете.
-Этим они отличаются от функций, которые FastAPI вызывает самостоятельно:
-*функции обработки пути* и зависимости.
+В отличие от функций, которые FastAPI вызывает за вас: *функции-обработчики пути* и зависимости.
-Если служебная функция объявлена с помощью `def`, она будет вызвана напрямую
-(как вы и написали в коде), а не в отдельном потоке. Если же она объявлена с
-помощью `async def`, её вызов должен осуществляться с ожиданием через `await`.
+Если служебная функция — обычная функция с `def`, она будет вызвана напрямую (как вы и пишете в коде), не в пуле потоков; если функция объявлена с `async def`, тогда при её вызове в вашем коде вы должны использовать `await`.
---
-
-Ещё раз повторим, что все эти технические подробности полезны, только если вы специально их искали.
+Снова: это очень технические подробности, полезные, вероятно, только если вы целенаправленно их ищете.
-В противном случае просто ознакомьтесь с основными принципами в разделе выше: Нет времени?.
+Иначе вам достаточно руководствоваться рекомендациями из раздела выше: Нет времени?.
diff --git a/docs/ru/docs/benchmarks.md b/docs/ru/docs/benchmarks.md
index 259dca8e6..612b39f70 100644
--- a/docs/ru/docs/benchmarks.md
+++ b/docs/ru/docs/benchmarks.md
@@ -1,37 +1,34 @@
-# Замеры производительности
+# Бенчмарки (тесты производительности) { #benchmarks }
-Независимые тесты производительности приложений от TechEmpower показывают, что **FastAPI** под управлением Uvicorn один из самых быстрых Python-фреймворков и уступает только Starlette и Uvicorn (которые используются в FastAPI). (*)
+Независимые бенчмарки TechEmpower показывают, что приложения **FastAPI** под управлением Uvicorn — одни из самых быстрых Python‑фреймворков, уступающие только Starlette и самому Uvicorn (используются внутри FastAPI).
-Но при просмотре и сравнении замеров производительности следует иметь в виду нижеописанное.
+Но при просмотре бенчмарков и сравнений следует иметь в виду следующее.
-## Замеры производительности и скорости
+## Бенчмарки и скорость { #benchmarks-and-speed }
-В подобных тестах часто можно увидеть, что инструменты разного типа сравнивают друг с другом, как аналогичные.
+При проверке бенчмарков часто можно увидеть, что инструменты разных типов сравнивают как эквивалентные.
-В частности, сравнивают вместе Uvicorn, Starlette и FastAPI (среди многих других инструментов).
+В частности, часто сравнивают вместе Uvicorn, Starlette и FastAPI (среди многих других инструментов).
-Чем проще проблема, которую решает инструмент, тем выше его производительность. И большинство тестов не проверяют дополнительные функции, предоставляемые инструментом.
+Чем проще задача, которую решает инструмент, тем выше его производительность. И большинство бенчмарков не тестируют дополнительные возможности, предоставляемые инструментом.
-Иерархия инструментов имеет следующий вид:
+Иерархия выглядит так:
* **Uvicorn**: ASGI-сервер
- * **Starlette** (использует Uvicorn): веб-микрофреймворк
- * **FastAPI** (использует Starlette): API-микрофреймворк с дополнительными функциями для создания API, с валидацией данных и т.д.
+ * **Starlette**: (использует Uvicorn) веб-микрофреймворк
+ * **FastAPI**: (использует Starlette) API-микрофреймворк с рядом дополнительных возможностей для создания API, включая валидацию данных и т. п.
* **Uvicorn**:
- * Будет иметь наилучшую производительность, так как не имеет большого количества дополнительного кода, кроме самого сервера.
- * Вы не будете писать приложение на Uvicorn напрямую. Это означало бы, что Ваш код должен включать как минимум весь
- код, предоставляемый Starlette (или **FastAPI**). И если Вы так сделаете, то в конечном итоге Ваше приложение будет иметь те же накладные расходы, что и при использовании фреймворка, минимизирующего код Вашего приложения и Ваши ошибки.
- * Uvicorn подлежит сравнению с Daphne, Hypercorn, uWSGI и другими веб-серверами.
-
+ * Будет иметь наилучшую производительность, так как помимо самого сервера у него немного дополнительного кода.
+ * Вы не будете писать приложение непосредственно на Uvicorn. Это означало бы, что Ваш код должен включать как минимум весь код, предоставляемый Starlette (или **FastAPI**). И если Вы так сделаете, то в конечном итоге Ваше приложение будет иметь те же накладные расходы, что и при использовании фреймворка, минимизирующего код Вашего приложения и Ваши ошибки.
+ * Если Вы сравниваете Uvicorn, сравнивайте его с Daphne, Hypercorn, uWSGI и т. д. — серверами приложений.
* **Starlette**:
- * Будет уступать Uvicorn по производительности. Фактически Starlette управляется Uvicorn и из-за выполнения большего количества кода он не может быть быстрее, чем Uvicorn.
- * Зато он предоставляет Вам инструменты для создания простых веб-приложений с обработкой маршрутов URL и т.д.
- * Starlette следует сравнивать с Sanic, Flask, Django и другими веб-фреймворками (или микрофреймворками).
-
+ * Будет на следующем месте по производительности после Uvicorn. Фактически Starlette запускается под управлением Uvicorn, поэтому он может быть только «медленнее» Uvicorn из‑за выполнения большего объёма кода.
+ * Зато он предоставляет Вам инструменты для создания простых веб‑приложений с маршрутизацией по путям и т. п.
+ * Если Вы сравниваете Starlette, сравнивайте его с Sanic, Flask, Django и т. д. — веб‑фреймворками (или микрофреймворками).
* **FastAPI**:
- * Так же как Starlette использует Uvicorn и не может быть быстрее него, **FastAPI** использует Starlette, то есть он не может быть быстрее Starlette.
- * FastAPI предоставляет больше возможностей поверх Starlette, которые наверняка Вам понадобятся при создании API, такие как проверка данных и сериализация. В довесок Вы ещё и получаете автоматическую документацию (автоматическая документация даже не увеличивает накладные расходы при работе приложения, так как она создается при запуске).
- * Если Вы не используете FastAPI, а используете Starlette напрямую (или другой инструмент вроде Sanic, Flask, Responder и т.д.), Вам пришлось бы самостоятельно реализовать валидацию и сериализацию данных. То есть, в итоге, Ваше приложение имело бы такие же накладные расходы, как если бы оно было создано с использованием FastAPI. И во многих случаях валидация и сериализация данных представляют собой самый большой объём кода, написанного в приложениях.
- * Таким образом, используя FastAPI Вы потратите меньше времени на разработку, уменьшите количество ошибок, строк кода и, вероятно, получите ту же производительность (или лучше), как и если бы не использовали его (поскольку Вам пришлось бы реализовать все его возможности в своем коде).
- * FastAPI должно сравнивать с фреймворками веб-приложений (или наборами инструментов), которые обеспечивают валидацию и сериализацию данных, а также предоставляют автоматическую документацию, такими как Flask-apispec, NestJS, Molten и им подобные.
+ * Точно так же, как Starlette использует Uvicorn и не может быть быстрее него, **FastAPI** использует Starlette, поэтому не может быть быстрее его.
+ * FastAPI предоставляет больше возможностей поверх Starlette — те, которые почти всегда нужны при создании API, такие как валидация и сериализация данных. В довесок Вы ещё и получаете автоматическую документацию (автоматическая документация даже не увеличивает накладные расходы при работе приложения, так как она создаётся при запуске).
+ * Если бы Вы не использовали FastAPI, а использовали Starlette напрямую (или другой инструмент вроде Sanic, Flask, Responder и т. д.), Вам пришлось бы самостоятельно реализовать валидацию и сериализацию данных. То есть, в итоге, Ваше приложение имело бы такие же накладные расходы, как если бы оно было создано с использованием FastAPI. И во многих случаях валидация и сериализация данных представляют собой самый большой объём кода, написанного в приложениях.
+ * Таким образом, используя FastAPI, Вы экономите время разработки, уменьшаете количество ошибок, строк кода и, вероятно, получите ту же производительность (или лучше), как и если бы не использовали его (поскольку Вам пришлось бы реализовать все его возможности в своём коде).
+ * Если Вы сравниваете FastAPI, сравнивайте его с фреймворком веб‑приложений (или набором инструментов), который обеспечивает валидацию данных, сериализацию и документацию, такими как Flask-apispec, NestJS, Molten и им подобные. Фреймворки с интегрированной автоматической валидацией данных, сериализацией и документацией.
diff --git a/docs/ru/docs/deployment/cloud.md b/docs/ru/docs/deployment/cloud.md
new file mode 100644
index 000000000..955db2a15
--- /dev/null
+++ b/docs/ru/docs/deployment/cloud.md
@@ -0,0 +1,24 @@
+# Развертывание FastAPI у облачных провайдеров { #deploy-fastapi-on-cloud-providers }
+
+Вы можете использовать практически любого облачного провайдера, чтобы развернуть свое приложение на FastAPI.
+
+В большинстве случаев у основных облачных провайдеров есть руководства по развертыванию FastAPI на их платформе.
+
+## FastAPI Cloud { #fastapi-cloud }
+
+**FastAPI Cloud** создан тем же автором и командой, стоящими за **FastAPI**.
+
+Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями.
+
+Он переносит тот же **опыт разработчика** создания приложений с FastAPI на их **развертывание** в облаке. 🎉
+
+FastAPI Cloud — основной спонсор и источник финансирования для open source проектов *FastAPI and friends*. ✨
+
+## Облачные провайдеры — спонсоры { #cloud-providers-sponsors }
+
+Некоторые другие облачные провайдеры ✨ [**спонсируют FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ тоже. 🙇
+
+Возможно, вы захотите попробовать их сервисы и воспользоваться их руководствами:
+
+* Render
+* Railway
diff --git a/docs/ru/docs/deployment/concepts.md b/docs/ru/docs/deployment/concepts.md
index acfa1f4fe..207d1604d 100644
--- a/docs/ru/docs/deployment/concepts.md
+++ b/docs/ru/docs/deployment/concepts.md
@@ -1,323 +1,321 @@
-# Концепции развёртывания
+# Концепции развёртывания { #deployments-concepts }
-Существует несколько концепций, применяемых для развёртывания приложений **FastAPI**, равно как и для любых других типов веб-приложений, среди которых вы можете выбрать **наиболее подходящий** способ.
+При развёртывании приложения **FastAPI** (и вообще любого веб‑API) есть несколько концепций, о которых стоит думать — с их помощью можно выбрать **наиболее подходящий** способ **развёртывания вашего приложения**.
-Самые важные из них:
+Некоторые из важных концепций:
-* Использование более безопасного протокола HTTPS
-* Настройки запуска приложения
-* Перезагрузка приложения
-* Запуск нескольких экземпляров приложения
-* Управление памятью
-* Использование перечисленных функций перед запуском приложения.
+* Безопасность — HTTPS
+* Запуск при старте
+* Перезапуски
+* Репликация (количество запущенных процессов)
+* Память
+* Предварительные шаги перед запуском
-Рассмотрим ниже влияние каждого из них на процесс **развёртывания**.
+Посмотрим, как они влияют на **развёртывания**.
-Наша конечная цель - **обслуживать клиентов вашего API безопасно** и **бесперебойно**, с максимально эффективным использованием **вычислительных ресурсов** (например, удалённых серверов/виртуальных машин). 🚀
+В конечном итоге цель — **обслуживать клиентов вашего API** безопасно, **избегать перебоев** и максимально эффективно использовать **вычислительные ресурсы** (например, удалённые серверы/виртуальные машины). 🚀
-Здесь я немного расскажу Вам об этих **концепциях** и надеюсь, что у вас сложится **интуитивное понимание**, какой способ выбрать при развертывании вашего API в различных окружениях, возможно, даже **ещё не существующих**.
+Здесь я немного расскажу о этих **концепциях**, чтобы у вас появилась **интуиция**, как развёртывать ваш API в разных окружениях, возможно даже в **будущих**, которых ещё не существует.
-Ознакомившись с этими концепциями, вы сможете **оценить и выбрать** лучший способ развёртывании **Вашего API**.
+Учитывая эти концепции, вы сможете **оценить и спроектировать** лучший способ развёртывания **своих API**.
-В последующих главах я предоставлю Вам **конкретные рецепты** развёртывания приложения FastAPI.
+В следующих главах я дам более **конкретные рецепты** по развёртыванию приложений FastAPI.
-А сейчас давайте остановимся на важных **идеях этих концепций**. Эти идеи можно также применить и к другим типам веб-приложений. 💡
+А пока давайте разберём важные **идеи**. Эти концепции применимы и к другим типам веб‑API. 💡
-## Использование более безопасного протокола HTTPS
+## Безопасность — HTTPS { #security-https }
-В [предыдущей главе об HTTPS](https.md){.internal-link target=_blank} мы рассмотрели, как HTTPS обеспечивает шифрование для вашего API.
+В [предыдущей главе про HTTPS](https.md){.internal-link target=_blank} мы разобрались, как HTTPS обеспечивает шифрование для вашего API.
-Также мы заметили, что обычно для работы с HTTPS вашему приложению нужен **дополнительный** компонент - **прокси-сервер завершения работы TLS**.
+Также мы увидели, что HTTPS обычно обеспечивает компонент, **внешний** по отношению к серверу вашего приложения — **TLS Termination Proxy**.
-И если прокси-сервер не умеет сам **обновлять сертификаты HTTPS**, то нужен ещё один компонент для этого действия.
+И должен быть компонент, отвечающий за **обновление HTTPS‑сертификатов** — это может быть тот же самый компонент или отдельный.
-### Примеры инструментов для работы с HTTPS
+### Примеры инструментов для HTTPS { #example-tools-for-https }
-Вот некоторые инструменты, которые вы можете применять как прокси-серверы:
+Некоторые инструменты, которые можно использовать как TLS Termination Proxy:
* Traefik
- * С автоматическим обновлением сертификатов ✨
+ * Автоматически обновляет сертификаты ✨
* Caddy
- * С автоматическим обновлением сертификатов ✨
+ * Автоматически обновляет сертификаты ✨
* Nginx
- * С дополнительным компонентом типа Certbot для обновления сертификатов
+ * С внешним компонентом (например, Certbot) для обновления сертификатов
* HAProxy
- * С дополнительным компонентом типа Certbot для обновления сертификатов
-* Kubernetes с Ingress Controller похожим на Nginx
- * С дополнительным компонентом типа cert-manager для обновления сертификатов
-* Использование услуг облачного провайдера (читайте ниже 👇)
+ * С внешним компонентом (например, Certbot) для обновления сертификатов
+* Kubernetes с Ingress Controller (например, Nginx)
+ * С внешним компонентом (например, cert-manager) для обновления сертификатов
+* Обрабатывается внутри облачного провайдера как часть его услуг (см. ниже 👇)
-В последнем варианте вы можете воспользоваться услугами **облачного сервиса**, который сделает большую часть работы, включая настройку HTTPS. Это может наложить дополнительные ограничения или потребовать дополнительную плату и т.п. Зато Вам не понадобится самостоятельно заниматься настройками прокси-сервера.
+Другой вариант — использовать **облачный сервис**, который возьмёт на себя больше задач, включая настройку HTTPS. Там могут быть ограничения или дополнительная стоимость и т.п., но в таком случае вам не придётся самим настраивать TLS Termination Proxy.
-В дальнейшем я покажу Вам некоторые конкретные примеры их применения.
+В следующих главах я покажу конкретные примеры.
---
-Следующие концепции рассматривают применение программы, запускающей Ваш API (такой как Uvicorn).
+Далее рассмотрим концепции, связанные с программой, которая запускает ваш реальный API (например, Uvicorn).
-## Программа и процесс
+## Программа и процесс { #program-and-process }
-Мы часто будем встречать слова **процесс** и **программа**, потому следует уяснить отличия между ними.
+Мы часто будем говорить о работающем "**процессе**", поэтому полезно чётко понимать, что это значит и чем отличается от "**программы**".
-### Что такое программа
+### Что такое программа { #what-is-a-program }
-Термином **программа** обычно описывают множество вещей:
+Словом **программа** обычно называют разные вещи:
-* **Код**, который вы написали, в нашем случае **Python-файлы**.
-* **Файл**, который может быть **исполнен** операционной системой, например `python`, `python.exe` или `uvicorn`.
-* Конкретная программа, **запущенная** операционной системой и использующая центральный процессор и память. В таком случае это также называется **процесс**.
+* **Код**, который вы пишете, то есть **Python‑файлы**.
+* **Файл**, который может быть **запущен** операционной системой, например: `python`, `python.exe` или `uvicorn`.
+* Конкретную программу в момент, когда она **работает** в операционной системе, используя CPU и память. Это также называют **процессом**.
-### Что такое процесс
+### Что такое процесс { #what-is-a-process }
-Термин **процесс** имеет более узкое толкование, подразумевая что-то, запущенное операционной системой (как в последнем пункте из вышестоящего абзаца):
+Слово **процесс** обычно используют более конкретно — только для того, что реально выполняется в операционной системе (как в последнем пункте выше):
-* Конкретная программа, **запущенная** операционной системой.
- * Это не имеет отношения к какому-либо файлу или коду, но нечто **определённое**, управляемое и **выполняемое** операционной системой.
-* Любая программа, любой код, **могут делать что-то** только когда они **выполняются**. То есть, когда являются **работающим процессом**.
-* Процесс может быть **прерван** (или "убит") Вами или вашей операционной системой. В результате чего он перестанет исполняться и **не будет продолжать делать что-либо**.
-* Каждое приложение, которое вы запустили на своём компьютере, каждая программа, каждое "окно" запускает какой-то процесс. И обычно на включенном компьютере **одновременно** запущено множество процессов.
-* И **одна программа** может запустить **несколько параллельных процессов**.
+* Конкретная программа в момент, когда она **запущена** в операционной системе.
+ * Речь не о файле и не о коде, а **конкретно** о том, что **исполняется** и управляется операционной системой.
+* Любая программа, любой код **могут что‑то делать** только когда **исполняются**, то есть когда есть **работающий процесс**.
+* Процесс можно **завершить** (или «убить») вами или операционной системой. В этот момент он перестаёт выполняться и **больше ничего делать не может**.
+* У каждого запущенного приложения на вашем компьютере есть свой процесс; у каждой программы, у каждого окна и т.д. Обычно одновременно **работает много процессов**, пока компьютер включён.
+* Могут **одновременно** работать **несколько процессов** одной и той же **программы**.
-Если вы заглянете в "диспетчер задач" или "системный монитор" (или аналогичные инструменты) вашей операционной системы, то увидите множество работающих процессов.
+Если вы посмотрите «диспетчер задач» или «системный монитор» (или аналогичные инструменты) в вашей операционной системе, то увидите множество работающих процессов.
-Вполне вероятно, что вы увидите несколько процессов с одним и тем же названием браузерной программы (Firefox, Chrome, Edge и т. Д.). Обычно браузеры запускают один процесс на вкладку и вдобавок некоторые дополнительные процессы.
+Например, вы, скорее всего, увидите несколько процессов одного и того же браузера (Firefox, Chrome, Edge и т.д.). Обычно браузеры запускают один процесс на вкладку плюс дополнительные процессы.
---
-Теперь, когда нам известна разница между **процессом** и **программой**, давайте продолжим обсуждение развёртывания.
+Теперь, когда мы понимаем разницу между **процессом** и **программой**, продолжим разговор о развёртываниях.
-## Настройки запуска приложения
+## Запуск при старте { #running-on-startup }
-В большинстве случаев когда вы создаёте веб-приложение, то желаете, чтоб оно **работало постоянно** и непрерывно, предоставляя клиентам доступ в любое время. Хотя иногда у вас могут быть причины, чтоб оно запускалось только при определённых условиях.
+В большинстве случаев, создавая веб‑API, вы хотите, чтобы он **работал постоянно**, без перерывов, чтобы клиенты всегда могли к нему обратиться. Разве что у вас есть особые причины запускать его только при определённых условиях, но обычно вы хотите, чтобы он был постоянно запущен и **доступен**.
-### Удалённый сервер
+### На удалённом сервере { #in-a-remote-server }
-Когда вы настраиваете удалённый сервер (облачный сервер, виртуальную машину и т.п.), самое простое, что можно сделать, запустить Uvicorn (или его аналог) вручную, как вы делаете при локальной разработке.
+Когда вы настраиваете удалённый сервер (облачный сервер, виртуальную машину и т.п.), самый простой вариант — вручную использовать `fastapi run` (он использует Uvicorn) или что‑то похожее, как вы делаете при локальной разработке.
-Это рабочий способ и он полезен **во время разработки**.
+Это будет работать и полезно **во время разработки**.
-Но если вы потеряете соединение с сервером, то не сможете отслеживать - работает ли всё ещё **запущенный Вами процесс**.
+Но если соединение с сервером прервётся, **запущенный процесс**, скорее всего, завершится.
-И если сервер перезагрузится (например, после обновления или каких-то действий облачного провайдера), вы скорее всего **этого не заметите**, чтобы снова запустить процесс вручную. Вследствие этого Ваш API останется мёртвым. 😱
+А если сервер перезагрузится (например, после обновлений или миграций у облачного провайдера), вы, вероятно, **даже не заметите этого**. Из‑за этого вы не узнаете, что нужно вручную перезапустить процесс — и ваш API просто будет «мёртв». 😱
-### Автоматический запуск программ
+### Автоматический запуск при старте { #run-automatically-on-startup }
-Вероятно вы захотите, чтоб Ваша серверная программа (такая, как Uvicorn) стартовала автоматически при включении сервера, без **человеческого вмешательства** и всегда могла управлять Вашим API (так как Uvicorn запускает приложение FastAPI).
+Как правило, вы захотите, чтобы серверная программа (например, Uvicorn) запускалась автоматически при старте сервера и без **участия человека**, чтобы всегда был процесс, запущенный с вашим API (например, Uvicorn, запускающий ваше приложение FastAPI).
-### Отдельная программа
+### Отдельная программа { #separate-program }
-Для этого у обычно используют отдельную программу, которая следит за тем, чтобы Ваши приложения запускались при включении сервера. Такой подход гарантирует, что другие компоненты или приложения также будут запущены, например, база данных
+Чтобы этого добиться, обычно используют **отдельную программу**, которая гарантирует запуск вашего приложения при старте. Во многих случаях она также запускает и другие компоненты/приложения, например базу данных.
-### Примеры инструментов, управляющих запуском программ
+### Примеры инструментов для запуска при старте { #example-tools-to-run-at-startup }
-Вот несколько примеров, которые могут справиться с такой задачей:
+Примеры инструментов, которые могут с этим справиться:
* Docker
* Kubernetes
* Docker Compose
-* Docker в режиме Swarm
+* Docker в режиме Swarm (Swarm Mode)
* Systemd
* Supervisor
-* Использование услуг облачного провайдера
+* Обработка внутри облачного провайдера как часть его услуг
* Прочие...
-Я покажу Вам некоторые примеры их использования в следующих главах.
+Более конкретные примеры будут в следующих главах.
-## Перезапуск
+## Перезапуски { #restarts }
-Вы, вероятно, также захотите, чтоб ваше приложение **перезапускалось**, если в нём произошёл сбой.
+Подобно тому как вы обеспечиваете запуск приложения при старте, вы, вероятно, захотите обеспечить его **перезапуск** после сбоев.
-### Мы ошибаемся
+### Мы ошибаемся { #we-make-mistakes }
-Все люди совершают **ошибки**. Программное обеспечение почти *всегда* содержит **баги** спрятавшиеся в разных местах. 🐛
+Мы, люди, постоянно совершаем **ошибки**. В программном обеспечении почти всегда есть **баги**, скрытые в разных местах. 🐛
-И мы, будучи разработчиками, продолжаем улучшать код, когда обнаруживаем в нём баги или добавляем новый функционал (возможно, добавляя при этом баги 😅).
+И мы, как разработчики, продолжаем улучшать код — находим баги и добавляем новые возможности (иногда добавляя новые баги 😅).
-### Небольшие ошибки обрабатываются автоматически
+### Небольшие ошибки обрабатываются автоматически { #small-errors-automatically-handled }
-Когда вы создаёте свои API на основе FastAPI и допускаете в коде ошибку, то FastAPI обычно остановит её распространение внутри одного запроса, при обработке которого она возникла. 🛡
+Создавая веб‑API с FastAPI, если в нашем коде возникает ошибка, FastAPI обычно «локализует» её в пределах одного запроса, который эту ошибку вызвал. 🛡
-Клиент получит ошибку **500 Internal Server Error** в ответ на свой запрос, но приложение не сломается и будет продолжать работать с последующими запросами.
+Клиент получит **500 Internal Server Error** для этого запроса, но приложение продолжит работать для последующих запросов, а не «упадёт» целиком.
-### Большие ошибки - Падение приложений
+### Большие ошибки — падения { #bigger-errors-crashes }
-Тем не менее, может случиться так, что ошибка вызовет **сбой всего приложения** или даже сбой в Uvicorn, а то и в самом Python. 💥
+Тем не менее возможны случаи, когда код **роняет всё приложение**, приводя к сбою Uvicorn и Python. 💥
-Но мы всё ещё хотим, чтобы приложение **продолжало работать** несмотря на эту единственную ошибку, обрабатывая, как минимум, запросы к *операциям пути* не имеющим ошибок.
+И вы, скорее всего, не захотите, чтобы приложение оставалось «мёртвым» из‑за ошибки в одном месте — вы захотите, чтобы оно **продолжало работать** хотя бы для *операций пути*, которые не сломаны.
-### Перезапуск после падения
+### Перезапуск после падения { #restart-after-crash }
-Для случаев, когда ошибки приводят к сбою в запущенном **процессе**, Вам понадобится добавить компонент, который **перезапустит** процесс хотя бы пару раз...
+В случаях действительно серьёзных ошибок, которые роняют работающий **процесс**, вам понадобится внешний компонент, отвечающий за **перезапуск** процесса, как минимум пару раз...
-/// tip | Заметка
+/// tip | Совет
-... Если приложение падает сразу же после запуска, вероятно бесполезно его бесконечно перезапускать. Но полагаю, вы заметите такое поведение во время разработки или, по крайней мере, сразу после развёртывания.
+...Хотя если приложение **падает сразу же**, вероятно, нет смысла перезапускать его бесконечно. Но такие случаи вы, скорее всего, заметите во время разработки или как минимум сразу после развёртывания.
-Так что давайте сосредоточимся на конкретных случаях, когда приложение может полностью выйти из строя, но всё ещё есть смысл его запустить заново.
+Давайте сосредоточимся на основных сценариях, когда в каких‑то конкретных ситуациях **в будущем** приложение может падать целиком, и при этом имеет смысл его перезапускать.
///
-Возможно вы захотите, чтоб был некий **внешний компонент**, ответственный за перезапуск вашего приложения даже если уже не работает Uvicorn или Python. То есть ничего из того, что написано в вашем коде внутри приложения, не может быть выполнено в принципе.
+Скорее всего, вы захотите, чтобы перезапуском вашего приложения занимался **внешний компонент**, потому что к тому моменту Uvicorn и Python уже упали, и внутри того же кода вашего приложения сделать уже ничего нельзя.
-### Примеры инструментов для автоматического перезапуска
+### Примеры инструментов для автоматического перезапуска { #example-tools-to-restart-automatically }
-В большинстве случаев инструменты **запускающие программы при старте сервера** умеют **перезапускать** эти программы.
+В большинстве случаев тот же инструмент, который **запускает программу при старте**, умеет обрабатывать и автоматические **перезапуски**.
-В качестве примера можно взять те же:
+Например, это может быть:
* Docker
* Kubernetes
* Docker Compose
-* Docker в режиме Swarm
+* Docker в режиме Swarm (Swarm Mode)
* Systemd
* Supervisor
-* Использование услуг облачного провайдера
+* Обработка внутри облачного провайдера как часть его услуг
* Прочие...
-## Запуск нескольких экземпляров приложения (Репликация) - Процессы и память
+## Репликация — процессы и память { #replication-processes-and-memory }
-Приложение FastAPI, управляемое серверной программой (такой как Uvicorn), запускается как **один процесс** и может обслуживать множество клиентов одновременно.
+В приложении FastAPI, используя серверную программу (например, команду `fastapi`, которая запускает Uvicorn), запуск в **одном процессе** уже позволяет обслуживать нескольких клиентов одновременно.
-Но часто Вам может понадобиться несколько одновременно работающих одинаковых процессов.
+Но во многих случаях вы захотите одновременно запустить несколько процессов‑воркеров.
-### Множество процессов - Воркеры (Workers)
+### Несколько процессов — Воркеры { #multiple-processes-workers }
-Если количество Ваших клиентов больше, чем может обслужить один процесс (допустим, что виртуальная машина не слишком мощная), но при этом Вам доступно **несколько ядер процессора**, то вы можете запустить **несколько процессов** одного и того же приложения параллельно и распределить запросы между этими процессами.
+Если клиентов больше, чем способен обслужить один процесс (например, если виртуальная машина не слишком мощная), и на сервере есть **несколько ядер CPU**, вы можете запустить **несколько процессов** одного и того же приложения параллельно и распределять запросы между ними.
-**Несколько запущенных процессов** одной и той же API-программы часто называют **воркерами**.
+Когда вы запускаете **несколько процессов** одной и той же программы API, их обычно называют **воркерами**.
-### Процессы и порты́
+### Процессы‑воркеры и порты { #worker-processes-and-ports }
-Помните ли Вы, как на странице [Об HTTPS](https.md){.internal-link target=_blank} мы обсуждали, что на сервере только один процесс может слушать одну комбинацию IP-адреса и порта?
+Помните из раздела [Об HTTPS](https.md){.internal-link target=_blank}, что на сервере только один процесс может слушать конкретную комбинацию порта и IP‑адреса?
-С тех пор ничего не изменилось.
+Это по‑прежнему так.
-Соответственно, чтобы иметь возможность работать с **несколькими процессами** одновременно, должен быть **один процесс, прослушивающий порт** и затем каким-либо образом передающий данные каждому рабочему процессу.
+Поэтому, чтобы одновременно работало **несколько процессов**, должен быть **один процесс, слушающий порт**, который затем каким‑то образом передаёт коммуникацию каждому воркер‑процессу.
-### У каждого процесса своя память
+### Память на процесс { #memory-per-process }
-Работающая программа загружает в память данные, необходимые для её работы, например, переменные содержащие модели машинного обучения или большие файлы. Каждая переменная **потребляет некоторое количество оперативной памяти (RAM)** сервера.
+Когда программа загружает что‑то в память (например, модель машинного обучения в переменную или содержимое большого файла в переменную), всё это **потребляет часть памяти (RAM)** сервера.
-Обычно процессы **не делятся памятью друг с другом**. Сие означает, что каждый работающий процесс имеет свои данные, переменные и свой кусок памяти. И если для выполнения вашего кода процессу нужно много памяти, то **каждый такой же процесс** запущенный дополнительно, потребует такого же количества памяти.
+И разные процессы обычно **не делят память**. Это значит, что у каждого процесса свои переменные и своя память. Если ваш код потребляет много памяти, то **каждый процесс** будет потреблять сопоставимый объём памяти.
-### Память сервера
+### Память сервера { #server-memory }
-Допустим, что Ваш код загружает модель машинного обучения **размером 1 ГБ**. Когда вы запустите своё API как один процесс, он займёт в оперативной памяти не менее 1 ГБ. А если вы запустите **4 таких же процесса** (4 воркера), то каждый из них займёт 1 ГБ оперативной памяти. В результате вашему API потребуется **4 ГБ оперативной памяти (RAM)**.
+Например, если ваш код загружает модель Машинного обучения размером **1 ГБ**, то при запуске одного процесса с вашим API он будет использовать как минимум 1 ГБ RAM. А если вы запустите **4 процесса** (4 воркера), каждый процесс будет использовать 1 ГБ RAM. Всего ваш API будет потреблять **4 ГБ RAM**.
-И если Ваш удалённый сервер или виртуальная машина располагает только 3 ГБ памяти, то попытка загрузить в неё 4 ГБ данных вызовет проблемы. 🚨
+И если у вашего удалённого сервера или виртуальной машины только 3 ГБ RAM, попытка загрузить более 4 ГБ вызовет проблемы. 🚨
-### Множество процессов - Пример
+### Несколько процессов — пример { #multiple-processes-an-example }
-В этом примере **менеджер процессов** запустит и будет управлять двумя **воркерами**.
+В этом примере есть **процесс‑менеджер**, который запускает и контролирует два **процесса‑воркера**.
-Менеджер процессов будет слушать определённый **сокет** (IP:порт) и передавать данные работающим процессам.
+Процесс‑менеджер, вероятно, будет тем, кто слушает **порт** на IP. И он будет передавать всю коммуникацию воркер‑процессам.
-Каждый из этих процессов будет запускать ваше приложение для обработки полученного **запроса** и возвращения вычисленного **ответа** и они будут использовать оперативную память.
+Эти воркеры будут запускать ваше приложение, выполнять основные вычисления для получения **запроса** и возврата **ответа**, и загружать всё, что вы кладёте в переменные, в RAM.
-Безусловно, на этом же сервере будут работать и **другие процессы**, которые не относятся к вашему приложению.
+Конечно, на той же машине помимо вашего приложения, скорее всего, будут работать и **другие процессы**.
-Интересная деталь заключается в том, что процент **использования центрального процессора (CPU)** каждым процессом может сильно меняться с течением времени, но объём занимаемой **оперативной памяти (RAM)** остаётся относительно **стабильным**.
+Интересная деталь: процент **использования CPU** каждым процессом со временем может сильно **меняться**, но **память (RAM)** обычно остаётся более‑менее **стабильной**.
-Если у вас есть API, который каждый раз выполняет сопоставимый объем вычислений, и у вас много клиентов, то **загрузка процессора**, вероятно, *также будет стабильной* (вместо того, чтобы постоянно быстро увеличиваться и уменьшаться).
+Если у вас API, который каждый раз выполняет сопоставимый объём вычислений, и у вас много клиентов, то **загрузка процессора**, вероятно, *тоже будет стабильной* (вместо того, чтобы быстро и постоянно «скакать»).
-### Примеры стратегий и инструментов для запуска нескольких экземпляров приложения
+### Примеры инструментов и стратегий репликации { #examples-of-replication-tools-and-strategies }
-Существует несколько подходов для достижения целей репликации и я расскажу Вам больше о конкретных стратегиях в следующих главах, например, когда речь пойдет о Docker и контейнерах.
+Есть несколько подходов для достижения этого, и я расскажу больше о конкретных стратегиях в следующих главах, например, говоря о Docker и контейнерах.
-Основное ограничение при этом - только **один** компонент может работать с определённым **портом публичного IP**. И должен быть способ **передачи** данных между этим компонентом и копиями **процессов/воркеров**.
+Главное ограничение: должен быть **один** компонент, который обрабатывает **порт** на **публичном IP**. И у него должен быть способ **передавать** коммуникацию реплицированным **процессам/воркерам**.
-Вот некоторые возможные комбинации и стратегии:
+Некоторые возможные комбинации и стратегии:
-* **Gunicorn** управляющий **воркерами Uvicorn**
- * Gunicorn будет выступать как **менеджер процессов**, прослушивая **IP:port**. Необходимое количество запущенных экземпляров приложения будет осуществляться посредством запуска **множества работающих процессов Uvicorn**.
-* **Uvicorn** управляющий **воркерами Uvicorn**
- * Один процесс Uvicorn будет выступать как **менеджер процессов**, прослушивая **IP:port**. Он будет запускать **множество работающих процессов Uvicorn**.
-* **Kubernetes** и аналогичные **контейнерные системы**
- * Какой-то компонент в **Kubernetes** будет слушать **IP:port**. Необходимое количество запущенных экземпляров приложения будет осуществляться посредством запуска **нескольких контейнеров**, в каждом из которых работает **один процесс Uvicorn**.
-* **Облачные сервисы**, которые позаботятся обо всём за Вас
- * Возможно, что облачный сервис умеет **управлять запуском дополнительных экземпляров приложения**. Вероятно, он потребует, чтоб вы указали - какой **процесс** или **образ** следует клонировать. Скорее всего, вы укажете **один процесс Uvicorn** и облачный сервис будет запускать его копии при необходимости.
+* **Uvicorn** с `--workers`
+ * Один **процесс‑менеджер** Uvicorn будет слушать **IP** и **порт** и запускать **несколько процессов‑воркеров Uvicorn**.
+* **Kubernetes** и другие распределённые **контейнерные системы**
+ * Некий компонент на уровне **Kubernetes** будет слушать **IP** и **порт**. Репликация достигается с помощью **нескольких контейнеров**, в каждом из которых работает **один процесс Uvicorn**.
+* **Облачные сервисы**, которые берут это на себя
+ * Облачный сервис, скорее всего, **возьмёт репликацию на себя**. Он, возможно, позволит указать **процесс для запуска** или **образ контейнера**. В любом случае это, скорее всего, будет **один процесс Uvicorn**, а сервис займётся его репликацией.
-/// tip | Заметка
+/// tip | Совет
-Если вы не знаете, что такое **контейнеры**, Docker или Kubernetes, не переживайте.
+Не беспокойтесь, если некоторые пункты про **контейнеры**, Docker или Kubernetes пока кажутся неочевидными.
-Я поведаю Вам о контейнерах, образах, Docker, Kubernetes и т.п. в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}.
+Я расскажу больше про образы контейнеров, Docker, Kubernetes и т.п. в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}.
///
-## Шаги, предшествующие запуску
+## Предварительные шаги перед запуском { #previous-steps-before-starting }
-Часто бывает, что Вам необходимо произвести какие-то подготовительные шаги **перед запуском** своего приложения.
+Во многих случаях вы захотите выполнить некоторые шаги **перед запуском** приложения.
Например, запустить **миграции базы данных**.
-Но в большинстве случаев такие действия достаточно произвести **однократно**.
+Но чаще всего эти шаги нужно выполнять только **один раз**.
-Поэтому Вам нужен будет **один процесс**, выполняющий эти **подготовительные шаги** до запуска приложения.
+Поэтому вы захотите иметь **один процесс**, который выполнит эти **предварительные шаги**, прежде чем запускать приложение.
-Также Вам нужно будет убедиться, что этот процесс выполнил подготовительные шаги *даже* если впоследствии вы запустите **несколько процессов** (несколько воркеров) самого приложения. Если бы эти шаги выполнялись в каждом **клонированном процессе**, они бы **дублировали** работу, пытаясь выполнить её **параллельно**. И если бы эта работа была бы чем-то деликатным, вроде миграции базы данных, то это может вызвать конфликты между ними.
+И вам нужно будет убедиться, что это делает один процесс **даже** если потом вы запускаете **несколько процессов** (несколько воркеров) самого приложения. Если эти шаги выполнят **несколько процессов**, они **дублируют** работу, запустив её **параллельно**, и, если речь о чём‑то деликатном (например, миграции БД), это может вызвать конфликты.
-Безусловно, возможны случаи, когда нет проблем при выполнении предварительной подготовки параллельно или несколько раз. Тогда Вам повезло, работать с ними намного проще.
+Конечно, бывают случаи, когда нет проблем, если предварительные шаги выполняются несколько раз — тогда всё проще.
-/// tip | Заметка
+/// tip | Совет
-Имейте в виду, что в некоторых случаях запуск вашего приложения **может не требовать каких-либо предварительных шагов вовсе**.
+Также учтите, что в зависимости от вашей схемы развёртывания в некоторых случаях **предварительные шаги могут вовсе не требоваться**.
-Что ж, тогда Вам не нужно беспокоиться об этом. 🤷
+Тогда об этом можно не беспокоиться. 🤷
///
-### Примеры стратегий запуска предварительных шагов
+### Примеры стратегий для предварительных шагов { #examples-of-previous-steps-strategies }
-Существует **сильная зависимость** от того, как вы **развёртываете свою систему**, запускаете программы, обрабатываете перезапуски и т.д.
+Это будет **сильно зависеть** от того, как вы **развёртываете систему**, как запускаете программы, обрабатываете перезапуски и т.д.
-Вот некоторые возможные идеи:
+Некоторые возможные идеи:
-* При использовании Kubernetes нужно предусмотреть "инициализирующий контейнер", запускаемый до контейнера с приложением.
-* Bash-скрипт, выполняющий предварительные шаги, а затем запускающий приложение.
- * При этом Вам всё ещё нужно найти способ - как запускать/перезапускать *такой* bash-скрипт, обнаруживать ошибки и т.п.
+* «Init Container» в Kubernetes, который запускается перед контейнером с приложением
+* Bash‑скрипт, который выполняет предварительные шаги, а затем запускает приложение
+ * При этом всё равно нужен способ запускать/перезапускать *этот* bash‑скрипт, обнаруживать ошибки и т.п.
-/// tip | Заметка
+/// tip | Совет
-Я приведу Вам больше конкретных примеров работы с контейнерами в главе: [FastAPI внутри контейнеров - Docker](docker.md){.internal-link target=_blank}.
+Я приведу более конкретные примеры с контейнерами в следующей главе: [FastAPI внутри контейнеров — Docker](docker.md){.internal-link target=_blank}.
///
-## Утилизация ресурсов
+## Использование ресурсов { #resource-utilization }
-Ваш сервер располагает ресурсами, которые Ваши программы могут потреблять или **утилизировать**, а именно - время работы центрального процессора и объём оперативной памяти.
+Ваш сервер(а) — это **ресурс**, который ваши программы могут потреблять или **использовать**: время вычислений на CPU и доступную оперативную память (RAM).
-Как много системных ресурсов вы предполагаете потребить/утилизировать? Если не задумываться, то можно ответить - "немного", но на самом деле Вы, вероятно, захотите использовать **максимально возможное количество**.
+Какую долю системных ресурсов вы хотите потреблять/использовать? Можно подумать «немного», но на практике вы, скорее всего, захотите потреблять **максимум без падений**.
-Если вы платите за содержание трёх серверов, но используете лишь малую часть системных ресурсов каждого из них, то вы **выбрасываете деньги на ветер**, а также **впустую тратите электроэнергию** и т.п.
+Если вы платите за 3 сервера, но используете лишь малую часть их RAM и CPU, вы, вероятно, **тратите деньги впустую** 💸 и **электроэнергию серверов** 🌎 и т.п.
-В таком случае было бы лучше обойтись двумя серверами, но более полно утилизировать их ресурсы (центральный процессор, оперативную память, жёсткий диск, сети передачи данных и т.д).
+В таком случае лучше иметь 2 сервера и использовать более высокий процент их ресурсов (CPU, память, диск, сетевую полосу и т.д.).
-С другой стороны, если вы располагаете только двумя серверами и используете **на 100% их процессоры и память**, но какой-либо процесс запросит дополнительную память, то операционная система сервера будет использовать жёсткий диск для расширения оперативной памяти (а диск работает в тысячи раз медленнее), а то вовсе **упадёт**. Или если какому-то процессу понадобится произвести вычисления, то ему придётся подождать, пока процессор освободится.
+С другой стороны, если у вас 2 сервера и вы используете **100% их CPU и RAM**, в какой‑то момент один процесс попросит больше памяти, и сервер начнёт использовать диск как «память» (что в тысячи раз медленнее) или даже **упадёт**. Или процессу понадобятся вычисления, но ему придётся ждать освобождения CPU.
-В такой ситуации лучше подключить **ещё один сервер** и перераспределить процессы между серверами, чтоб всем **хватало памяти и процессорного времени**.
+В таком случае лучше добавить **ещё один сервер** и запустить часть процессов на нём, чтобы у всех было **достаточно RAM и времени CPU**.
-Также есть вероятность, что по какой-то причине возник **всплеск** запросов к вашему API. Возможно, это был вирус, боты или другие сервисы начали пользоваться им. И для таких происшествий вы можете захотеть иметь дополнительные ресурсы.
+Также возможен **всплеск** использования вашего API: он мог «взорваться» по популярности, или какие‑то сервисы/боты начали его активно использовать. На такие случаи стоит иметь запас ресурсов.
-При настройке логики развёртываний, вы можете указать **целевое значение** утилизации ресурсов, допустим, **от 50% до 90%**. Обычно эти метрики и используют.
+Можно задать **целевое значение**, например **между 50% и 90%** использования ресурсов. Скорее всего, именно эти вещи вы будете измерять и на их основе настраивать развёртывание.
-Вы можете использовать простые инструменты, такие как `htop`, для отслеживания загрузки центрального процессора и оперативной памяти сервера, в том числе каждым процессом. Или более сложные системы мониторинга нескольких серверов.
+Можно использовать простые инструменты вроде `htop`, чтобы смотреть загрузку CPU и RAM на сервере или по процессам. Или более сложные распределённые системы мониторинга.
-## Резюме
+## Резюме { #recap }
-Вы прочитали некоторые из основных концепций, которые необходимо иметь в виду при принятии решения о развертывании приложений:
+Здесь вы прочитали о некоторых основных концепциях, которые, вероятно, стоит учитывать при выборе способа развёртывания приложения:
-* Использование более безопасного протокола HTTPS
-* Настройки запуска приложения
-* Перезагрузка приложения
-* Запуск нескольких экземпляров приложения
-* Управление памятью
-* Использование перечисленных функций перед запуском приложения.
+* Безопасность — HTTPS
+* Запуск при старте
+* Перезапуски
+* Репликация (количество запущенных процессов)
+* Память
+* Предварительные шаги перед запуском
-Осознание этих идей и того, как их применять, должно дать Вам интуитивное понимание, необходимое для принятия решений при настройке развертываний. 🤓
+Понимание этих идей и того, как их применять, даст вам интуицию, необходимую для принятия решений при настройке и доработке ваших развёртываний. 🤓
-В следующих разделах я приведу более конкретные примеры возможных стратегий, которым вы можете следовать. 🚀
+В следующих разделах я приведу более конкретные примеры возможных стратегий. 🚀
diff --git a/docs/ru/docs/deployment/docker.md b/docs/ru/docs/deployment/docker.md
index c72f67172..3937b0165 100644
--- a/docs/ru/docs/deployment/docker.md
+++ b/docs/ru/docs/deployment/docker.md
@@ -1,17 +1,17 @@
-# FastAPI и Docker-контейнеры
+# FastAPI в контейнерах — Docker { #fastapi-in-containers-docker }
-При развёртывании приложений FastAPI, часто начинают с создания **образа контейнера на основе Linux**. Обычно для этого используют **Docker**. Затем можно развернуть такой контейнер на сервере одним из нескольких способов.
+При развёртывании приложений FastAPI распространённый подход — собирать **образ контейнера на Linux**. Обычно это делают с помощью **Docker**. Затем такой образ контейнера можно развернуть несколькими способами.
-Использование контейнеров на основе Linux имеет ряд преимуществ, включая **безопасность**, **воспроизводимость**, **простоту** и прочие.
+Использование Linux-контейнеров даёт ряд преимуществ: **безопасность**, **воспроизводимость**, **простоту** и другие.
/// tip | Подсказка
-Торопитесь или уже знакомы с этой технологией? Перепрыгните на раздел [Создать Docker-образ для FastAPI 👇](#docker-fastapi)
+Нет времени и вы уже знакомы с этим? Перейдите к [`Dockerfile` ниже 👇](#build-a-docker-image-for-fastapi).
///
-### Рукопожатие TLS
+### Начало TLS-рукопожатия { #tls-handshake-start }
-В дальнейшем браузер будет взаимодействовать с этим IP-адресом через **port 443** (общепринятый номер порта для HTTPS).
+Далее браузер будет общаться с этим IP‑адресом на **порту 443** (порт HTTPS).
-Первым шагом будет установление соединения между клиентом (браузером) и сервером и выбор криптографического ключа (для шифрования).
+Первая часть взаимодействия — установить соединение между клиентом и сервером и договориться о криптографических ключах и т.п.
-Эта часть клиент-серверного взаимодействия устанавливает TLS-соединение и называется **TLS-рукопожатием**.
+Это взаимодействие клиента и сервера для установления TLS‑соединения называется **TLS‑рукопожатием**.
-### TLS с расширением SNI
+### TLS с расширением SNI { #tls-with-sni-extension }
-На сервере **только один процесс** может прослушивать определённый **порт** определённого **IP-адреса**. На сервере могут быть и другие процессы, слушающие другие порты этого же IP-адреса, но никакой процесс не может быть привязан к уже занятой комбинации IP-адрес:порт. Эта комбинация называется "сокет".
+На сервере **только один процесс** может слушать конкретный **порт** на конкретном **IP‑адресе**. Могут быть другие процессы, слушающие другие порты на том же IP‑адресе, но не более одного процесса на каждую комбинацию IP‑адреса и порта.
-По умолчанию TLS (HTTPS) использует порт `443`. Потому этот же порт будем использовать и мы.
+По умолчанию TLS (HTTPS) использует порт `443`. Значит, он нам и нужен.
-И раз уж только один процесс может слушать этот порт, то это будет процесс **прокси-сервера завершения работы TLS**.
+Так как только один процесс может слушать этот порт, делать это будет **прокси‑сервер TLS-терминации**.
-Прокси-сервер завершения работы TLS будет иметь доступ к одному или нескольким **TLS-сертификатам** (сертификаты HTTPS).
+У прокси‑сервера TLS-терминации будет доступ к одному или нескольким **TLS‑сертификатам** (HTTPS‑сертификатам).
-Используя **расширение SNI** упомянутое выше, прокси-сервер из имеющихся сертификатов TLS (HTTPS) выберет тот, который соответствует имени домена, указанному в запросе от клиента.
+Используя **расширение SNI**, упомянутое выше, прокси‑сервер TLS-терминации определит, какой из доступных TLS (HTTPS)‑сертификатов нужно использовать для этого соединения, выбрав тот, который соответствует домену, ожидаемому клиентом.
-То есть будет выбран сертификат для домена `someapp.example.com`.
+В нашем случае это будет сертификат для `someapp.example.com`.
-Клиент уже **доверяет** тому, кто выдал этот TLS-сертификат (в нашем случае - Let's Encrypt, но мы ещё обсудим это), потому может **проверить**, действителен ли полученный от сервера сертификат.
+Клиент уже **доверяет** организации, выдавшей этот TLS‑сертификат (в нашем случае — Let's Encrypt, но об этом позже), поэтому может **проверить**, что сертификат действителен.
-Затем, используя этот сертификат, клиент и прокси-сервер **выбирают способ шифрования** данных для устанавливаемого **TCP-соединения**. На этом операция **TLS-рукопожатия** завершена.
+Затем, используя сертификат, клиент и прокси‑сервер TLS-терминации **договариваются о способе шифрования** остальной **TCP‑коммуникации**. На этом **TLS‑рукопожатие** завершено.
-В дальнейшем клиент и сервер будут взаимодействовать по **зашифрованному TCP-соединению**, как предлагается в протоколе TLS. И на основе этого TCP-соедениния будет создано **HTTP-соединение**.
+После этого у клиента и сервера есть **зашифрованное TCP‑соединение** — это и предоставляет TLS. И они могут использовать это соединение, чтобы начать собственно **HTTP‑обмен**.
-Таким образом, **HTTPS** это тот же **HTTP**, но внутри **безопасного TLS-соединения** вместо чистого (незашифрованного) TCP-соединения.
+Собственно, **HTTPS** — это обычный **HTTP** внутри **защищённого TLS‑соединения**, вместо чистого (незашифрованного) TCP‑соединения.
-/// tip | Заметка
+/// tip | Совет
-Обратите внимание, что шифрование происходит на **уровне TCP**, а не на более высоком уровне HTTP.
+Обратите внимание, что шифрование обмена происходит на **уровне TCP**, а не на уровне HTTP.
///
-### HTTPS-запрос
+### HTTPS‑запрос { #https-request }
-Теперь, когда между клиентом и сервером (в нашем случае, браузером и прокси-сервером) создано **зашифрованное TCP-соединение**, они могут начать **обмен данными по протоколу HTTP**.
+Теперь, когда у клиента и сервера (конкретно у браузера и прокси‑сервера TLS-терминации) есть **зашифрованное TCP‑соединение**, они могут начать **HTTP‑обмен**.
-Так клиент отправляет **HTTPS-запрос**. То есть обычный HTTP-запрос, но через зашифрованное TLS-содинение.
+Клиент отправляет **HTTPS‑запрос**. Это обычный HTTP‑запрос через зашифрованное TLS‑соединение.
-### Расшифровка запроса
+### Расшифровка запроса { #decrypt-the-request }
-Прокси-сервер, используя согласованный с клиентом ключ, расшифрует полученный **зашифрованный запрос** и передаст **обычный (незашифрованный) HTTP-запрос** процессу, запускающему приложение (например, процессу Uvicorn запускающему приложение FastAPI).
+Прокси‑сервер TLS-терминации использует согласованное шифрование, чтобы **расшифровать запрос**, и передаёт **обычный (расшифрованный) HTTP‑запрос** процессу, запускающему приложение (например, процессу с Uvicorn, который запускает приложение FastAPI).
-### HTTP-ответ
+### HTTP‑ответ { #http-response }
-Приложение обработает запрос и вернёт **обычный (незашифрованный) HTTP-ответ** прокси-серверу.
+Приложение обработает запрос и отправит **обычный (незашифрованный) HTTP‑ответ** прокси‑серверу TLS-терминации.
-### HTTPS-ответ
+### HTTPS‑ответ { #https-response }
-Пркоси-сервер **зашифрует ответ** используя ранее согласованный с клиентом способ шифрования (которые содержатся в сертификате для домена `someapp.example.com`) и отправит его браузеру.
+Затем прокси‑сервер TLS-терминации **зашифрует ответ** с использованием ранее согласованного способа шифрования (который начали использовать для сертификата для `someapp.example.com`) и отправит его обратно в браузер.
-Наконец, браузер проверит ответ, в том числе, что тот зашифрован с нужным ключом, **расшифрует его** и обработает.
+Далее браузер проверит, что ответ корректен и зашифрован правильным криптографическим ключом и т.п., затем **расшифрует ответ** и обработает его.
-Клиент (браузер) знает, что ответ пришёл от правильного сервера, так как использует методы шифрования, согласованные ими раннее через **HTTPS-сертификат**.
+Клиент (браузер) узнает, что ответ пришёл от правильного сервера, потому что используется способ шифрования, о котором они договорились ранее с помощью **HTTPS‑сертификата**.
-### Множество приложений
+### Несколько приложений { #multiple-applications }
-На одном и том же сервере (или серверах) можно разместить **множество приложений**, например, другие программы с API или базы данных.
+На одном и том же сервере (или серверах) могут работать **несколько приложений**, например другие программы с API или база данных.
-Напомню, что только один процесс (например, прокси-сервер) может прослушивать определённый порт определённого IP-адреса.
-Но другие процессы и приложения тоже могут работать на этом же сервере (серверах), если они не пытаются использовать уже занятую **комбинацию IP-адреса и порта** (сокет).
+Только один процесс может обрабатывать конкретную комбинацию IP и порта (в нашем примере — прокси‑сервер TLS-терминации), но остальные приложения/процессы тоже могут работать на сервере(ах), пока они не пытаются использовать ту же **комбинацию публичного IP и порта**.
-Таким образом, сервер завершения TLS может обрабатывать HTTPS-запросы и использовать сертификаты для **множества доменов** или приложений и передавать запросы правильным адресатам (другим приложениям).
+Таким образом, прокси‑сервер TLS-терминации может обрабатывать HTTPS и сертификаты для **нескольких доменов** (для нескольких приложений), а затем передавать запросы нужному приложению в каждом случае.
-### Обновление сертификата
+### Продление сертификата { #certificate-renewal }
-В недалёком будущем любой сертификат станет **просроченным** (примерно через три месяца после получения).
+Со временем каждый сертификат **истечёт** (примерно через 3 месяца после получения).
-Когда это произойдёт, можно запустить другую программу, которая подключится к Let's Encrypt и обновит сертификат(ы). Существуют прокси-серверы, которые могут сделать это действие самостоятельно.
+Затем будет другая программа (иногда это отдельная программа, иногда — тот же прокси‑сервер TLS-терминации), которая свяжется с Let's Encrypt и продлит сертификат(ы).
-**TLS-сертификаты** не привязаны к IP-адресу, но **связаны с именем домена**.
+**TLS‑сертификаты** **связаны с именем домена**, а не с IP‑адресом.
-Так что при обновлении сертификатов программа должна **подтвердить** центру сертификации (Let's Encrypt), что обновление запросил **"владелец", который контролирует этот домен**.
+Поэтому, чтобы продлить сертификаты, программа продления должна **доказать** удостоверяющему центру (Let's Encrypt), что она действительно **«владеет» и контролирует этот домен**.
-Есть несколько путей осуществления этого. Самые популярные из них:
+Для этого, учитывая разные потребности приложений, есть несколько способов. Популярные из них:
-* **Изменение записей DNS**.
- * Для такого варианта Ваша программа обновления должна уметь работать с API DNS-провайдера, обслуживающего Ваши DNS-записи. Не у всех провайдеров есть такой API, так что этот способ не всегда применим.
-* **Запуск в качестве программы-сервера** (как минимум, на время обновления сертификатов) на публичном IP-адресе домена.
- * Как уже не раз упоминалось, только один процесс может прослушивать определённый порт определённого IP-адреса.
- * Это одна из причин использования прокси-сервера ещё и в качестве программы обновления сертификатов.
- * В случае, если обновлением сертификатов занимается другая программа, вам понадобится остановить прокси-сервер, запустить программу обновления сертификатов на сокете, предназначенном для прокси-сервера, настроить прокси-сервер на работу с новыми сертификатами и перезапустить его. Эта схема далека от идеальной, так как Ваши приложения будут недоступны на время отключения прокси-сервера.
+* **Изменить некоторые DNS‑записи**.
+ * Для этого программа продления должна поддерживать API DNS‑провайдера, поэтому, в зависимости от используемого провайдера DNS, этот вариант может быть доступен или нет.
+* **Запуститься как сервер** (как минимум на время получения сертификатов) на публичном IP‑адресе, связанном с доменом.
+ * Как сказано выше, только один процесс может слушать конкретный IP и порт.
+ * Это одна из причин, почему очень удобно, когда тот же прокси‑сервер TLS-терминации также занимается процессом продления сертификатов.
+ * В противном случае вам, возможно, придётся временно остановить прокси‑сервер TLS-терминации, запустить программу продления для получения сертификатов, затем настроить их в прокси‑сервере TLS-терминации и перезапустить его. Это не идеально, так как ваше приложение(я) будут недоступны, пока прокси‑сервер TLS-терминации остановлен.
-Весь этот процесс обновления, одновременный с обслуживанием запросов, является одной из основных причин, по которой желательно иметь **отдельную систему для работы с HTTPS** в виде прокси-сервера завершения TLS, а не просто использовать сертификаты TLS непосредственно с сервером приложений (например, Uvicorn).
+Весь этот процесс продления, совмещённый с обслуживанием приложения, — одна из главных причин иметь **отдельную систему для работы с HTTPS** в виде прокси‑сервера TLS-терминации, вместо использования TLS‑сертификатов напрямую в сервере приложения (например, Uvicorn).
-## Резюме
+## Пересылаемые HTTP-заголовки прокси { #proxy-forwarded-headers }
-Наличие **HTTPS** очень важно и довольно **критично** в большинстве случаев. Однако, Вам, как разработчику, не нужно тратить много сил на это, достаточно **понимать эти концепции** и принципы их работы.
+Когда вы используете прокси для обработки HTTPS, ваш **сервер приложения** (например, Uvicorn через FastAPI CLI) ничего не знает о процессе HTTPS, он общается обычным HTTP с **прокси‑сервером TLS-терминации**.
-Но узнав базовые основы **HTTPS** вы можете легко совмещать разные инструменты, которые помогут вам в дальнейшей разработке.
+Обычно этот **прокси** на лету добавляет некоторые HTTP‑заголовки перед тем, как переслать запрос на **сервер приложения**, чтобы тот знал, что запрос был **проксирован**.
-В следующих главах я покажу вам несколько примеров, как настраивать **HTTPS** для приложений **FastAPI**. 🔒
+/// note | Технические детали
+
+Заголовки прокси:
+
+* X-Forwarded-For
+* X-Forwarded-Proto
+* X-Forwarded-Host
+
+///
+
+Тем не менее, так как **сервер приложения** не знает, что он находится за доверенным **прокси**, по умолчанию он не будет доверять этим заголовкам.
+
+Но вы можете настроить **сервер приложения**, чтобы он доверял *пересылаемым* заголовкам, отправленным **прокси**. Если вы используете FastAPI CLI, вы можете использовать *опцию CLI* `--forwarded-allow-ips`, чтобы указать, с каких IP‑адресов следует доверять этим *пересылаемым* заголовкам.
+
+Например, если **сервер приложения** получает запросы только от доверенного **прокси**, вы можете установить `--forwarded-allow-ips="*"`, чтобы доверять всем входящим IP, так как он всё равно будет получать запросы только с IP‑адреса, используемого **прокси**.
+
+Таким образом, приложение сможет знать свой публичный URL, использует ли оно HTTPS, какой домен и т.п.
+
+Это будет полезно, например, для корректной обработки редиректов.
+
+/// tip | Совет
+
+Подробнее об этом вы можете узнать в документации: [За прокси — Включить пересылаемые заголовки прокси](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank}
+
+///
+
+## Резюме { #recap }
+
+Наличие **HTTPS** очень важно и во многих случаях довольно **критично**. Большая часть усилий, которые вам, как разработчику, нужно приложить вокруг HTTPS, — это просто **понимание этих концепций** и того, как они работают.
+
+Зная базовую информацию о **HTTPS для разработчиков**, вы сможете легко комбинировать и настраивать разные инструменты, чтобы управлять всем этим простым способом.
+
+В некоторых из следующих глав я покажу вам несколько конкретных примеров настройки **HTTPS** для приложений **FastAPI**. 🔒
diff --git a/docs/ru/docs/deployment/index.md b/docs/ru/docs/deployment/index.md
index e88ddc3e2..ffb77641d 100644
--- a/docs/ru/docs/deployment/index.md
+++ b/docs/ru/docs/deployment/index.md
@@ -1,21 +1,23 @@
-# Развёртывание
+# Развёртывание { #deployment }
Развернуть приложение **FastAPI** довольно просто.
-## Да что такое это ваше - "развёртывание"?!
+## Что означает развёртывание { #what-does-deployment-mean }
Термин **развёртывание** (приложения) означает выполнение необходимых шагов, чтобы сделать приложение **доступным для пользователей**.
-Обычно **веб-приложения** размещают на удалённом компьютере с серверной программой, которая обеспечивает хорошую производительность, стабильность и т. д., Чтобы ваши пользователи могли эффективно, беспрерывно и беспроблемно обращаться к приложению.
+Для **веб-API** это обычно означает размещение его на **удалённой машине** с **серверной программой**, обеспечивающей хорошую производительность, стабильность и т.д., чтобы ваши **пользователи** могли **получать доступ** к приложению эффективно и без перебоев или проблем.
-Это отличается от **разработки**, когда вы постоянно меняете код, делаете в нём намеренные ошибки и исправляете их, останавливаете и перезапускаете сервер разработки и т. д.
+Это отличается от этапов **разработки**, когда вы постоянно меняете код, ломаете его и исправляете, останавливаете и перезапускаете сервер разработки и т.д.
-## Стратегии развёртывания
+## Стратегии развёртывания { #deployment-strategies }
-В зависимости от вашего конкретного случая, есть несколько способов сделать это.
+Есть несколько способов сделать это, в зависимости от вашего конкретного случая и используемых вами инструментов.
Вы можете **развернуть сервер** самостоятельно, используя различные инструменты. Например, можно использовать **облачный сервис**, который выполнит часть работы за вас. Также возможны и другие варианты.
+Например, мы, команда, стоящая за FastAPI, создали **FastAPI Cloud**, чтобы сделать развёртывание приложений FastAPI в облаке как можно более простым и прямолинейным, с тем же удобством для разработчика, что и при работе с FastAPI.
+
В этом блоке я покажу вам некоторые из основных концепций, которые вы, вероятно, должны иметь в виду при развертывании приложения **FastAPI** (хотя большинство из них применимо к любому другому типу веб-приложений).
В последующих разделах вы узнаете больше деталей и методов, необходимых для этого. ✨
diff --git a/docs/ru/docs/deployment/manually.md b/docs/ru/docs/deployment/manually.md
index 9b1d32be8..93287372a 100644
--- a/docs/ru/docs/deployment/manually.md
+++ b/docs/ru/docs/deployment/manually.md
@@ -1,163 +1,157 @@
-# Запуск сервера вручную - Uvicorn
+# Запуск сервера вручную { #run-a-server-manually }
-Для запуска приложения **FastAPI** на удалённой серверной машине вам необходим программный сервер, поддерживающий протокол ASGI, такой как **Uvicorn**.
+## Используйте команду `fastapi run` { #use-the-fastapi-run-command }
-Существует три наиболее распространённые альтернативы:
+Коротко: используйте `fastapi run`, чтобы запустить ваше приложение FastAPI:
-* Uvicorn: высокопроизводительный ASGI сервер.
-* Hypercorn: ASGI сервер, помимо прочего поддерживающий HTTP/2 и Trio.
-* Daphne: ASGI сервер, созданный для Django Channels.
-
-## Сервер как машина и сервер как программа
-
-В этих терминах есть некоторые различия и вам следует запомнить их. 💡
-
-Слово "**сервер**" чаще всего используется в двух контекстах:
+
+
+Но вы можете отключить её, установив `syntaxHighlight` в `False`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial001_py39.py hl[3] *}
+
+…и после этого Swagger UI больше не будет показывать подсветку синтаксиса:
+
+
+
+## Изменить тему { #change-the-theme }
+
+Аналогично вы можете задать тему подсветки синтаксиса с ключом "syntaxHighlight.theme" (обратите внимание, что посередине стоит точка):
+
+{* ../../docs_src/configure_swagger_ui/tutorial002_py39.py hl[3] *}
+
+Эта настройка изменит цветовую тему подсветки синтаксиса:
+
+
+
+## Изменить параметры Swagger UI по умолчанию { #change-default-swagger-ui-parameters }
+
+FastAPI включает некоторые параметры конфигурации по умолчанию, подходящие для большинства случаев.
+
+Это включает следующие настройки по умолчанию:
+
+{* ../../fastapi/openapi/docs.py ln[9:24] hl[18:24] *}
+
+Вы можете переопределить любую из них, указав другое значение в аргументе `swagger_ui_parameters`.
+
+Например, чтобы отключить `deepLinking`, можно передать такие настройки в `swagger_ui_parameters`:
+
+{* ../../docs_src/configure_swagger_ui/tutorial003_py39.py hl[3] *}
+
+## Другие параметры Swagger UI { #other-swagger-ui-parameters }
+
+Чтобы увидеть все остальные возможные настройки, прочитайте официальную документацию по параметрам Swagger UI.
+
+## Настройки только для JavaScript { #javascript-only-settings }
+
+Swagger UI также допускает другие настройки, которые являются **чисто JavaScript-объектами** (например, JavaScript-функциями).
+
+FastAPI также включает следующие настройки `presets` (только для JavaScript):
+
+```JavaScript
+presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+]
+```
+
+Это объекты **JavaScript**, а не строки, поэтому напрямую передать их из Python-кода нельзя.
+
+Если вам нужны такие настройки только для JavaScript, используйте один из методов выше. Переопределите *операцию пути* Swagger UI и вручную напишите любой необходимый JavaScript.
diff --git a/docs/ru/docs/how-to/custom-docs-ui-assets.md b/docs/ru/docs/how-to/custom-docs-ui-assets.md
new file mode 100644
index 000000000..f524911e6
--- /dev/null
+++ b/docs/ru/docs/how-to/custom-docs-ui-assets.md
@@ -0,0 +1,185 @@
+# Свои статические ресурсы UI документации (самостоятельный хостинг) { #custom-docs-ui-static-assets-self-hosting }
+
+Документация API использует **Swagger UI** и **ReDoc**, и для каждого из них нужны некоторые файлы JavaScript и CSS.
+
+По умолчанию эти файлы отдаются с CDN.
+
+Но это можно настроить: вы можете указать конкретный CDN или отдавать файлы самостоятельно.
+
+## Пользовательский CDN для JavaScript и CSS { #custom-cdn-for-javascript-and-css }
+
+Допустим, вы хотите использовать другой CDN, например `https://unpkg.com/`.
+
+Это может быть полезно, если, например, вы живёте в стране, где некоторые URL ограничены.
+
+### Отключить автоматическую документацию { #disable-the-automatic-docs }
+
+Первый шаг — отключить автоматическую документацию, так как по умолчанию она использует стандартный CDN.
+
+Чтобы отключить её, установите их URL в значение `None` при создании вашего приложения `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[8] *}
+
+### Подключить пользовательскую документацию { #include-the-custom-docs }
+
+Теперь вы можете создать *операции пути* для пользовательской документации.
+
+Вы можете переиспользовать внутренние функции FastAPI для создания HTML-страниц документации и передать им необходимые аргументы:
+
+* `openapi_url`: URL, по которому HTML-страница документации сможет получить схему OpenAPI для вашего API. Здесь можно использовать атрибут `app.openapi_url`.
+* `title`: заголовок вашего API.
+* `oauth2_redirect_url`: здесь можно использовать `app.swagger_ui_oauth2_redirect_url`, чтобы оставить значение по умолчанию.
+* `swagger_js_url`: URL, по которому HTML для документации Swagger UI сможет получить файл **JavaScript**. Это URL вашего пользовательского CDN.
+* `swagger_css_url`: URL, по которому HTML для документации Swagger UI сможет получить файл **CSS**. Это URL вашего пользовательского CDN.
+
+Аналогично и для ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[2:6,11:19,22:24,27:33] *}
+
+/// tip | Совет
+
+*Операция пути* для `swagger_ui_redirect` — это вспомогательный эндпоинт на случай, когда вы используете OAuth2.
+
+Если вы интегрируете свой API с провайдером OAuth2, вы сможете аутентифицироваться и вернуться к документации API с полученными учётными данными, а затем взаимодействовать с ним, используя реальную аутентификацию OAuth2.
+
+Swagger UI сделает это за вас «за кулисами», но для этого ему нужен этот вспомогательный «redirect» эндпоинт.
+
+///
+
+### Создайте *операцию пути*, чтобы проверить { #create-a-path-operation-to-test-it }
+
+Чтобы убедиться, что всё работает, создайте *операцию пути*:
+
+{* ../../docs_src/custom_docs_ui/tutorial001_py39.py hl[36:38] *}
+
+### Тестирование { #test-it }
+
+Теперь вы должны иметь возможность открыть свою документацию по адресу http://127.0.0.1:8000/docs и перезагрузить страницу — «ассеты» (статические файлы) будут загружаться с нового CDN.
+
+## Самостоятельный хостинг JavaScript и CSS для документации { #self-hosting-javascript-and-css-for-docs }
+
+Самостоятельный хостинг JavaScript и CSS может быть полезен, если, например, вам нужно, чтобы приложение продолжало работать в офлайне, без доступа к открытому Интернету, или в локальной сети.
+
+Здесь вы увидите, как отдавать эти файлы самостоятельно, в том же приложении FastAPI, и настроить документацию на их использование.
+
+### Структура файлов проекта { #project-file-structure }
+
+Допустим, структура файлов вашего проекта выглядит так:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+```
+
+Теперь создайте директорию для хранения этих статических файлов.
+
+Новая структура файлов может выглядеть так:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static/
+```
+
+### Скачайте файлы { #download-the-files }
+
+Скачайте статические файлы, необходимые для документации, и поместите их в директорию `static/`.
+
+Скорее всего, вы можете кликнуть правой кнопкой на каждой ссылке и выбрать что-то вроде «Сохранить ссылку как...».
+
+**Swagger UI** использует файлы:
+
+* `swagger-ui-bundle.js`
+* `swagger-ui.css`
+
+А **ReDoc** использует файл:
+
+* `redoc.standalone.js`
+
+После этого структура файлов может выглядеть так:
+
+```
+.
+├── app
+│ ├── __init__.py
+│ ├── main.py
+└── static
+ ├── redoc.standalone.js
+ ├── swagger-ui-bundle.js
+ └── swagger-ui.css
+```
+
+### Предоставьте доступ к статическим файлам { #serve-the-static-files }
+
+* Импортируйте `StaticFiles`.
+* Смонтируйте экземпляр `StaticFiles()` в определённый путь.
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[7,11] *}
+
+### Протестируйте статические файлы { #test-the-static-files }
+
+Запустите своё приложение и откройте http://127.0.0.1:8000/static/redoc.standalone.js.
+
+Вы должны увидеть очень длинный JavaScript-файл для **ReDoc**.
+
+Он может начинаться примерно так:
+
+```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")):
+...
+```
+
+Это подтверждает, что ваше приложение умеет отдавать статические файлы и что вы поместили файлы документации в нужное место.
+
+Теперь можно настроить приложение так, чтобы документация использовала эти статические файлы.
+
+### Отключить автоматическую документацию для статических файлов { #disable-the-automatic-docs-for-static-files }
+
+Так же, как и при использовании пользовательского CDN, первым шагом будет отключение автоматической документации, так как по умолчанию она использует CDN.
+
+Чтобы отключить её, установите их URL в значение `None` при создании вашего приложения `FastAPI`:
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[9] *}
+
+### Подключить пользовательскую документацию со статическими файлами { #include-the-custom-docs-for-static-files }
+
+Аналогично пользовательскому CDN, теперь вы можете создать *операции пути* для собственной документации.
+
+Снова можно переиспользовать внутренние функции FastAPI для создания HTML-страниц документации и передать им необходимые аргументы:
+
+* `openapi_url`: URL, по которому HTML-страница документации сможет получить схему OpenAPI для вашего API. Здесь можно использовать атрибут `app.openapi_url`.
+* `title`: заголовок вашего API.
+* `oauth2_redirect_url`: здесь можно использовать `app.swagger_ui_oauth2_redirect_url`, чтобы оставить значение по умолчанию.
+* `swagger_js_url`: URL, по которому HTML для документации Swagger UI сможет получить файл **JavaScript**. **Это тот файл, который теперь отдаёт ваше собственное приложение**.
+* `swagger_css_url`: URL, по которому HTML для документации Swagger UI сможет получить файл **CSS**. **Это тот файл, который теперь отдаёт ваше собственное приложение**.
+
+Аналогично и для ReDoc...
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[2:6,14:22,25:27,30:36] *}
+
+/// tip | Совет
+
+*Операция пути* для `swagger_ui_redirect` — это вспомогательный эндпоинт на случай, когда вы используете OAuth2.
+
+Если вы интегрируете свой API с провайдером OAuth2, вы сможете аутентифицироваться и вернуться к документации API с полученными учётными данными, а затем взаимодействовать с ним, используя реальную аутентификацию OAuth2.
+
+Swagger UI сделает это за вас «за кулисами», но для этого ему нужен этот вспомогательный «redirect» эндпоинт.
+
+///
+
+### Создайте *операцию пути* для теста статических файлов { #create-a-path-operation-to-test-static-files }
+
+Чтобы убедиться, что всё работает, создайте *операцию пути*:
+
+{* ../../docs_src/custom_docs_ui/tutorial002_py39.py hl[39:41] *}
+
+### Тестирование UI со статическими файлами { #test-static-files-ui }
+
+Теперь вы можете отключить Wi‑Fi, открыть свою документацию по адресу http://127.0.0.1:8000/docs и перезагрузить страницу.
+
+Даже без Интернета вы сможете видеть документацию к своему API и взаимодействовать с ним.
diff --git a/docs/ru/docs/how-to/custom-request-and-route.md b/docs/ru/docs/how-to/custom-request-and-route.md
new file mode 100644
index 000000000..feef9670a
--- /dev/null
+++ b/docs/ru/docs/how-to/custom-request-and-route.md
@@ -0,0 +1,109 @@
+# Пользовательские классы Request и APIRoute { #custom-request-and-apiroute-class }
+
+В некоторых случаях может понадобиться переопределить логику, используемую классами `Request` и `APIRoute`.
+
+В частности, это может быть хорошей альтернативой логике в middleware.
+
+Например, если вы хотите прочитать или изменить тело запроса до того, как оно будет обработано вашим приложением.
+
+/// danger | Опасность
+
+Это «продвинутая» возможность.
+
+Если вы только начинаете работать с **FastAPI**, возможно, стоит пропустить этот раздел.
+
+///
+
+## Сценарии использования { #use-cases }
+
+Некоторые сценарии:
+
+* Преобразование тел запросов, не в формате JSON, в JSON (например, `msgpack`).
+* Распаковка тел запросов, сжатых с помощью gzip.
+* Автоматическое логирование всех тел запросов.
+
+## Обработка пользовательского кодирования тела запроса { #handling-custom-request-body-encodings }
+
+Посмотрим как использовать пользовательский подкласс `Request` для распаковки gzip-запросов.
+
+И подкласс `APIRoute`, чтобы использовать этот пользовательский класс запроса.
+
+### Создать пользовательский класс `GzipRequest` { #create-a-custom-gziprequest-class }
+
+/// tip | Совет
+
+Это учебный пример, демонстрирующий принцип работы. Если вам нужна поддержка Gzip, вы можете использовать готовый [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}.
+
+///
+
+Сначала создадим класс `GzipRequest`, который переопределит метод `Request.body()` и распакует тело запроса при наличии соответствующего HTTP-заголовка.
+
+Если в заголовке нет `gzip`, он не будет пытаться распаковывать тело.
+
+Таким образом, один и тот же класс маршрута сможет обрабатывать как gzip-сжатые, так и несжатые запросы.
+
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *}
+
+### Создать пользовательский класс `GzipRoute` { #create-a-custom-gziproute-class }
+
+Далее создадим пользовательский подкласс `fastapi.routing.APIRoute`, который будет использовать `GzipRequest`.
+
+На этот раз он переопределит метод `APIRoute.get_route_handler()`.
+
+Этот метод возвращает функцию. Именно эта функция получает HTTP-запрос и возвращает HTTP-ответ.
+
+Здесь мы используем её, чтобы создать `GzipRequest` из исходного HTTP-запроса.
+
+{* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[19:27] *}
+
+/// note | Технические детали
+
+У `Request` есть атрибут `request.scope` — это просто Python-`dict`, содержащий метаданные, связанные с HTTP-запросом.
+
+У `Request` также есть `request.receive` — функция для «получения» тела запроса.
+
+И `dict` `scope`, и функция `receive` являются частью спецификации ASGI.
+
+Именно этих двух компонентов — `scope` и `receive` — достаточно, чтобы создать новый экземпляр `Request`.
+
+Чтобы узнать больше о `Request`, см. документацию Starlette о запросах.
+
+///
+
+Единственное, что делает по-другому функция, возвращённая `GzipRequest.get_route_handler`, — преобразует `Request` в `GzipRequest`.
+
+Благодаря этому наш `GzipRequest` позаботится о распаковке данных (при необходимости) до передачи их в наши *операции пути*.
+
+Дальше вся логика обработки остаётся прежней.
+
+Но благодаря изменениям в `GzipRequest.body` тело запроса будет автоматически распаковано при необходимости, когда оно будет загружено **FastAPI**.
+
+## Доступ к телу запроса в обработчике исключений { #accessing-the-request-body-in-an-exception-handler }
+
+/// tip | Совет
+
+Для решения этой задачи, вероятно, намного проще использовать `body` в пользовательском обработчике `RequestValidationError` ([Обработка ошибок](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
+
+Но этот пример всё равно актуален и показывает, как взаимодействовать с внутренними компонентами.
+
+///
+
+Тем же подходом можно воспользоваться, чтобы получить доступ к телу запроса в обработчике исключений.
+
+Нужно лишь обработать запрос внутри блока `try`/`except`:
+
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[14,16] *}
+
+Если произойдёт исключение, экземпляр `Request` всё ещё будет в области видимости, поэтому мы сможем прочитать тело запроса и использовать его при обработке ошибки:
+
+{* ../../docs_src/custom_request_and_route/tutorial002_an_py310.py hl[17:19] *}
+
+## Пользовательский класс `APIRoute` в роутере { #custom-apiroute-class-in-a-router }
+
+Вы также можете задать параметр `route_class` у `APIRouter`:
+
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[26] *}
+
+В этом примере *операции пути*, объявленные в `router`, будут использовать пользовательский класс `TimedRoute` и получат дополнительный HTTP-заголовок `X-Response-Time` в ответе с временем, затраченным на формирование ответа:
+
+{* ../../docs_src/custom_request_and_route/tutorial003_py310.py hl[13:20] *}
diff --git a/docs/ru/docs/how-to/extending-openapi.md b/docs/ru/docs/how-to/extending-openapi.md
new file mode 100644
index 000000000..1d69cbdb3
--- /dev/null
+++ b/docs/ru/docs/how-to/extending-openapi.md
@@ -0,0 +1,80 @@
+# Расширение OpenAPI { #extending-openapi }
+
+Иногда может понадобиться изменить сгенерированную схему OpenAPI.
+
+В этом разделе показано, как это сделать.
+
+## Обычный процесс { #the-normal-process }
+
+Обычный (по умолчанию) процесс выглядит так.
+
+Приложение `FastAPI` (экземпляр) имеет метод `.openapi()`, который должен возвращать схему OpenAPI.
+
+В процессе создания объекта приложения регистрируется *операция пути* (обработчик пути) для `/openapi.json` (или для того, что указано в вашем `openapi_url`).
+
+Она просто возвращает JSON-ответ с результатом вызова метода приложения `.openapi()`.
+
+По умолчанию метод `.openapi()` проверяет свойство `.openapi_schema`: если в нём уже есть данные, возвращает их.
+
+Если нет — генерирует схему с помощью вспомогательной функции `fastapi.openapi.utils.get_openapi`.
+
+Функция `get_openapi()` принимает параметры:
+
+* `title`: Заголовок OpenAPI, отображается в документации.
+* `version`: Версия вашего API, например `2.5.0`.
+* `openapi_version`: Версия используемой спецификации OpenAPI. По умолчанию — последняя: `3.1.0`.
+* `summary`: Краткое описание API.
+* `description`: Описание вашего API; может включать Markdown и будет отображается в документации.
+* `routes`: Список маршрутов — это каждая зарегистрированная *операция пути*. Берутся из `app.routes`.
+
+/// info | Информация
+
+Параметр `summary` доступен в OpenAPI 3.1.0 и выше, поддерживается FastAPI версии 0.99.0 и выше.
+
+///
+
+## Переопределение значений по умолчанию { #overriding-the-defaults }
+
+Используя информацию выше, вы можете той же вспомогательной функцией сгенерировать схему OpenAPI и переопределить любые нужные части.
+
+Например, добавим расширение OpenAPI ReDoc для включения собственного логотипа.
+
+### Обычный **FastAPI** { #normal-fastapi }
+
+Сначала напишите приложение **FastAPI** как обычно:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[1,4,7:9] *}
+
+### Сгенерируйте схему OpenAPI { #generate-the-openapi-schema }
+
+Затем используйте ту же вспомогательную функцию для генерации схемы OpenAPI внутри функции `custom_openapi()`:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[2,15:21] *}
+
+### Измените схему OpenAPI { #modify-the-openapi-schema }
+
+Теперь можно добавить расширение ReDoc, добавив кастомный `x-logo` в «объект» `info` в схеме OpenAPI:
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[22:24] *}
+
+### Кэшируйте схему OpenAPI { #cache-the-openapi-schema }
+
+Вы можете использовать свойство `.openapi_schema` как «кэш» для хранения сгенерированной схемы.
+
+Так приложению не придётся генерировать схему каждый раз, когда пользователь открывает документацию API.
+
+Она будет создана один раз, а затем тот же кэшированный вариант будет использоваться для последующих запросов.
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[13:14,25:26] *}
+
+### Переопределите метод { #override-the-method }
+
+Теперь вы можете заменить метод `.openapi()` на вашу новую функцию.
+
+{* ../../docs_src/extending_openapi/tutorial001_py39.py hl[29] *}
+
+### Проверьте { #check-it }
+
+Перейдите на http://127.0.0.1:8000/redoc — вы увидите, что используется ваш кастомный логотип (в этом примере — логотип **FastAPI**):
+
+
diff --git a/docs/ru/docs/how-to/general.md b/docs/ru/docs/how-to/general.md
new file mode 100644
index 000000000..029ea1d27
--- /dev/null
+++ b/docs/ru/docs/how-to/general.md
@@ -0,0 +1,39 @@
+# Общее — Как сделать — Рецепты { #general-how-to-recipes }
+
+Здесь несколько указателей на другие места в документации для общих или частых вопросов.
+
+## Фильтрация данных — Безопасность { #filter-data-security }
+
+Чтобы убедиться, что вы не возвращаете больше данных, чем следует, прочитайте документацию: [Руководство — Модель ответа — Возвращаемый тип](../tutorial/response-model.md){.internal-link target=_blank}.
+
+## Теги в документации — OpenAPI { #documentation-tags-openapi }
+
+Чтобы добавить теги к вашим *операциям пути* и группировать их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Теги](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
+
+## Краткое описание и описание в документации — OpenAPI { #documentation-summary-and-description-openapi }
+
+Чтобы добавить краткое описание и описание к вашим *операциям пути* и отобразить их в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Краткое описание и описание](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
+
+## Описание ответа в документации — OpenAPI { #documentation-response-description-openapi }
+
+Чтобы задать описание ответа, отображаемое в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Описание ответа](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
+
+## Документация — пометить операцию пути устаревшей — OpenAPI { #documentation-deprecate-a-path-operation-openapi }
+
+Чтобы пометить *операцию пути* как устаревшую и показать это в интерфейсе документации, прочитайте документацию: [Руководство — Конфигурации операций пути — Пометить операцию пути устаревшей](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
+
+## Преобразование любых данных к формату, совместимому с JSON { #convert-any-data-to-json-compatible }
+
+Чтобы преобразовать любые данные к формату, совместимому с JSON, прочитайте документацию: [Руководство — JSON-совместимый кодировщик](../tutorial/encoder.md){.internal-link target=_blank}.
+
+## Метаданные OpenAPI — Документация { #openapi-metadata-docs }
+
+Чтобы добавить метаданные в вашу схему OpenAPI, включая лицензию, версию, контакты и т.д., прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md){.internal-link target=_blank}.
+
+## Пользовательский URL OpenAPI { #openapi-custom-url }
+
+Чтобы настроить URL OpenAPI (или удалить его), прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
+
+## URL документации OpenAPI { #openapi-docs-urls }
+
+Чтобы изменить URL, используемые для автоматически сгенерированных пользовательских интерфейсов документации, прочитайте документацию: [Руководство — Метаданные и URL документации](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
diff --git a/docs/ru/docs/how-to/graphql.md b/docs/ru/docs/how-to/graphql.md
new file mode 100644
index 000000000..50c321e7d
--- /dev/null
+++ b/docs/ru/docs/how-to/graphql.md
@@ -0,0 +1,60 @@
+# GraphQL { #graphql }
+
+Так как **FastAPI** основан на стандарте **ASGI**, очень легко интегрировать любую библиотеку **GraphQL**, также совместимую с ASGI.
+
+Вы можете комбинировать обычные *операции пути* FastAPI с GraphQL в одном приложении.
+
+/// tip | Совет
+
+**GraphQL** решает некоторые очень специфические задачи.
+
+У него есть как **преимущества**, так и **недостатки** по сравнению с обычными **веб-API**.
+
+Убедитесь, что **выгоды** для вашего случая использования перевешивают **недостатки**. 🤓
+
+///
+
+## Библиотеки GraphQL { #graphql-libraries }
+
+Ниже приведены некоторые библиотеки **GraphQL** с поддержкой **ASGI**. Их можно использовать с **FastAPI**:
+
+* Strawberry 🍓
+ * С документацией для FastAPI
+* Ariadne
+ * С документацией для FastAPI
+* Tartiflette
+ * С Tartiflette ASGI для интеграции с ASGI
+* Graphene
+ * С starlette-graphene3
+
+## GraphQL со Strawberry { #graphql-with-strawberry }
+
+Если вам нужно или хочется работать с **GraphQL**, **Strawberry** — **рекомендуемая** библиотека, так как её дизайн ближе всего к дизайну **FastAPI**, всё основано на **аннотациях типов**.
+
+В зависимости от вашего сценария использования вы можете предпочесть другую библиотеку, но если бы вы спросили меня, я, скорее всего, предложил бы попробовать **Strawberry**.
+
+Вот небольшой пример того, как можно интегрировать Strawberry с FastAPI:
+
+{* ../../docs_src/graphql_/tutorial001_py39.py hl[3,22,25] *}
+
+Подробнее о Strawberry можно узнать в документации Strawberry.
+
+А также в документации по интеграции Strawberry с FastAPI.
+
+## Устаревший `GraphQLApp` из Starlette { #older-graphqlapp-from-starlette }
+
+В предыдущих версиях Starlette был класс `GraphQLApp` для интеграции с Graphene.
+
+Он был объявлен устаревшим в Starlette, но если у вас есть код, который его использовал, вы можете легко **мигрировать** на starlette-graphene3, который решает ту же задачу и имеет **почти идентичный интерфейс**.
+
+/// tip | Совет
+
+Если вам нужен GraphQL, я всё же рекомендую посмотреть Strawberry, так как он основан на аннотациях типов, а не на пользовательских классах и типах.
+
+///
+
+## Подробнее { #learn-more }
+
+Подробнее о **GraphQL** вы можете узнать в официальной документации GraphQL.
+
+Также можно почитать больше о каждой из указанных выше библиотек по приведённым ссылкам.
diff --git a/docs/ru/docs/how-to/index.md b/docs/ru/docs/how-to/index.md
new file mode 100644
index 000000000..228c125dd
--- /dev/null
+++ b/docs/ru/docs/how-to/index.md
@@ -0,0 +1,13 @@
+# Как сделать — Рецепты { #how-to-recipes }
+
+Здесь вы найдете разные рецепты и руководства «как сделать» по различным темам.
+
+Большинство из этих идей более-менее независимы, и в большинстве случаев вам стоит изучать их только если они напрямую относятся к вашему проекту.
+
+Если что-то кажется интересным и полезным для вашего проекта, смело изучайте; в противном случае, вероятно, можно просто пропустить.
+
+/// tip | Совет
+
+Если вы хотите изучить FastAPI структурированно (рекомендуется), вместо этого читайте [Учебник — Руководство пользователя](../tutorial/index.md){.internal-link target=_blank} по главам.
+
+///
diff --git a/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
new file mode 100644
index 000000000..2b47c08f6
--- /dev/null
+++ b/docs/ru/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
@@ -0,0 +1,135 @@
+# Миграция с Pydantic v1 на Pydantic v2 { #migrate-from-pydantic-v1-to-pydantic-v2 }
+
+Если у вас старое приложение FastAPI, возможно, вы используете Pydantic версии 1.
+
+FastAPI версии 0.100.0 поддерживал либо Pydantic v1, либо v2. Он использовал ту версию, которая была установлена.
+
+FastAPI версии 0.119.0 добавил частичную поддержку Pydantic v1 изнутри Pydantic v2 (как `pydantic.v1`), чтобы упростить миграцию на v2.
+
+FastAPI 0.126.0 убрал поддержку Pydantic v1, при этом ещё некоторое время продолжал поддерживать `pydantic.v1`.
+
+/// warning | Предупреждение
+
+Команда Pydantic прекратила поддержку Pydantic v1 для последних версий Python, начиная с **Python 3.14**.
+
+Это включает `pydantic.v1`, который больше не поддерживается в Python 3.14 и выше.
+
+Если вы хотите использовать последние возможности Python, вам нужно убедиться, что вы используете Pydantic v2.
+
+///
+
+Если у вас старое приложение FastAPI с Pydantic v1, здесь я покажу, как мигрировать на Pydantic v2, и **возможности FastAPI 0.119.0**, которые помогут выполнить постепенную миграцию.
+
+## Официальное руководство { #official-guide }
+
+У Pydantic есть официальное руководство по миграции с v1 на v2.
+
+Там также описано, что изменилось, как валидации стали более корректными и строгими, возможные нюансы и т.д.
+
+Прочитайте его, чтобы лучше понять, что изменилось.
+
+## Тесты { #tests }
+
+Убедитесь, что у вас есть [тесты](../tutorial/testing.md){.internal-link target=_blank} для вашего приложения и что вы запускаете их в системе непрерывной интеграции (CI).
+
+Так вы сможете выполнить обновление и убедиться, что всё работает как ожидается.
+
+## `bump-pydantic` { #bump-pydantic }
+
+Во многих случаях, когда вы используете обычные Pydantic‑модели без пользовательских настроек, вы сможете автоматизировать большую часть процесса миграции с Pydantic v1 на Pydantic v2.
+
+Вы можете использовать `bump-pydantic` от той же команды Pydantic.
+
+Этот инструмент поможет автоматически изменить большую часть кода, который нужно изменить.
+
+После этого вы можете запустить тесты и проверить, что всё работает. Если да — на этом всё. 😎
+
+## Pydantic v1 в v2 { #pydantic-v1-in-v2 }
+
+Pydantic v2 включает всё из Pydantic v1 как подмодуль `pydantic.v1`. Но это больше не поддерживается в версиях Python выше 3.13.
+
+Это означает, что вы можете установить последнюю версию Pydantic v2 и импортировать и использовать старые компоненты Pydantic v1 из этого подмодуля так, как если бы у вас был установлен старый Pydantic v1.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py hl[1,4] *}
+
+### Поддержка FastAPI для Pydantic v1 внутри v2 { #fastapi-support-for-pydantic-v1-in-v2 }
+
+Начиная с FastAPI 0.119.0, есть также частичная поддержка Pydantic v1 изнутри Pydantic v2, чтобы упростить миграцию на v2.
+
+Таким образом, вы можете обновить Pydantic до последней версии 2 и сменить импорты на подмодуль `pydantic.v1` — во многих случаях всё просто заработает.
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py hl[2,5,15] *}
+
+/// warning | Предупреждение
+
+Имейте в виду, что так как команда Pydantic больше не поддерживает Pydantic v1 в последних версиях Python, начиная с Python 3.14, использование `pydantic.v1` также не поддерживается в Python 3.14 и выше.
+
+///
+
+### Pydantic v1 и v2 в одном приложении { #pydantic-v1-and-v2-on-the-same-app }
+
+В Pydantic **не поддерживается** ситуация, когда в одной модели Pydantic v2 используются поля, определённые как модели Pydantic v1, и наоборот.
+
+```mermaid
+graph TB
+ subgraph "❌ Not Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+…но в одном и том же приложении вы можете иметь отдельные модели на Pydantic v1 и v2.
+
+```mermaid
+graph TB
+ subgraph "✅ Supported"
+ direction TB
+ subgraph V2["Pydantic v2 Model"]
+ V2Field["Pydantic v2 Model"]
+ end
+ subgraph V1["Pydantic v1 Model"]
+ V1Field["Pydantic v1 Model"]
+ end
+ end
+
+ style V2 fill:#f9fff3
+ style V1 fill:#fff6f0
+ style V1Field fill:#fff6f0
+ style V2Field fill:#f9fff3
+```
+
+В некоторых случаях можно использовать и модели Pydantic v1, и v2 в одной и той же **операции пути** (обработчике пути) вашего приложения FastAPI:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py hl[2:3,6,12,21:22] *}
+
+В примере выше модель входных данных — это модель Pydantic v1, а модель выходных данных (указанная в `response_model=ItemV2`) — это модель Pydantic v2.
+
+### Параметры Pydantic v1 { #pydantic-v1-parameters }
+
+Если вам нужно использовать некоторые специфичные для FastAPI инструменты для параметров, такие как `Body`, `Query`, `Form` и т.п., с моделями Pydantic v1, вы можете импортировать их из `fastapi.temp_pydantic_v1_params`, пока завершаете миграцию на Pydantic v2:
+
+{* ../../docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py hl[4,18] *}
+
+### Мигрируйте по шагам { #migrate-in-steps }
+
+/// tip | Совет
+
+Сначала попробуйте `bump-pydantic`: если тесты проходят и всё работает, вы справились одной командой. ✨
+
+///
+
+Если `bump-pydantic` не подходит для вашего случая, вы можете использовать поддержку одновременной работы моделей Pydantic v1 и v2 в одном приложении, чтобы мигрировать на Pydantic v2 постепенно.
+
+Сначала вы можете обновить Pydantic до последней 2-й версии и изменить импорты так, чтобы все ваши модели использовали `pydantic.v1`.
+
+Затем вы можете начать мигрировать ваши модели с Pydantic v1 на v2 группами, поэтапно. 🚶
diff --git a/docs/ru/docs/how-to/separate-openapi-schemas.md b/docs/ru/docs/how-to/separate-openapi-schemas.md
new file mode 100644
index 000000000..8f6c83e7e
--- /dev/null
+++ b/docs/ru/docs/how-to/separate-openapi-schemas.md
@@ -0,0 +1,102 @@
+# Разделять схемы OpenAPI для входа и выхода или нет { #separate-openapi-schemas-for-input-and-output-or-not }
+
+При использовании **Pydantic v2** сгенерированный OpenAPI становится чуть более точным и **корректным**, чем раньше. 😎
+
+На самом деле, в некоторых случаях в OpenAPI будет даже **две JSON-схемы** для одной и той же Pydantic‑модели: для входа и для выхода — в зависимости от наличия **значений по умолчанию**.
+
+Посмотрим, как это работает, и как это изменить при необходимости.
+
+## Pydantic‑модели для входа и выхода { #pydantic-models-for-input-and-output }
+
+Предположим, у вас есть Pydantic‑модель со значениями по умолчанию, как здесь:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
+
+### Модель для входа { #model-for-input }
+
+Если использовать эту модель как входную, как здесь:
+
+{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}
+
+…то поле `description` **не будет обязательным**, потому что у него значение по умолчанию `None`.
+
+### Входная модель в документации { #input-model-in-docs }
+
+В документации это видно: у поля `description` нет **красной звёздочки** — оно не отмечено как обязательное:
+
+
+
+
+
+
+
-
+
- Готовый к внедрению высокопроизводительный фреймворк, простой в изучении и разработке. + Фреймворк FastAPI: высокая производительность, прост в изучении, позволяет быстро писать код, готов к продакшн
--- -**Документация**: https://fastapi.tiangolo.com +**Документация**: https://fastapi.tiangolo.com **Исходный код**: https://github.com/fastapi/fastapi --- -FastAPI — это современный, быстрый (высокопроизводительный) веб-фреймворк для создания API используя Python, в основе которого лежит стандартная аннотация типов Python. +FastAPI — это современный, быстрый (высокопроизводительный) веб-фреймворк для создания API на Python, основанный на стандартных аннотациях типов Python. Ключевые особенности: -* **Скорость**: Очень высокая производительность, на уровне **NodeJS** и **Go** (благодаря Starlette и Pydantic). [Один из самых быстрых фреймворков Python](#_10). -* **Быстрота разработки**: Увеличьте скорость разработки примерно на 200–300%. * +* **Скорость**: Очень высокая производительность, на уровне **NodeJS** и **Go** (благодаря Starlette и Pydantic). [Один из самых быстрых доступных фреймворков Python](#performance). +* **Быстрота разработки**: Увеличьте скорость разработки фич примерно на 200–300%. * * **Меньше ошибок**: Сократите примерно на 40% количество ошибок, вызванных человеком (разработчиком). * -* **Интуитивно понятный**: Отличная поддержка редактора. Автозавершение везде. Меньше времени на отладку. -* **Лёгкость**: Разработан так, чтобы его было легко использовать и осваивать. Меньше времени на чтение документации. -* **Краткость**: Сведите к минимуму дублирование кода. Каждый объявленный параметр - определяет несколько функций. Меньше ошибок. -* **Надежность**: Получите готовый к работе код. С автоматической интерактивной документацией. -* **На основе стандартов**: Основан на открытых стандартах API и полностью совместим с ними: OpenAPI (ранее известном как Swagger) и JSON Schema. +* **Интуитивность**: Отличная поддержка редактора кода. Автозавершение везде. Меньше времени на отладку. +* **Простота**: Разработан так, чтобы его было легко использовать и осваивать. Меньше времени на чтение документации. +* **Краткость**: Минимизируйте дублирование кода. Несколько возможностей из каждого объявления параметров. Меньше ошибок. +* **Надежность**: Получите код, готовый к продакшн. С автоматической интерактивной документацией. +* **На основе стандартов**: Основан на открытых стандартах API и полностью совместим с ними: OpenAPI (ранее известный как Swagger) и JSON Schema. -* оценка на основе тестов внутренней команды разработчиков, создающих производственные приложения. +* оценка на основе тестов внутренней команды разработчиков, создающих продакшн-приложения. -## Спонсоры +## Спонсоры { #sponsors } -{% if sponsors %} +### Ключевой-спонсор { #keystone-sponsor } + +{% for sponsor in sponsors.keystone -%} +
+
-* Starlette для части связанной с вебом.
-* Pydantic для части связанной с данными.
+## **Typer**, FastAPI для CLI { #typer-the-fastapi-of-clis }
-## Установка
+
-uvicorn main:app --reload...fastapi dev main.py...email-validator - для проверки электронной почты.
+* email-validator — для проверки адресов электронной почты.
Используется Starlette:
-* HTTPX - Обязательно, если вы хотите использовать `TestClient`.
-* jinja2 - Обязательно, если вы хотите использовать конфигурацию шаблона по умолчанию.
-* python-multipart - Обязательно, если вы хотите поддерживать форму "парсинга" с помощью `request.form()`.
-* itsdangerous - Обязательно, для поддержки `SessionMiddleware`.
-* pyyaml - Обязательно, для поддержки `SchemaGenerator` Starlette (возможно, вам это не нужно с FastAPI).
+* httpx — обязателен, если вы хотите использовать `TestClient`.
+* jinja2 — обязателен, если вы хотите использовать конфигурацию шаблонов по умолчанию.
+* python-multipart - обязателен, если вы хотите поддерживать «парсинг» форм через `request.form()`.
+
+Используется FastAPI:
+
+* uvicorn — сервер, который загружает и «отдаёт» ваше приложение. Включает `uvicorn[standard]`, содержащий некоторые зависимости (например, `uvloop`), нужные для высокой производительности.
+* `fastapi-cli[standard]` — чтобы предоставить команду `fastapi`.
+ * Включает `fastapi-cloud-cli`, который позволяет развернуть ваше приложение FastAPI в FastAPI Cloud.
+
+### Без зависимостей `standard` { #without-standard-dependencies }
+
+Если вы не хотите включать опциональные зависимости `standard`, можно установить `pip install fastapi` вместо `pip install "fastapi[standard]"`.
+
+### Без `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
+
+Если вы хотите установить FastAPI со стандартными зависимостями, но без `fastapi-cloud-cli`, установите `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
+
+### Дополнительные опциональные зависимости { #additional-optional-dependencies }
+
+Есть дополнительные зависимости, которые вы можете установить.
+
+Дополнительные опциональные зависимости Pydantic:
-Используется FastAPI / Starlette:
+* pydantic-settings — для управления настройками.
+* pydantic-extra-types — дополнительные типы для использования с Pydantic.
-* uvicorn - сервер, который загружает и обслуживает ваше приложение.
-* orjson - Обязательно, если вы хотите использовать `ORJSONResponse`.
-* ujson - Обязательно, если вы хотите использовать `UJSONResponse`.
+Дополнительные опциональные зависимости FastAPI:
-Вы можете установить все это с помощью `pip install "fastapi[all]"`.
+* orjson — обязателен, если вы хотите использовать `ORJSONResponse`.
+* ujson — обязателен, если вы хотите использовать `UJSONResponse`.
-## Лицензия
+## Лицензия { #license }
Этот проект распространяется на условиях лицензии MIT.
diff --git a/docs/ru/docs/learn/index.md b/docs/ru/docs/learn/index.md
index b2e4cabc7..50fbd7738 100644
--- a/docs/ru/docs/learn/index.md
+++ b/docs/ru/docs/learn/index.md
@@ -1,4 +1,4 @@
-# Обучение
+# Обучение { #learn }
Здесь представлены вводные разделы и учебные пособия для изучения **FastAPI**.
diff --git a/docs/ru/docs/project-generation.md b/docs/ru/docs/project-generation.md
index efd6794ad..dbedf76fe 100644
--- a/docs/ru/docs/project-generation.md
+++ b/docs/ru/docs/project-generation.md
@@ -1,84 +1,28 @@
-# Генераторы проектов - Шаблоны
-
-Чтобы начать работу быстрее, Вы можете использовать "генераторы проектов", в которые включены множество начальных настроек для функций безопасности, баз данных и некоторые эндпоинты API.
-
-В генераторе проектов всегда будут предустановлены какие-то настройки, которые Вам следует обновить и подогнать под свои нужды, но это может быть хорошей отправной точкой для Вашего проекта.
-
-## Full Stack FastAPI PostgreSQL
-
-GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql
-
-### Full Stack FastAPI PostgreSQL - Особенности
-
-* Полностью интегрирован с **Docker** (основан на Docker).
-* Развёртывается в режиме Docker Swarm.
-* Интегрирован с **Docker Compose** и оптимизирован для локальной разработки.
-* **Готовый к реальной работе** веб-сервер Python использующий Uvicorn и Gunicorn.
-* Бэкенд построен на фреймворке **FastAPI**:
- * **Быстрый**: Высокопроизводительный, на уровне **NodeJS** и **Go** (благодаря Starlette и Pydantic).
- * **Интуитивно понятный**: Отличная поддержка редактора. Автодополнение кода везде. Меньше времени на отладку.
- * **Простой**: Разработан так, чтоб быть простым в использовании и изучении. Меньше времени на чтение документации.
- * **Лаконичный**: Минимизировано повторение кода. Каждый объявленный параметр определяет несколько функций.
- * **Надёжный**: Получите готовый к работе код. С автоматической интерактивной документацией.
- * **Стандартизированный**: Основан на открытых стандартах API (OpenAPI и JSON Schema) и полностью совместим с ними.
- * **Множество других возможностей** включая автоматическую проверку и сериализацию данных, интерактивную документацию, аутентификацию с помощью OAuth2 JWT-токенов и т.д.
-* **Безопасное хранение паролей**, которые хэшируются по умолчанию.
-* Аутентификация посредством **JWT-токенов**.
-* Модели **SQLAlchemy** (независящие от расширений Flask, а значит могут быть непосредственно использованы процессами Celery).
-* Базовая модель пользователя (измените или удалите её по необходимости).
-* **Alembic** для организации миграций.
-* **CORS** (Совместное использование ресурсов из разных источников).
-* **Celery**, процессы которого могут выборочно импортировать и использовать модели и код из остальной части бэкенда.
-* Тесты, на основе **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**.
- * Сервер Docker основан на **Nginx** (настроен для удобной работы с Vue-router).
- * Многоступенчатая сборка Docker, то есть Вам не нужно сохранять или коммитить скомпилированный код.
- * Тесты фронтенда запускаются во время сборки (можно отключить).
- * Сделан настолько модульно, насколько возможно, поэтому работает "из коробки", но Вы можете повторно сгенерировать фронтенд с помощью Vue CLI или создать то, что Вам нужно и повторно использовать то, что захотите.
-* **PGAdmin** для СУБД PostgreSQL, которые легко можно заменить на PHPMyAdmin и MySQL.
-* **Flower** для отслеживания работы Celery.
-* Балансировка нагрузки между фронтендом и бэкендом с помощью **Traefik**, а значит, Вы можете расположить их на одном домене, разделив url-пути, так как они обслуживаются разными контейнерами.
-* Интеграция с Traefik включает автоматическую генерацию сертификатов Let's Encrypt для поддержки протокола **HTTPS**.
-* GitLab **CI** (непрерывная интеграция), которая включает тестирование фронтенда и бэкенда.
-
-## Full Stack FastAPI Couchbase
-
-GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase
-
-⚠️ **ПРЕДУПРЕЖДЕНИЕ** ⚠️
-
-Если Вы начинаете новый проект, ознакомьтесь с представленными здесь альтернативами.
-
-Например, генератор проектов Full Stack FastAPI PostgreSQL может быть более подходящей альтернативой, так как он активно поддерживается и используется. И он включает в себя все новые возможности и улучшения.
-
-Но никто не запрещает Вам использовать генератор с СУБД Couchbase, возможно, он всё ещё работает нормально. Или у Вас уже есть проект, созданный с помощью этого генератора ранее, и Вы, вероятно, уже обновили его в соответствии со своими потребностями.
-
-Вы можете прочитать о нём больше в документации соответствующего репозитория.
-
-## Full Stack FastAPI MongoDB
-
-...может быть когда-нибудь появится, в зависимости от наличия у меня свободного времени и прочих факторов. 😅 🎉
-
-## Модели машинного обучения на основе spaCy и FastAPI
-
-GitHub: https://github.com/microsoft/cookiecutter-spacy-fastapi
-
-### Модели машинного обучения на основе spaCy и FastAPI - Особенности
-
-* Интеграция с моделями **spaCy** NER.
-* Встроенный формат запросов к **когнитивному поиску Azure**.
-* **Готовый к реальной работе** веб-сервер Python использующий Uvicorn и Gunicorn.
-* Встроенное развёртывание на основе **Azure DevOps** Kubernetes (AKS) CI/CD.
-* **Многоязычность**. Лёгкий выбор одного из встроенных в spaCy языков во время настройки проекта.
-* **Легко подключить** модели из других фреймворков (Pytorch, Tensorflow) не ограничиваясь spaCy.
+# Шаблон Full Stack FastAPI { #full-stack-fastapi-template }
+
+Шаблоны, хотя обычно поставляются с определённой конфигурацией, спроектированы так, чтобы быть гибкими и настраиваемыми. Это позволяет вам изменять их и адаптировать под требования вашего проекта, что делает их отличной отправной точкой. 🏁
+
+Вы можете использовать этот шаблон для старта: в нём уже сделана значительная часть начальной настройки, безопасность, база данных и несколько эндпоинтов API.
+
+Репозиторий GitHub: Full Stack FastAPI Template
+
+## Шаблон Full Stack FastAPI — Технологический стек и возможности { #full-stack-fastapi-template-technology-stack-and-features }
+
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com/ru) для бэкенд‑API на Python.
+ - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) для взаимодействия с SQL‑базой данных на Python (ORM).
+ - 🔍 [Pydantic](https://docs.pydantic.dev), используется FastAPI, для валидации данных и управления настройками.
+ - 💾 [PostgreSQL](https://www.postgresql.org) в качестве SQL‑базы данных.
+- 🚀 [React](https://react.dev) для фронтенда.
+ - 💃 Используются TypeScript, хуки, Vite и другие части современного фронтенд‑стека.
+ - 🎨 [Tailwind CSS](https://tailwindcss.com) и [shadcn/ui](https://ui.shadcn.com) для компонентов фронтенда.
+ - 🤖 Автоматически сгенерированный фронтенд‑клиент.
+ - 🧪 [Playwright](https://playwright.dev) для End‑to‑End тестирования.
+ - 🦇 Поддержка тёмной темы.
+- 🐋 [Docker Compose](https://www.docker.com) для разработки и продакшна.
+- 🔒 Безопасное хэширование паролей по умолчанию.
+- 🔑 Аутентификация по JWT‑токенам.
+- 📫 Восстановление пароля по электронной почте.
+- ✅ Тесты с [Pytest](https://pytest.org).
+- 📞 [Traefik](https://traefik.io) в роли обратного прокси / балансировщика нагрузки.
+- 🚢 Инструкции по развёртыванию с использованием Docker Compose, включая настройку фронтенд‑прокси Traefik для автоматического получения сертификатов HTTPS.
+- 🏭 CI (continuous integration) и CD (continuous deployment) на основе GitHub Actions.
diff --git a/docs/ru/docs/python-types.md b/docs/ru/docs/python-types.md
index b1d4715fd..ae4a1e2b7 100644
--- a/docs/ru/docs/python-types.md
+++ b/docs/ru/docs/python-types.md
@@ -1,29 +1,28 @@
-# Введение в аннотации типов Python
+# Введение в типы Python { #python-types-intro }
-Python имеет поддержку необязательных аннотаций типов.
+Python поддерживает необязательные «подсказки типов» (их также называют «аннотациями типов»).
-**Аннотации типов** являются специальным синтаксисом, который позволяет определять тип переменной.
+Эти **«подсказки типов»** или аннотации — это специальный синтаксис, позволяющий объявлять тип переменной.
-Объявление типов для переменных позволяет улучшить поддержку вашего кода редакторами и различными инструментами.
+Объявляя типы для ваших переменных, редакторы кода и инструменты смогут лучше вас поддерживать.
-Это просто **краткое руководство / напоминание** об аннотациях типов в Python. Оно охватывает только минимум, необходимый для их использования с **FastAPI**... что на самом деле очень мало.
+Это всего лишь **краткое руководство / напоминание** о подсказках типов в Python. Оно охватывает только минимум, необходимый для их использования с **FastAPI**... что на самом деле очень мало.
-**FastAPI** целиком основан на аннотациях типов, у них много выгод и преимуществ.
+**FastAPI** целиком основан на этих подсказках типов — они дают ему множество преимуществ и выгод.
Но даже если вы никогда не используете **FastAPI**, вам будет полезно немного узнать о них.
-/// note
+/// note | Примечание
-Если вы являетесь экспертом в Python и уже знаете всё об аннотациях типов, переходите к следующему разделу.
+Если вы являетесь экспертом в Python и уже знаете всё о подсказках типов, переходите к следующей главе.
///
-## Мотивация
+## Мотивация { #motivation }
Давайте начнем с простого примера:
-{* ../../docs_src/python_types/tutorial001.py *}
-
+{* ../../docs_src/python_types/tutorial001_py39.py *}
Вызов этой программы выводит:
@@ -34,13 +33,12 @@ John Doe
Функция делает следующее:
* Принимает `first_name` и `last_name`.
-* Преобразует первую букву содержимого каждой переменной в верхний регистр с `title()`.
-* Соединяет их через пробел.
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+* Преобразует первую букву каждого значения в верхний регистр с помощью `title()`.
+* Соединяет их пробелом посередине.
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
-### Отредактируем пример
+### Отредактируем пример { #edit-it }
Это очень простая программа.
@@ -48,23 +46,23 @@ John Doe
В какой-то момент вы бы начали определение функции, у вас были бы готовы параметры...
-Но затем вы должны вызвать «тот метод, который преобразует первую букву в верхний регистр».
+Но затем нужно вызвать «тот метод, который делает первую букву заглавной».
-Было это `upper`? Или `uppercase`? `first_uppercase`? `capitalize`?
+Это был `upper`? Или `uppercase`? `first_uppercase`? `capitalize`?
-Тогда вы попробуете с давним другом программиста: автодополнением редактора.
+Тогда вы пробуете старого друга программиста — автозавершение редактора кода.
-Вы вводите первый параметр функции, `first_name`, затем точку (`.`), а затем нажимаете `Ctrl+Space`, чтобы запустить дополнение.
+Вы вводите первый параметр функции, `first_name`, затем точку (`.`) и нажимаете `Ctrl+Space`, чтобы вызвать автозавершение.
-Но, к сожалению, ничего полезного не выходит:
+Но, к сожалению, ничего полезного не находится:
-### Добавим типы
+### Добавим типы { #add-types }
-Давайте изменим одну строчку в предыдущей версии.
+Давайте изменим одну строку из предыдущей версии.
-Мы изменим именно этот фрагмент, параметры функции, с:
+Мы поменяем ровно этот фрагмент — параметры функции — с:
```Python
first_name, last_name
@@ -76,14 +74,13 @@ John Doe
first_name: str, last_name: str
```
-Вот и все.
-
-Это аннотации типов:
+Вот и всё.
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+Это и есть «подсказки типов»:
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
-Это не то же самое, что объявление значений по умолчанию, например:
+Это не то же самое, что объявление значений по умолчанию, как, например:
```Python
first_name="john", last_name="doe"
@@ -91,192 +88,314 @@ John Doe
Это другая вещь.
-Мы используем двоеточия (`:`), а не равно (`=`).
+Здесь мы используем двоеточия (`:`), а не знак равенства (`=`).
-И добавление аннотаций типов обычно не меняет происходящего по сравнению с тем, что произошло бы без неё.
+И добавление подсказок типов обычно не меняет поведение программы по сравнению с вариантом без них.
-Но теперь представьте, что вы снова находитесь в процессе создания этой функции, но уже с аннотациями типов.
+Но теперь представьте, что вы снова посередине написания этой функции, только уже с подсказками типов.
-В тот же момент вы пытаетесь запустить автодополнение с помощью `Ctrl+Space` и вы видите:
+В тот же момент вы пробуете вызвать автозавершение с помощью `Ctrl+Space` — и видите:
-При этом вы можете просматривать варианты, пока не найдёте подходящий:
+С этим вы можете прокручивать варианты, пока не найдёте тот самый:
-## Больше мотивации
+## Больше мотивации { #more-motivation }
-Проверьте эту функцию, она уже имеет аннотации типов:
+Посмотрите на эту функцию — у неё уже есть подсказки типов:
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
-
-Поскольку редактор знает типы переменных, вы получаете не только дополнение, но и проверки ошибок:
+Так как редактор кода знает типы переменных, вы получаете не только автозавершение, но и проверки ошибок:
-Теперь вы знаете, что вам нужно исправить, преобразовав `age` в строку с `str(age)`:
-
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+Теперь вы знаете, что нужно исправить — преобразовать `age` в строку с помощью `str(age)`:
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
-## Объявление типов
+## Объявление типов { #declaring-types }
-Вы только что видели основное место для объявления подсказок типов. В качестве параметров функции.
+Вы только что увидели основное место, где объявляют подсказки типов — параметры функции.
-Это также основное место, где вы можете использовать их с **FastAPI**.
+Это также основное место, где вы будете использовать их с **FastAPI**.
-### Простые типы
+### Простые типы { #simple-types }
-Вы можете объявить все стандартные типы Python, а не только `str`.
+Вы можете объявлять все стандартные типы Python, не только `str`.
-Вы можете использовать, к примеру:
+Можно использовать, например:
* `int`
* `float`
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
+### Generic-типы с параметрами типов { #generic-types-with-type-parameters }
-### Generic-типы с параметрами типов
+Есть структуры данных, которые могут содержать другие значения, например, `dict`, `list`, `set` и `tuple`. И внутренние значения тоже могут иметь свой тип.
-Существуют некоторые структуры данных, которые могут содержать другие значения, например, `dict`, `list`, `set` и `tuple`. И внутренние значения тоже могут иметь свой тип.
+Такие типы, которые содержат внутренние типы, называют «**generic**»-типами. И их можно объявлять, в том числе с указанием внутренних типов.
-Чтобы объявить эти типы и внутренние типы, вы можете использовать стандартный Python-модуль `typing`.
+Чтобы объявлять эти типы и их внутренние типы, вы можете использовать стандартный модуль Python `typing`. Он существует специально для поддержки подсказок типов.
-Он существует специально для поддержки подсказок этих типов.
+#### Новые версии Python { #newer-versions-of-python }
-#### `List`
+Синтаксис с использованием `typing` **совместим** со всеми версиями, от Python 3.6 до самых новых, включая Python 3.9, Python 3.10 и т.д.
-Например, давайте определим переменную как `list`, состоящий из `str`.
+По мере развития Python **новые версии** получают улучшенную поддержку этих аннотаций типов, и во многих случаях вам даже не нужно импортировать и использовать модуль `typing`, чтобы объявлять аннотации типов.
-Импортируйте `List` из `typing` (с заглавной `L`):
+Если вы можете выбрать более свежую версию Python для проекта, вы получите дополнительную простоту.
-{* ../../docs_src/python_types/tutorial006.py hl[1] *}
+Во всей документации есть примеры, совместимые с каждой версией Python (когда есть различия).
+Например, «**Python 3.6+**» означает совместимость с Python 3.6 и выше (включая 3.7, 3.8, 3.9, 3.10 и т.д.). А «**Python 3.9+**» — совместимость с Python 3.9 и выше (включая 3.10 и т.п.).
-Объявите переменную с тем же синтаксисом двоеточия (`:`).
+Если вы можете использовать **последние версии Python**, используйте примеры для самой новой версии — у них будет **самый лучший и простой синтаксис**, например, «**Python 3.10+**».
-В качестве типа укажите `List`.
+#### List { #list }
-Поскольку список является типом, содержащим некоторые внутренние типы, вы помещаете их в квадратные скобки:
+Например, давайте определим переменную как `list` из `str`.
-{* ../../docs_src/python_types/tutorial006.py hl[4] *}
+Объявите переменную с тем же синтаксисом двоеточия (`:`).
+
+В качестве типа укажите `list`.
+
+Так как список — это тип, содержащий внутренние типы, укажите их в квадратных скобках:
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
-/// tip
+/// info | Информация
Эти внутренние типы в квадратных скобках называются «параметрами типов».
-В этом случае `str` является параметром типа, передаваемым в `List`.
+В данном случае `str` — это параметр типа, передаваемый в `list`.
///
-Это означает: "переменная `items` является `list`, и каждый из элементов этого списка является `str`".
+Это означает: «переменная `items` — это `list`, и каждый элемент этого списка — `str`».
-Если вы будете так поступать, редактор может оказывать поддержку даже при обработке элементов списка:
+Таким образом, ваш редактор кода сможет помогать даже при обработке элементов списка:
-Без типов добиться этого практически невозможно.
+Без типов добиться этого почти невозможно.
-Обратите внимание, что переменная `item` является одним из элементов списка `items`.
+Обратите внимание, что переменная `item` — один из элементов списка `items`.
-И все же редактор знает, что это `str`, и поддерживает это.
+И всё же редактор кода знает, что это `str`, и даёт соответствующую поддержку.
-#### `Tuple` и `Set`
+#### Tuple и Set { #tuple-and-set }
-Вы бы сделали то же самое, чтобы объявить `tuple` и `set`:
-
-{* ../../docs_src/python_types/tutorial007.py hl[1,4] *}
+Аналогично вы бы объявили `tuple` и `set`:
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
Это означает:
-* Переменная `items_t` является `tuple` с 3 элементами: `int`, другим `int` и `str`.
-* Переменная `items_s` является `set` и каждый элемент имеет тип `bytes`.
-
-#### `Dict`
+* Переменная `items_t` — это `tuple` из 3 элементов: `int`, ещё один `int` и `str`.
+* Переменная `items_s` — это `set`, и каждый элемент имеет тип `bytes`.
-Чтобы определить `dict`, вы передаёте 2 параметра типов, разделённых запятыми.
+#### Dict { #dict }
-Первый параметр типа предназначен для ключей `dict`.
+Чтобы определить `dict`, вы передаёте 2 параметра типов, разделённые запятой.
-Второй параметр типа предназначен для значений `dict`:
+Первый параметр типа — для ключей `dict`.
-{* ../../docs_src/python_types/tutorial008.py hl[1,4] *}
+Второй параметр типа — для значений `dict`:
+{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *}
Это означает:
-* Переменная `prices` является `dict`:
- * Ключи этого `dict` имеют тип `str` (скажем, название каждого элемента).
+* Переменная `prices` — это `dict`:
+ * Ключи этого `dict` имеют тип `str` (скажем, название каждой позиции).
* Значения этого `dict` имеют тип `float` (скажем, цена каждой позиции).
-#### `Optional`
+#### Union { #union }
+
+Вы можете объявить, что переменная может быть **одним из нескольких типов**, например, `int` или `str`.
-Вы также можете использовать `Optional`, чтобы объявить, что переменная имеет тип, например, `str`, но это является «необязательным», что означает, что она также может быть `None`:
+В Python 3.6 и выше (включая Python 3.10) вы можете использовать тип `Union` из `typing` и перечислить в квадратных скобках все допустимые типы.
+
+В Python 3.10 также появился **новый синтаксис**, где допустимые типы можно указать через вертикальную черту (`|`).
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
+```
+
+////
+
+В обоих случаях это означает, что `item` может быть `int` или `str`.
+
+#### Возможно `None` { #possibly-none }
+
+Вы можете объявить, что значение может иметь определённый тип, например `str`, но также может быть и `None`.
+
+В Python 3.6 и выше (включая Python 3.10) это можно объявить, импортировав и используя `Optional` из модуля `typing`.
+
+```Python hl_lines="1 4"
+{!../../docs_src/python_types/tutorial009_py39.py!}
+```
+
+Использование `Optional[str]` вместо просто `str` позволит редактору кода помочь вам обнаружить ошибки, когда вы предполагаете, что значение всегда `str`, хотя на самом деле оно может быть и `None`.
+
+`Optional[Something]` — это на самом деле сокращение для `Union[Something, None]`, они эквивалентны.
+
+Это также означает, что в Python 3.10 вы можете использовать `Something | None`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
+```
+
+////
+
+//// tab | Python 3.9+ альтернативный вариант
+
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
+```
+
+////
+
+#### Использовать `Union` или `Optional` { #using-union-or-optional }
+
+Если вы используете версию Python ниже 3.10, вот совет с моей весьма **субъективной** точки зрения:
+
+* 🚨 Избегайте использования `Optional[SomeType]`
+* Вместо этого ✨ **используйте `Union[SomeType, None]`** ✨.
+
+Оба варианта эквивалентны и внутри одинаковы, но я бы рекомендовал `Union` вместо `Optional`, потому что слово «**optional**» («необязательный») может навести на мысль, что значение необязательное, хотя на самом деле оно означает «может быть `None`», даже если параметр не является необязательным и всё ещё обязателен.
+
+Мне кажется, `Union[SomeType, None]` более явно выражает смысл.
+
+Речь только о словах и названиях. Но эти слова могут влиять на то, как вы и ваши коллеги думаете о коде.
+
+В качестве примера возьмём эту функцию:
+
+{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *}
+
+Параметр `name` определён как `Optional[str]`, но он **не необязательный** — вы не можете вызвать функцию без этого параметра:
+
+```Python
+say_hi() # О нет, это вызывает ошибку! 😱
+```
+
+Параметр `name` всё ещё **обязателен** (не *optional*), потому что у него нет значения по умолчанию. При этом `name` принимает `None` как значение:
+
+```Python
+say_hi(name=None) # Это работает, None допустим 🎉
```
-Использование `Optional[str]` вместо просто `str` позволит редактору помочь вам в обнаружении ошибок, в которых вы могли бы предположить, что значение всегда является `str`, хотя на самом деле это может быть и `None`.
+Хорошая новость: как только вы перейдёте на Python 3.10, об этом можно не переживать — вы сможете просто использовать `|` для объединения типов:
-#### Generic-типы
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
-Эти типы принимают параметры в квадратных скобках:
+И тогда вам не придётся задумываться о названиях вроде `Optional` и `Union`. 😎
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
+#### Generic-типы { #generic-types }
+
+Типы, которые принимают параметры типов в квадратных скобках, называются **Generic-типами** или **Generics**, например:
+
+//// tab | Python 3.10+
+
+Вы можете использовать те же встроенные типы как generics (с квадратными скобками и типами внутри):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+И, как и в предыдущих версиях Python, из модуля `typing`:
+
+* `Union`
* `Optional`
-* ...и др.
+* ...и другие.
-называются **Generic-типами** или **Generics**.
+В Python 3.10, как альтернативу generics `Union` и `Optional`, можно использовать вертикальную черту (`|`) для объявления объединений типов — это гораздо лучше и проще.
-### Классы как типы
+////
-Вы также можете объявить класс как тип переменной.
+//// tab | Python 3.9+
-Допустим, у вас есть класс `Person` с полем `name`:
+Вы можете использовать те же встроенные типы как generics (с квадратными скобками и типами внутри):
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
+* `list`
+* `tuple`
+* `set`
+* `dict`
+И generics из модуля `typing`:
-Тогда вы можете объявить переменную типа `Person`:
+* `Union`
+* `Optional`
+* ...и другие.
+
+////
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
+### Классы как типы { #classes-as-types }
+Вы также можете объявлять класс как тип переменной.
-И снова вы получаете полную поддержку редактора:
+Допустим, у вас есть класс `Person` с именем:
+
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
+
+Тогда вы можете объявить переменную типа `Person`:
+
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
+
+И снова вы получите полную поддержку редактора кода:
-## Pydantic-модели
+Обратите внимание, что это означает: «`one_person` — это **экземпляр** класса `Person`».
-Pydantic является Python-библиотекой для выполнения валидации данных.
+Это не означает: «`one_person` — это **класс** с именем `Person`».
-Вы объявляете «форму» данных как классы с атрибутами.
+## Pydantic-модели { #pydantic-models }
-И каждый атрибут имеет тип.
+Pydantic — это библиотека Python для валидации данных.
-Затем вы создаете экземпляр этого класса с некоторыми значениями, и он проверяет значения, преобразует их в соответствующий тип (если все верно) и предоставляет вам объект со всеми данными.
+Вы объявляете «форму» данных как классы с атрибутами.
+
+И у каждого атрибута есть тип.
-И вы получаете полную поддержку редактора для этого итогового объекта.
+Затем вы создаёте экземпляр этого класса с некоторыми значениями — он провалидирует значения, преобразует их к соответствующему типу (если это применимо) и вернёт вам объект со всеми данными.
-Взято из официальной документации Pydantic:
+И вы получите полную поддержку редактора кода для этого результирующего объекта.
-{* ../../docs_src/python_types/tutorial011.py *}
+Пример из официальной документации Pydantic:
+{* ../../docs_src/python_types/tutorial011_py310.py *}
-/// info
+/// info | Информация
-Чтобы узнать больше о Pydantic, читайте его документацию.
+Чтобы узнать больше о Pydantic, ознакомьтесь с его документацией.
///
@@ -284,30 +403,62 @@ John Doe
Вы увидите намного больше всего этого на практике в [Руководстве пользователя](tutorial/index.md){.internal-link target=_blank}.
-## Аннотации типов в **FastAPI**
+/// tip | Совет
+
+У Pydantic есть особое поведение, когда вы используете `Optional` или `Union[Something, None]` без значения по умолчанию. Подробнее читайте в документации Pydantic: Required Optional fields.
+
+///
+
+## Подсказки типов с аннотациями метаданных { #type-hints-with-metadata-annotations }
+
+В Python также есть возможность добавлять **дополнительные метаданные** к подсказкам типов с помощью `Annotated`.
+
+Начиная с Python 3.9, `Annotated` входит в стандартную библиотеку, поэтому вы можете импортировать его из `typing`.
+
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
+
+Сам Python ничего не делает с `Annotated`. А для редакторов кода и других инструментов тип по-прежнему `str`.
+
+Но вы можете использовать это место в `Annotated`, чтобы передать **FastAPI** дополнительные метаданные о том, как вы хотите, чтобы ваше приложение себя вело.
+
+Важно помнить, что **первый параметр типа**, который вы передаёте в `Annotated`, — это **фактический тип**. Всё остальное — просто метаданные для других инструментов.
+
+Пока вам достаточно знать, что `Annotated` существует и это — стандартный Python. 😎
+
+Позже вы увидите, насколько это **мощно**.
+
+/// tip | Совет
+
+Тот факт, что это **стандартный Python**, означает, что вы по-прежнему получите **лучший возможный разработческий опыт** в вашем редакторе кода, с инструментами для анализа и рефакторинга кода и т.д. ✨
+
+А ещё ваш код будет очень совместим со множеством других инструментов и библиотек Python. 🚀
+
+///
+
+## Аннотации типов в **FastAPI** { #type-hints-in-fastapi }
-**FastAPI** получает преимущества аннотаций типов для выполнения определённых задач.
+**FastAPI** использует эти подсказки типов для выполнения нескольких задач.
-С **FastAPI** вы объявляете параметры с аннотациями типов и получаете:
+С **FastAPI** вы объявляете параметры с подсказками типов и получаете:
-* **Поддержку редактора**.
+* **Поддержку редактора кода**.
* **Проверки типов**.
-...и **FastAPI** использует тот же механизм для:
+...и **FastAPI** использует эти же объявления для:
-* **Определения требований**: из параметров пути запроса, параметров запроса, заголовков, зависимостей и т.д.
-* **Преобразования данных**: от запроса к нужному типу.
-* **Валидации данных**: исходя из каждого запроса:
- * Генерации **автоматических ошибок**, возвращаемых клиенту, когда данные не являются корректными.
+* **Определения требований**: из path-параметров пути запроса, query-параметров, HTTP-заголовков, тел запросов, зависимостей и т.д.
+* **Преобразования данных**: из HTTP-запроса к требуемому типу.
+* **Валидации данных**: приходящих с каждого HTTP-запроса:
+ * Генерации **автоматических ошибок**, возвращаемых клиенту, когда данные некорректны.
* **Документирования** API с использованием OpenAPI:
- * который затем используется пользовательскими интерфейсами автоматической интерактивной документации.
+ * что затем используется пользовательскими интерфейсами автоматической интерактивной документации.
-Всё это может показаться абстрактным. Не волнуйтесь. Вы увидите всё это в действии в [Руководстве пользователя](tutorial/index.md){.internal-link target=_blank}.
+Всё это может звучать абстрактно. Не волнуйтесь. Вы увидите всё это в действии в [Руководстве пользователя](tutorial/index.md){.internal-link target=_blank}.
-Важно то, что при использовании стандартных типов Python в одном месте (вместо добавления дополнительных классов, декораторов и т.д.) **FastAPI** сделает за вас большую часть работы.
+Важно то, что, используя стандартные типы Python в одном месте (вместо добавления дополнительных классов, декораторов и т.д.), **FastAPI** сделает за вас большую часть работы.
-/// info
+/// info | Информация
-Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом является «шпаргалка» от `mypy`.
+Если вы уже прошли всё руководство и вернулись, чтобы узнать больше о типах, хорошим ресурсом будет «шпаргалка» от `mypy`.
///
diff --git a/docs/ru/docs/resources/index.md b/docs/ru/docs/resources/index.md
new file mode 100644
index 000000000..faf80f7f4
--- /dev/null
+++ b/docs/ru/docs/resources/index.md
@@ -0,0 +1,3 @@
+# Ресурсы { #resources }
+
+Дополнительные ресурсы, внешние ссылки и многое другое. ✈️
diff --git a/docs/ru/docs/tutorial/background-tasks.md b/docs/ru/docs/tutorial/background-tasks.md
index bf2e9dec3..8d7b7442f 100644
--- a/docs/ru/docs/tutorial/background-tasks.md
+++ b/docs/ru/docs/tutorial/background-tasks.md
@@ -1,84 +1,84 @@
-# Фоновые задачи
+# Фоновые задачи { #background-tasks }
-Вы можете создавать фоновые задачи, которые будут выполнятся *после* возвращения ответа сервером.
+Вы можете создавать фоновые задачи, которые будут выполняться после возврата ответа.
-Это может быть полезно для функций, которые должны выполниться после получения запроса, но ожидание их выполнения необязательно для пользователя.
+Это полезно для операций, которые должны произойти после HTTP-запроса, но клиенту не обязательно ждать их завершения, чтобы получить ответ.
-К примеру:
+Например:
-* Отправка писем на почту после выполнения каких-либо действий:
- * Т.к. соединение с почтовым сервером и отправка письма идут достаточно "долго" (несколько секунд), вы можете отправить ответ пользователю, а отправку письма выполнить в фоне.
+* Уведомления по электронной почте, отправляемые после выполнения действия:
+ * Так как подключение к почтовому серверу и отправка письма обычно «медленные» (несколько секунд), вы можете сразу вернуть ответ, а отправку уведомления выполнить в фоне.
* Обработка данных:
- * К примеру, если вы получаете файл, который должен пройти через медленный процесс, вы можете отправить ответ "Accepted" (HTTP 202) и отправить работу с файлом в фон.
+ * Например, если вы получаете файл, который должен пройти через медленный процесс, вы можете вернуть ответ «Accepted» (HTTP 202) и обработать файл в фоне.
-## Использование класса `BackgroundTasks`
+## Использование `BackgroundTasks` { #using-backgroundtasks }
-Сначала импортируйте `BackgroundTasks`, потом добавьте в функцию параметр с типом `BackgroundTasks`:
+Сначала импортируйте `BackgroundTasks` и объявите параметр в вашей функции‑обработчике пути с типом `BackgroundTasks`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
-**FastAPI** создаст объект класса `BackgroundTasks` для вас и запишет его в параметр.
+**FastAPI** создаст объект типа `BackgroundTasks` для вас и передаст его через этот параметр.
-## Создание функции для фоновой задачи
+## Создание функции для фоновой задачи { #create-a-task-function }
-Создайте функцию, которую хотите запустить в фоне.
+Создайте функцию, которую нужно запустить как фоновую задачу.
-Это совершенно обычная функция, которая может принимать параметры.
+Это обычная функция, которая может принимать параметры.
-Она может быть как асинхронной `async def`, так и обычной `def` функцией, **FastAPI** знает, как правильно ее выполнить.
+Это может быть как `async def`, так и обычная функция `def`, **FastAPI** знает, как корректно её выполнить.
-В нашем примере фоновая задача будет вести запись в файл (симулируя отправку письма).
+В этом случае функция задачи будет записывать данные в файл (имитируя отправку письма).
-Так как операция записи не использует `async` и `await`, мы определим ее как обычную `def`:
+Так как операция записи не использует `async` и `await`, мы определим функцию как обычную `def`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
-## Добавление фоновой задачи
+## Добавление фоновой задачи { #add-the-background-task }
-Внутри функции вызовите метод `.add_task()` у объекта *background tasks* и передайте ему функцию, которую хотите выполнить в фоне:
+Внутри вашей функции‑обработчика пути передайте функцию задачи объекту фоновых задач методом `.add_task()`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
`.add_task()` принимает следующие аргументы:
-* Функцию, которая будет выполнена в фоне (`write_notification`). Обратите внимание, что передается объект функции, без скобок.
-* Любое упорядоченное количество аргументов, которые принимает функция (`email`).
-* Любое количество именованных аргументов, которые принимает функция (`message="some notification"`).
+* Функцию задачи, которую нужно выполнить в фоне (`write_notification`).
+* Последовательность позиционных аргументов, которые должны быть переданы функции задачи, в порядке (`email`).
+* Любые именованные аргументы, которые должны быть переданы функции задачи (`message="some notification"`).
-## Встраивание зависимостей
+## Встраивание зависимостей { #dependency-injection }
-Класс `BackgroundTasks` также работает с системой встраивания зависимостей, вы можете определить `BackgroundTasks` на разных уровнях: как параметр функции, как завимость, как подзависимость и так далее.
+Использование `BackgroundTasks` также работает с системой встраивания зависимостей, вы можете объявить параметр типа `BackgroundTasks` на нескольких уровнях: в функции‑обработчике пути, в зависимости (dependable), в подзависимости и т. д.
-**FastAPI** знает, что нужно сделать в каждом случае и как переиспользовать тот же объект `BackgroundTasks`, так чтобы все фоновые задачи собрались и запустились вместе в фоне:
+**FastAPI** знает, что делать в каждом случае и как переиспользовать один и тот же объект, так чтобы все фоновые задачи были объединены и затем выполнены в фоне:
-{* ../../docs_src/background_tasks/tutorial002_py310.py hl[11,13,20,23] *}
+{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
-В этом примере сообщения будут записаны в `log.txt` *после* того, как ответ сервера был отправлен.
+В этом примере сообщения будут записаны в файл `log.txt` после отправки ответа.
-Если бы в запрос был передан query-параметр `q`, он бы первыми записался в `log.txt` фоновой задачей (потому что вызывается в зависимости `get_query`).
+Если в запросе была строка запроса (query), она будет записана в лог фоновой задачей.
-После другая фоновая задача, которая была сгенерирована в функции, запишет сообщение из параметра `email`.
+Затем другая фоновая задача, созданная в функции‑обработчике пути, запишет сообщение, используя path‑параметр `email`.
-## Технические детали
+## Технические детали { #technical-details }
-Класс `BackgroundTasks` основан на `starlette.background`.
+Класс `BackgroundTasks` приходит напрямую из `starlette.background`.
-Он интегрирован в FastAPI, так что вы можете импортировать его прямо из `fastapi` и избежать случайного импорта `BackgroundTask` (без `s` на конце) из `starlette.background`.
+Он импортируется/включается прямо в FastAPI, чтобы вы могли импортировать его из `fastapi` и избежать случайного импорта альтернативного `BackgroundTask` (без `s` на конце) из `starlette.background`.
-При использовании `BackgroundTasks` (а не `BackgroundTask`), вам достаточно только определить параметр функции с типом `BackgroundTasks` и **FastAPI** сделает все за вас, также как при использовании объекта `Request`.
+Используя только `BackgroundTasks` (а не `BackgroundTask`), его можно применять как параметр функции‑обработчика пути, и **FastAPI** сделает остальное за вас, как при использовании объекта `Request` напрямую.
-Вы все равно можете использовать `BackgroundTask` из `starlette` в FastAPI, но вам придется самостоятельно создавать объект фоновой задачи и вручную обработать `Response` внутри него.
+По‑прежнему можно использовать один `BackgroundTask` в FastAPI, но тогда вам нужно создать объект в своём коде и вернуть Starlette `Response`, включающий его.
-Вы можете подробнее изучить его в Официальной документации Starlette для BackgroundTasks.
+Подробнее см. в официальной документации Starlette по фоновым задачам.
-## Предостережение
+## Предостережение { #caveat }
-Если вам нужно выполнить тяжелые вычисления в фоне, которым необязательно быть запущенными в одном процессе с приложением **FastAPI** (к примеру, вам не нужны обрабатываемые переменные или вы не хотите делиться памятью процесса и т.д.), вы можете использовать более серьезные инструменты, такие как Celery.
+Если вам нужно выполнять тяжелые вычисления в фоне, и при этом они не обязательно должны запускаться тем же процессом (например, вам не нужно делиться памятью, переменными и т. п.), вам могут подойти более мощные инструменты, такие как Celery.
-Их тяжелее настраивать, также им нужен брокер сообщений наподобие RabbitMQ или Redis, но зато они позволяют вам запускать фоновые задачи в нескольких процессах и даже на нескольких серверах.
+Они обычно требуют более сложной конфигурации, менеджера очереди сообщений/заданий (например, RabbitMQ или Redis), но позволяют запускать фоновые задачи в нескольких процессах и, что особенно важно, на нескольких серверах.
-Но если вам нужен доступ к общим переменным и объектам вашего **FastAPI** приложения или вам нужно выполнять простые фоновые задачи (наподобие отправки письма из примера) вы можете просто использовать `BackgroundTasks`.
+Но если вам нужен доступ к переменным и объектам из того же приложения **FastAPI**, или нужно выполнять небольшие фоновые задачи (например, отправку email‑уведомления), вы можете просто использовать `BackgroundTasks`.
-## Резюме
+## Резюме { #recap }
-Для создания фоновых задач вам необходимо импортировать `BackgroundTasks` и добавить его в функцию, как параметр с типом `BackgroundTasks`.
+Импортируйте и используйте `BackgroundTasks` с параметрами в функциях‑обработчиках пути и зависимостях, чтобы добавлять фоновые задачи.
diff --git a/docs/ru/docs/tutorial/bigger-applications.md b/docs/ru/docs/tutorial/bigger-applications.md
index 8b9080d39..76304523c 100644
--- a/docs/ru/docs/tutorial/bigger-applications.md
+++ b/docs/ru/docs/tutorial/bigger-applications.md
@@ -1,4 +1,4 @@
-# Большие приложения, в которых много файлов
+# Большие приложения — несколько файлов { #bigger-applications-multiple-files }
При построении приложения или веб-API нам редко удается поместить всё в один файл.
@@ -10,7 +10,7 @@
///
-## Пример структуры приложения
+## Пример структуры приложения { #an-example-file-structure }
Давайте предположим, что наше приложение имеет следующую структуру:
@@ -31,7 +31,7 @@
/// tip | Подсказка
-Обратите внимание, что в каждом каталоге и подкаталоге имеется файл `__init__.py`
+Есть несколько файлов `__init__.py`: по одному в каждом каталоге или подкаталоге.
Это как раз то, что позволяет импортировать код из одного файла в другой.
@@ -43,66 +43,63 @@ from app.routers import items
///
-* Всё помещается в каталоге `app`. В нём также находится пустой файл `app/__init__.py`. Таким образом, `app` является "Python-пакетом" (коллекцией модулей Python).
-* Он содержит файл `app/main.py`. Данный файл является частью пакета (т.е. находится внутри каталога, содержащего файл `__init__.py`), и, соответственно, он является модулем пакета: `app.main`.
+* Всё помещается в каталоге `app`. В нём также находится пустой файл `app/__init__.py`. Таким образом, `app` является "Python-пакетом" (коллекцией "Python-модулей"): `app`.
+* Он содержит файл `app/main.py`. Данный файл является частью Python-пакета (т.е. находится внутри каталога, содержащего файл `__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/routers/`, содержащий `__init__.py`. Он является Python-подпакетом: `app.routers`.
+* Файл `app/routers/items.py` находится внутри пакета `app/routers/`. Таким образом, он является подмодулем: `app.routers.items`.
+* Точно так же `app/routers/users.py` является ещё одним подмодулем: `app.routers.users`.
+* Подкаталог `app/internal/`, содержащий файл `__init__.py`, является ещё одним Python-подпакетом: `app.internal`.
+* А файл `app/internal/admin.py` является ещё одним подмодулем: `app.internal.admin`.
Та же самая файловая структура приложения, но с комментариями:
-```
+```bash
.
├── 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
+│ └── 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`
+## `APIRouter` { #apirouter }
-Давайте предположим, что для работы с пользователями используется отдельный файл (суб-модуль) `/app/routers/users.py`.
+Давайте предположим, что для работы с пользователями используется отдельный файл (подмодуль) `/app/routers/users.py`.
-Для лучшей организации приложения, вы хотите отделить операции пути, связанные с пользователями, от остального кода.
+Вы хотите отделить *операции пути*, связанные с пользователями, от остального кода, чтобы сохранить порядок.
-Но так, чтобы эти операции по-прежнему оставались частью **FastAPI** приложения/веб-API (частью одного пакета)
+Но это всё равно часть того же приложения/веб-API на **FastAPI** (часть того же «Python-пакета»).
-С помощью `APIRouter` вы можете создать *операции пути* (*эндпоинты*) для данного модуля.
+С помощью `APIRouter` вы можете создать *операции пути* для этого модуля.
+### Импорт `APIRouter` { #import-apirouter }
-### Импорт `APIRouter`
+Точно так же, как и в случае с классом `FastAPI`, вам нужно импортировать и создать его «экземпляр»:
-Точно также, как и в случае с классом `FastAPI`, вам нужно импортировать и создать объект класса `APIRouter`.
+{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *}
-```Python hl_lines="1 3" title="app/routers/users.py"
-{!../../docs_src/bigger_applications/app/routers/users.py!}
-```
+### *Операции пути* с `APIRouter` { #path-operations-with-apirouter }
-### Создание *эндпоинтов* с помощью `APIRouter`
+И затем вы используете его, чтобы объявить ваши *операции пути*.
-В дальнейшем используйте `APIRouter` для объявления *эндпоинтов*, точно также, как вы используете класс `FastAPI`:
+Используйте его так же, как вы использовали бы класс `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_an_py39/routers/users.py hl[6,11,16] title["app/routers/users.py"] *}
-Вы можете думать об `APIRouter` как об "уменьшенной версии" класса FastAPI`.
+Вы можете думать об `APIRouter` как об «мини-классе `FastAPI`».
-`APIRouter` поддерживает все те же самые опции.
+Поддерживаются все те же опции.
-`APIRouter` поддерживает все те же самые параметры, такие как `parameters`, `responses`, `dependencies`, `tags`, и т. д.
+Все те же `parameters`, `responses`, `dependencies`, `tags` и т.д.
/// tip | Подсказка
@@ -110,82 +107,51 @@ from app.routers import items
///
-Мы собираемся подключить данный `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!}
-```
-
-////
+Мы собираемся подключить данный `APIRouter` к нашему основному приложению на `FastAPI`, но сначала давайте проверим зависимости и ещё один `APIRouter`.
-//// tab | Python 3.8+ non-Annotated
+## Зависимости { #dependencies }
-/// tip | Подсказка
-
-Мы рекомендуем использовать версию `Annotated`, когда это возможно.
+Мы видим, что нам понадобятся некоторые зависимости, которые будут использоваться в нескольких местах приложения.
-///
+Поэтому мы поместим их в отдельный модуль `dependencies` (`app/dependencies.py`).
-```Python hl_lines="1 4-6" title="app/dependencies.py"
-{!> ../../docs_src/bigger_applications/app/dependencies.py!}
-```
+Теперь мы воспользуемся простой зависимостью, чтобы прочитать кастомный HTTP-заголовок `X-Token`:
-////
+{* ../../docs_src/bigger_applications/app_an_py39/dependencies.py hl[3,6:8] title["app/dependencies.py"] *}
/// tip | Подсказка
-Для простоты мы воспользовались неким воображаемым заголовоком.
+Для простоты мы воспользовались выдуманным заголовком.
-В реальных случаях для получения наилучших результатов используйте интегрированные утилиты обеспечения безопасности [Security utilities](security/index.md){.internal-link target=_blank}.
+В реальных случаях для получения наилучших результатов используйте интегрированные [утилиты безопасности](security/index.md){.internal-link target=_blank}.
///
-## Ещё один модуль с `APIRouter`
+## Ещё один модуль с `APIRouter` { #another-module-with-apirouter }
-Давайте также предположим, что у вас есть *эндпоинты*, отвечающие за обработку "items", и они находятся в модуле `app/routers/items.py`.
+Давайте также предположим, что у вас есть эндпоинты, отвечающие за обработку «items» в вашем приложении, и они находятся в модуле `app/routers/items.py`.
-У вас определены следующие *операции пути* (*эндпоинты*):
+У вас определены *операции пути* для:
* `/items/`
* `/items/{item_id}`
-Тут всё точно также, как и в ситуации с `app/routers/users.py`.
+Тут всё та же структура, как и в случае с `app/routers/users.py`.
-Но теперь мы хотим поступить немного умнее и слегка упростить код.
+Но мы хотим поступить умнее и слегка упростить код.
-Мы знаем, что все *эндпоинты* данного модуля имеют некоторые общие свойства:
+Мы знаем, что все *операции пути* этого модуля имеют одинаковые:
-* Префикс пути: `/items`.
-* Теги: (один единственный тег: `items`).
-* Дополнительные ответы (responses)
-* Зависимости: использование созданной нами зависимости `X-token`
+* `prefix` пути: `/items`.
+* `tags`: (один единственный тег: `items`).
+* Дополнительные `responses`.
+* `dependencies`: всем им нужна та зависимость `X-Token`, которую мы создали.
-Таким образом, вместо того чтобы добавлять все эти свойства в функцию каждого отдельного *эндпоинта*,
-мы добавим их в `APIRouter`.
+Таким образом, вместо того чтобы добавлять всё это в каждую *операцию пути*, мы можем добавить это в `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_an_py39/routers/items.py hl[5:10,16,21] title["app/routers/items.py"] *}
-Так как каждый *эндпоинт* начинается с символа `/`:
+Так как путь каждой *операции пути* должен начинаться с `/`, как здесь:
```Python hl_lines="1"
@router.get("/{item_id}")
@@ -197,75 +163,74 @@ async def read_item(item_id: str):
В нашем случае префиксом является `/items`.
-Мы также можем добавить в наш маршрутизатор (router) список `тегов` (`tags`) и дополнительных `ответов` (`responses`), которые являются общими для каждого *эндпоинта*.
+Мы также можем добавить список `tags` и дополнительные `responses`, которые будут применяться ко всем *операциям пути*, включённым в этот маршрутизатор.
-И ещё мы можем добавить в наш маршрутизатор список `зависимостей`, которые должны вызываться при каждом обращении к *эндпоинтам*.
+И ещё мы можем добавить список `dependencies`, которые будут добавлены ко всем *операциям пути* в маршрутизаторе и будут выполняться/разрешаться для каждого HTTP-запроса к ним.
/// tip | Подсказка
-Обратите внимание, что также, как и в случае с зависимостями в декораторах *эндпоинтов* ([dependencies in *path operation decorators*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), никакого значения в *функцию эндпоинта* передано не будет.
+Обратите внимание, что так же, как и в случае с [зависимостями в декораторах *операций пути*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, никакое значение не будет передано в вашу *функцию-обработчик пути*.
///
-В результате мы получим следующие эндпоинты:
+В результате пути для items теперь такие:
* `/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}.
+* Они будут помечены списком тегов, содержащим одну строку `"items"`.
+ * Эти «теги» особенно полезны для систем автоматической интерактивной документации (с использованием OpenAPI).
+* Все они будут включать предопределённые `responses`.
+* Все эти *операции пути* будут иметь список `dependencies`, вычисляемых/выполняемых перед ними.
+ * Если вы также объявите зависимости в конкретной *операции пути*, **они тоже будут выполнены**.
+ * Сначала выполняются зависимости маршрутизатора, затем [`dependencies` в декораторе](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, и затем обычные параметрические зависимости.
+ * Вы также можете добавить [`Security`-зависимости с `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
/// tip | Подсказка
-Например, с помощью зависимостей в `APIRouter` мы можем потребовать аутентификации для доступа ко всей группе *эндпоинтов*, не указывая зависимости для каждой отдельной функции *эндпоинта*.
+Например, с помощью зависимостей в `APIRouter` мы можем потребовать аутентификации для доступа ко всей группе *операций пути*. Даже если зависимости не добавляются по отдельности к каждой из них.
///
/// check | Заметка
-Параметры `prefix`, `tags`, `responses` и `dependencies` относятся к функционалу **FastAPI**, помогающему избежать дублирования кода.
+Параметры `prefix`, `tags`, `responses` и `dependencies` — это (как и во многих других случаях) просто возможность **FastAPI**, помогающая избежать дублирования кода.
///
-### Импорт зависимостей
+### Импорт зависимостей { #import-the-dependencies }
-Наш код находится в модуле `app.routers.items` (файл `app/routers/items.py`).
+Этот код находится в модуле `app.routers.items`, в файле `app/routers/items.py`.
-И нам нужно вызвать функцию зависимости из модуля `app.dependencies` (файл `app/dependencies.py`).
+И нам нужно получить функцию зависимости из модуля `app.dependencies`, файла `app/dependencies.py`.
-Мы используем операцию относительного импорта `..` для импорта зависимости:
+Поэтому мы используем относительный импорт с `..` для зависимостей:
-```Python hl_lines="3" title="app/routers/items.py"
-{!../../docs_src/bigger_applications/app/routers/items.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/routers/items.py hl[3] title["app/routers/items.py"] *}
-#### Как работает относительный импорт?
+#### Как работает относительный импорт { #how-relative-imports-work }
/// tip | Подсказка
-Если вы прекрасно знаете, как работает импорт в Python, то переходите к следующему разделу.
+Если вы прекрасно знаете, как работает импорт, переходите к следующему разделу ниже.
///
-Одна точка `.`, как в данном примере:
+Одна точка `.`, как здесь:
```Python
from .dependencies import get_token_header
```
+
означает:
-* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` расположен в каталоге `app/routers/`)...
-* ... найдите модуль `dependencies` (файл `app/routers/dependencies.py`)...
-* ... и импортируйте из него функцию `get_token_header`.
+* Начать в том же пакете, в котором находится этот модуль (файл `app/routers/items.py`) (каталог `app/routers/`)...
+* найти модуль `dependencies` (воображаемый файл `app/routers/dependencies.py`)...
+* и импортировать из него функцию `get_token_header`.
-К сожалению, такого файла не существует, и наши зависимости находятся в файле `app/dependencies.py`.
+Но такого файла не существует, наши зависимости находятся в файле `app/dependencies.py`.
Вспомните, как выглядит файловая структура нашего приложения:
@@ -273,7 +238,7 @@ from .dependencies import get_token_header
---
-Две точки `..`, как в данном примере:
+Две точки `..`, как здесь:
```Python
from ..dependencies import get_token_header
@@ -281,12 +246,12 @@ from ..dependencies import get_token_header
означают:
-* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` находится в каталоге `app/routers/`)...
-* ... перейдите в родительский пакет (каталог `app/`)...
-* ... найдите в нём модуль `dependencies` (файл `app/dependencies.py`)...
-* ... и импортируйте из него функцию `get_token_header`.
+* Начать в том же пакете, в котором находится этот модуль (файл `app/routers/items.py`) (каталог `app/routers/`)...
+* перейти в родительский пакет (каталог `app/`)...
+* и там найти модуль `dependencies` (файл `app/dependencies.py`)...
+* и импортировать из него функцию `get_token_header`.
-Это работает верно! 🎉
+Это работает корректно! 🎉
---
@@ -298,67 +263,61 @@ from ...dependencies import get_token_header
то это бы означало:
-* Начните с пакета, в котором находится данный модуль (файл `app/routers/items.py` находится в каталоге `app/routers/`)...
-* ... перейдите в родительский пакет (каталог `app/`)...
-* ... затем перейдите в родительский пакет текущего пакета (такого пакета не существует, `app` находится на самом верхнем уровне 😱)...
-* ... найдите в нём модуль `dependencies` (файл `app/dependencies.py`)...
-* ... и импортируйте из него функцию `get_token_header`.
+* Начать в том же пакете, в котором находится этот модуль (файл `app/routers/items.py`) расположен в (каталоге `app/routers/`)...
+* перейти в родительский пакет (каталог `app/`)...
+* затем перейти в родительский пакет этого пакета (родительского пакета нет, `app` — верхний уровень 😱)...
+* и там найти модуль `dependencies` (файл `app/dependencies.py`)...
+* и импортировать из него функцию `get_token_header`.
-Это будет относиться к некоторому пакету, находящемуся на один уровень выше чем `app/` и содержащему свой собственный файл `__init__.py`. Но ничего такого у нас нет. Поэтому это приведет к ошибке в нашем примере. 🚨
+Это ссылалось бы на какой-то пакет выше `app/`, со своим файлом `__init__.py` и т.п. Но у нас такого нет. Поэтому это вызвало бы ошибку в нашем примере. 🚨
-Теперь вы знаете, как работает импорт в Python, и сможете использовать относительное импортирование в своих собственных приложениях любого уровня сложности. 🤓
+Но теперь вы знаете, как это работает, так что можете использовать относительные импорты в своих приложениях, независимо от того, насколько они сложные. 🤓
-### Добавление пользовательских тегов (`tags`), ответов (`responses`) и зависимостей (`dependencies`)
+### Добавление пользовательских `tags`, `responses` и `dependencies` { #add-some-custom-tags-responses-and-dependencies }
-Мы не будем добавлять префикс `/items` и список тегов `tags=["items"]` для каждого *эндпоинта*, т.к. мы уже их добавили с помощью `APIRouter`.
+Мы не добавляем префикс `/items` и `tags=["items"]` к каждой *операции пути*, потому что мы добавили их в `APIRouter`.
-Но помимо этого мы можем добавить новые теги для каждого отдельного *эндпоинта*, а также некоторые дополнительные ответы (`responses`), характерные для данного *эндпоинта*:
+Но мы всё равно можем добавить _ещё_ `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_an_py39/routers/items.py hl[30:31] title["app/routers/items.py"] *}
/// tip | Подсказка
-Последний *эндпоинт* будет иметь следующую комбинацию тегов: `["items", "custom"]`.
+Эта последняя операция пути будет иметь комбинацию тегов: `["items", "custom"]`.
-А также в его документации будут содержаться оба ответа: один для `404` и другой для `403`.
+И в документации у неё будут оба ответа: один для `404` и один для `403`.
///
-## Модуль main в `FastAPI`
+## Модуль main в `FastAPI` { #the-main-fastapi }
Теперь давайте посмотрим на модуль `app/main.py`.
Именно сюда вы импортируете и именно здесь вы используете класс `FastAPI`.
-Это основной файл вашего приложения, который объединяет всё в одно целое.
+Это основной файл вашего приложения, который связывает всё воедино.
-И теперь, когда большая часть логики приложения разделена на отдельные модули, основной файл `app/main.py` будет достаточно простым.
+И так как большая часть вашей логики теперь будет находиться в отдельных специфичных модулях, основной файл будет довольно простым.
-### Импорт `FastAPI`
+### Импорт `FastAPI` { #import-fastapi }
-Вы импортируете и создаете класс `FastAPI` как обычно.
+Вы импортируете и создаёте класс `FastAPI` как обычно.
-Мы даже можем объявить глобальные зависимости [global dependencies](dependencies/global-dependencies.md){.internal-link target=_blank}, которые будут объединены с зависимостями для каждого отдельного маршрутизатора:
+И мы даже можем объявить [глобальные зависимости](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_an_py39/main.py hl[1,3,7] title["app/main.py"] *}
-### Импорт `APIRouter`
+### Импорт `APIRouter` { #import-the-apirouter }
-Теперь мы импортируем другие суб-модули, содержащие `APIRouter`:
+Теперь мы импортируем другие подмодули, содержащие `APIRouter`:
-```Python hl_lines="4-5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[4:5] title["app/main.py"] *}
-Так как файлы `app/routers/users.py` и `app/routers/items.py` являются суб-модулями одного и того же Python-пакета `app`, то мы сможем их импортировать, воспользовавшись операцией относительного импорта `.`.
+Так как файлы `app/routers/users.py` и `app/routers/items.py` являются подмодулями, входящими в один и тот же Python-пакет `app`, мы можем использовать одну точку `.` для импорта через «относительные импорты».
-### Как работает импорт?
+### Как работает импорт { #how-the-importing-works }
-Данная строка кода:
+Этот фрагмент:
```Python
from .routers import items, users
@@ -366,15 +325,15 @@ from .routers import items, users
означает:
-* Начните с пакета, в котором содержится данный модуль (файл `app/main.py` содержится в каталоге `app/`)...
-* ... найдите суб-пакет `routers` (каталог `app/routers/`)...
-* ... и из него импортируйте суб-модули `items` (файл `app/routers/items.py`) и `users` (файл `app/routers/users.py`)...
+* Начать в том же пакете, в котором находится этот модуль (файл `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`.
+В модуле `items` будет переменная `router` (`items.router`). Это та же самая, которую мы создали в файле `app/routers/items.py`, это объект `APIRouter`.
-И затем мы сделаем то же самое для модуля `users`.
+И затем мы делаем то же самое для модуля `users`.
-Мы также могли бы импортировать и другим методом:
+Мы также могли бы импортировать их так:
```Python
from app.routers import items, users
@@ -382,50 +341,46 @@ from app.routers import items, users
/// info | Примечание
-Первая версия является примером относительного импорта:
+Первая версия — это «относительный импорт»:
```Python
from .routers import items, users
```
-Вторая версия является примером абсолютного импорта:
+Вторая версия — это «абсолютный импорт»:
```Python
from app.routers import items, users
```
-Узнать больше о пакетах и модулях в Python вы можете из официальной документации Python о модулях
+Чтобы узнать больше о Python-пакетах и модулях, прочитайте официальную документацию Python о модулях.
///
-### Избегайте конфликтов имен
+### Избегайте конфликтов имён { #avoid-name-collisions }
-Вместо того чтобы импортировать только переменную `router`, мы импортируем непосредственно суб-модуль `items`.
+Мы импортируем подмодуль `items` напрямую, вместо того чтобы импортировать только его переменную `router`.
-Мы делаем это потому, что у нас есть ещё одна переменная `router` в суб-модуле `users`.
+Это потому, что у нас также есть другая переменная с именем `router` в подмодуле `users`.
-Если бы мы импортировали их одну за другой, как показано в примере:
+Если бы мы импортировали их одну за другой, как здесь:
```Python
from .routers.items import router
from .routers.users import router
```
-то переменная `router` из `users` переписал бы переменную `router` из `items`, и у нас не было бы возможности использовать их одновременно.
+то `router` из `users` перезаписал бы `router` из `items`, и мы не смогли бы использовать их одновременно.
-Поэтому, для того чтобы использовать обе эти переменные в одном файле, мы импортировали соответствующие суб-модули:
+Поэтому, чтобы иметь возможность использовать обе в одном файле, мы импортируем подмодули напрямую:
-```Python hl_lines="5" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[5] title["app/main.py"] *}
-### Подключение маршрутизаторов (`APIRouter`) для `users` и для `items`
+### Подключение `APIRouter` для `users` и `items` { #include-the-apirouters-for-users-and-items }
-Давайте подключим маршрутизаторы (`router`) из суб-модулей `users` и `items`:
+Теперь давайте подключим `router` из подмодулей `users` и `items`:
-```Python hl_lines="10-11" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[10:11] title["app/main.py"] *}
/// info | Примечание
@@ -435,89 +390,82 @@ from .routers.users import router
///
-С помощью `app.include_router()` мы можем добавить каждый из маршрутизаторов (`APIRouter`) в основное приложение `FastAPI`.
+С помощью `app.include_router()` мы можем добавить каждый `APIRouter` в основное приложение `FastAPI`.
-Он подключит все маршруты заданного маршрутизатора к нашему приложению.
+Он включит все маршруты этого маршрутизатора как часть приложения.
/// note | Технические детали
-Фактически, внутри он создаст все *операции пути* для каждой операции пути объявленной в `APIRouter`.
+Фактически, внутри он создаст *операцию пути* для каждой *операции пути*, объявленной в `APIRouter`.
-И под капотом всё будет работать так, как будто бы мы имеем дело с одним файлом приложения.
+Так что под капотом всё будет работать так, как будто всё было одним приложением.
///
/// check | Заметка
-При подключении маршрутизаторов не стоит беспокоиться о производительности.
+При подключении маршрутизаторов не нужно беспокоиться о производительности.
-Операция подключения займёт микросекунды и понадобится только при запуске приложения.
+Это займёт микросекунды и произойдёт только при старте.
-Таким образом, это не повлияет на производительность. ⚡
+Так что это не повлияет на производительность. ⚡
///
-### Подключение `APIRouter` с пользовательскими префиксом (`prefix`), тегами (`tags`), ответами (`responses`), и зависимостями (`dependencies`)
+### Подключение `APIRouter` с пользовательскими `prefix`, `tags`, `responses` и `dependencies` { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies }
Теперь давайте представим, что ваша организация передала вам файл `app/internal/admin.py`.
-Он содержит `APIRouter` с некоторыми *эндпоитами* администрирования, которые ваша организация использует для нескольких проектов.
+Он содержит `APIRouter` с некоторыми административными *операциями пути*, которые ваша организация использует в нескольких проектах.
-В данном примере это сделать очень просто. Но давайте предположим, что поскольку файл используется для нескольких проектов,
-то мы не можем модифицировать его, добавляя префиксы (`prefix`), зависимости (`dependencies`), теги (`tags`), и т.д. непосредственно в `APIRouter`:
+Для этого примера всё будет очень просто. Но допустим, что поскольку он используется совместно с другими проектами в организации, мы не можем модифицировать его и добавить `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_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *}
-Но, несмотря на это, мы хотим использовать кастомный префикс (`prefix`) для подключенного маршрутизатора (`APIRouter`), в результате чего, каждая *операция пути* будет начинаться с `/admin`. Также мы хотим защитить наш маршрутизатор с помощью зависимостей, созданных для нашего проекта. И ещё мы хотим включить теги (`tags`) и ответы (`responses`).
+Но мы всё равно хотим задать пользовательский `prefix` при подключении `APIRouter`, чтобы все его *операции пути* начинались с `/admin`, хотим защитить его с помощью `dependencies`, которые у нас уже есть для этого проекта, и хотим включить `tags` и `responses`.
-Мы можем применить все вышеперечисленные настройки, не изменяя начальный `APIRouter`. Нам всего лишь нужно передать нужные параметры в `app.include_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_an_py39/main.py hl[14:17] title["app/main.py"] *}
-Таким образом, оригинальный `APIRouter` не будет модифицирован, и мы сможем использовать файл `app/internal/admin.py` сразу в нескольких проектах организации.
+Таким образом исходный `APIRouter` не будет модифицирован, и мы сможем использовать файл `app/internal/admin.py` сразу в нескольких проектах организации.
-В результате, в нашем приложении каждый *эндпоинт* модуля `admin` будет иметь:
+В результате в нашем приложении каждая из *операций пути* из модуля `admin` будет иметь:
* Префикс `/admin`.
* Тег `admin`.
* Зависимость `get_token_header`.
* Ответ `418`. 🍵
-Это будет иметь место исключительно для `APIRouter` в нашем приложении, и не затронет любой другой код, использующий его.
+Но это повлияет только на этот `APIRouter` в нашем приложении, а не на любой другой код, который его использует.
-Например, другие проекты, могут использовать тот же самый `APIRouter` с другими методами аутентификации.
+Так что, например, другие проекты могут использовать тот же `APIRouter` с другим методом аутентификации.
-### Подключение отдельного *эндпоинта*
+### Подключение *операции пути* { #include-a-path-operation }
-Мы также можем добавить *эндпоинт* непосредственно в основное приложение `FastAPI`.
+Мы также можем добавлять *операции пути* напрямую в приложение `FastAPI`.
-Здесь мы это делаем ... просто, чтобы показать, что это возможно 🤷:
+Здесь мы делаем это... просто чтобы показать, что можем 🤷:
-```Python hl_lines="21-23" title="app/main.py"
-{!../../docs_src/bigger_applications/app/main.py!}
-```
+{* ../../docs_src/bigger_applications/app_an_py39/main.py hl[21:23] title["app/main.py"] *}
-и это будет работать корректно вместе с другими *эндпоинтами*, добавленными с помощью `app.include_router()`.
+и это будет работать корректно вместе со всеми другими *операциями пути*, добавленными через `app.include_router()`.
-/// info | Сложные технические детали
+/// info | Очень технические детали
-**Примечание**: это сложная техническая деталь, которую, скорее всего, **вы можете пропустить**.
+**Примечание**: это очень техническая деталь, которую, вероятно, можно **просто пропустить**.
---
-Маршрутизаторы (`APIRouter`) не "монтируются" по-отдельности и не изолируются от остального приложения.
+`APIRouter` не «монтируются», они не изолированы от остального приложения.
-Это происходит потому, что нужно включить их *эндпоинты* в OpenAPI схему и в интерфейс пользователя.
+Это потому, что мы хотим включить их *операции пути* в OpenAPI-схему и пользовательские интерфейсы.
-В силу того, что мы не можем их изолировать и "примонтировать" независимо от остальных, *эндпоинты* клонируются (пересоздаются) и не подключаются напрямую.
+Так как мы не можем просто изолировать их и «смонтировать» независимо от остального, *операции пути* «клонируются» (пересоздаются), а не включаются напрямую.
///
-## Проверка автоматической документации API
+## Проверка автоматической документации API { #check-the-automatic-api-docs }
Теперь запустите приложение:
@@ -533,24 +481,24 @@ $ fastapi dev app/main.py
Откройте документацию по адресу http://127.0.0.1:8000/docs.
-Вы увидите автоматическую API документацию. Она включает в себя маршруты из суб-модулей, используя верные маршруты, префиксы и теги:
+Вы увидите автоматическую документацию API, включая пути из всех подмодулей, с использованием корректных путей (и префиксов) и корректных тегов:
-## Подключение существующего маршрута через новый префикс (`prefix`)
+## Подключение одного и того же маршрутизатора несколько раз с разными `prefix` { #include-the-same-router-multiple-times-with-different-prefix }
-Вы можете использовать `.include_router()` несколько раз с одним и тем же маршрутом, применив различные префиксы.
+Вы можете использовать `.include_router()` несколько раз с *одним и тем же* маршрутизатором, используя разные префиксы.
-Это может быть полезным, если нужно предоставить доступ к одному и тому же API через различные префиксы, например, `/api/v1` и `/api/latest`.
+Это может быть полезно, например, чтобы предоставить доступ к одному и тому же API с разными префиксами, например `/api/v1` и `/api/latest`.
-Это продвинутый способ, который вам может и не пригодится. Мы приводим его на случай, если вдруг вам это понадобится.
+Это продвинутое использование, которое вам может и не понадобиться, но оно есть на случай, если понадобится.
-## Включение одного маршрутизатора (`APIRouter`) в другой
+## Подключение `APIRouter` в другой `APIRouter` { #include-an-apirouter-in-another }
-Точно так же, как вы включаете `APIRouter` в приложение `FastAPI`, вы можете включить `APIRouter` в другой `APIRouter`:
+Точно так же, как вы можете подключить `APIRouter` к приложению `FastAPI`, вы можете подключить `APIRouter` к другому `APIRouter`, используя:
```Python
router.include_router(other_router)
```
-Удостоверьтесь, что вы сделали это до того, как подключить маршрутизатор (`router`) к вашему `FastAPI` приложению, и *эндпоинты* маршрутизатора `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 5ed5f59fc..cf6cf480a 100644
--- a/docs/ru/docs/tutorial/body-fields.md
+++ b/docs/ru/docs/tutorial/body-fields.md
@@ -1,12 +1,12 @@
-# Body - Поля
+# Body - Поля { #body-fields }
Таким же способом, как вы объявляете дополнительную валидацию и метаданные в параметрах *функции обработки пути* с помощью функций `Query`, `Path` и `Body`, вы можете объявлять валидацию и метаданные внутри Pydantic моделей, используя функцию `Field` из Pydantic.
-## Импорт `Field`
+## Импорт `Field` { #import-field }
Сначала вы должны импортировать его:
-{* ../../docs_src/body_fields/tutorial001_py310.py hl[2] *}
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
/// warning | Внимание
@@ -14,11 +14,11 @@
///
-## Объявление атрибутов модели
+## Объявление атрибутов модели { #declare-model-attributes }
Вы можете использовать функцию `Field` с атрибутами модели:
-{* ../../docs_src/body_fields/tutorial001_py310.py hl[9:12] *}
+{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
Функция `Field` работает так же, как `Query`, `Path` и `Body`, у неё такие же параметры и т.д.
@@ -26,9 +26,9 @@
На самом деле, `Query`, `Path` и другие функции, которые вы увидите в дальнейшем, создают объекты подклассов общего класса `Param`, который сам по себе является подклассом `FieldInfo` из Pydantic.
-И `Field` (из Pydantic), и `Body`, оба возвращают объекты подкласса `FieldInfo`.
+И `Field` (из Pydantic) также возвращает экземпляр `FieldInfo`.
-У класса `Body` есть и другие подклассы, с которыми вы ознакомитесь позже.
+`Body` также напрямую возвращает объекты подкласса `FieldInfo`. И есть и другие, с которыми вы познакомитесь позже, которые являются подклассами класса `Body`.
Помните, что когда вы импортируете `Query`, `Path` и другое из `fastapi`, это фактически функции, которые возвращают специальные классы.
@@ -40,12 +40,11 @@
///
-## Добавление дополнительной информации
+## Добавление дополнительной информации { #add-extra-information }
Вы можете объявлять дополнительную информацию в `Field`, `Query`, `Body` и т.п. Она будет включена в сгенерированную JSON схему.
-Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать, как задавать примеры принимаемых данных.
-
+Вы узнаете больше о добавлении дополнительной информации позже в документации, когда будете изучать, как задавать примеры.
/// warning | Внимание
@@ -54,7 +53,7 @@
///
-## Резюме
+## Резюме { #recap }
Вы можете использовать функцию `Field` из Pydantic, чтобы задавать дополнительную валидацию и метаданные для атрибутов модели.
diff --git a/docs/ru/docs/tutorial/body-multiple-params.md b/docs/ru/docs/tutorial/body-multiple-params.md
index 9300aa1bd..9ae57a311 100644
--- a/docs/ru/docs/tutorial/body-multiple-params.md
+++ b/docs/ru/docs/tutorial/body-multiple-params.md
@@ -1,8 +1,8 @@
-# Body - Множество параметров
+# Body - Множество параметров { #body-multiple-parameters }
-Теперь, когда мы увидели, как использовать `Path` и `Query` параметры, давайте рассмотрим более продвинутые примеры обьявления тела запроса.
+Теперь, когда мы увидели, как использовать `Path` и `Query` параметры, давайте рассмотрим более продвинутые примеры объявления тела запроса.
-## Обьединение `Path`, `Query` и параметров тела запроса
+## Объединение `Path`, `Query` и параметров тела запроса { #mix-path-query-and-body-parameters }
Во-первых, конечно, вы можете объединять параметры `Path`, `Query` и объявления тела запроса в своих функциях обработки, **FastAPI** автоматически определит, что с ними нужно делать.
@@ -16,9 +16,9 @@
///
-## Несколько параметров тела запроса
+## Несколько параметров тела запроса { #multiple-body-parameters }
-В предыдущем примере, *операции пути* ожидали тело запроса в формате JSON-тело с параметрами, соответствующими атрибутам `Item`, например:
+В предыдущем примере, *операции пути* ожидали тело запроса в формате JSON, с параметрами, соответствующими атрибутам `Item`, например:
```JSON
{
@@ -33,7 +33,7 @@
{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
-В этом случае **FastAPI** заметит, что в функции есть более одного параметра тела (два параметра, которые являются моделями Pydantic).
+В этом случае **FastAPI** заметит, что в функции есть более одного параметра тела (два параметра, которые являются Pydantic-моделями).
Таким образом, имена параметров будут использоваться в качестве ключей (имён полей) в теле запроса, и будет ожидаться запрос следующего формата:
@@ -54,21 +54,21 @@
/// note | Внимание
-Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предпологается, что он находится внутри тела с ключом `item`.
+Обратите внимание, что хотя параметр `item` был объявлен таким же способом, как и раньше, теперь предполагается, что он находится внутри тела с ключом `item`.
///
-**FastAPI** сделает автоматические преобразование из запроса, так что параметр `item` получит своё конкретное содержимое, и то же самое происходит с пользователем `user`.
+**FastAPI** сделает автоматическое преобразование из запроса, так что параметр `item` получит своё конкретное содержимое, и то же самое происходит с пользователем `user`.
Произойдёт проверка составных данных, и создание документации в схеме OpenAPI и автоматических документах.
-## Отдельные значения в теле запроса
+## Отдельные значения в теле запроса { #singular-values-in-body }
Точно так же, как `Query` и `Path` используются для определения дополнительных данных для query и path параметров, **FastAPI** предоставляет аналогичный инструмент - `Body`.
Например, расширяя предыдущую модель, вы можете решить, что вам нужен еще один ключ `importance` в том же теле запроса, помимо параметров `item` и `user`.
-Если вы объявите его без указания, какой именно объект (Path, Query, Body и .т.п.) ожидаете, то, поскольку это является простым типом данных, **FastAPI** будет считать, что это query-параметр.
+Если вы объявите его без указания, какой именно объект (Path, Query, Body и т.п.) ожидаете, то, поскольку это является простым типом данных, **FastAPI** будет считать, что это query-параметр.
Но вы можете указать **FastAPI** обрабатывать его, как ещё один ключ тела запроса, используя `Body`:
@@ -94,7 +94,7 @@
И всё будет работать так же - преобразование типов данных, валидация, документирование и т.д.
-## Множество body и query параметров
+## Множество body и query параметров { #multiple-body-params-and-query }
Конечно, вы также можете объявлять query-параметры в любое время, дополнительно к любым body-параметрам.
@@ -112,7 +112,7 @@ q: str | None = None
Например:
-{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[27] *}
+{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
/// info | Информация
@@ -120,9 +120,9 @@ q: str | None = None
///
-## Добавление одного body-параметра
+## Вложить один body-параметр { #embed-a-single-body-parameter }
-Предположим, у вас есть только один body-параметр `item` из Pydantic модели `Item`.
+Предположим, у вас есть только один body-параметр `item` из Pydantic-модели `Item`.
По умолчанию, **FastAPI** ожидает получить тело запроса напрямую.
@@ -160,9 +160,9 @@ item: Item = Body(embed=True)
}
```
-## Резюме
+## Резюме { #recap }
-Вы можете добавлять несколько body-параметров вашей *функции операции пути*, несмотря даже на то, что запрос может содержать только одно тело.
+Вы можете добавлять несколько body-параметров вашей *функции-обработчика пути*, несмотря даже на то, что запрос может содержать только одно тело.
Но **FastAPI** справится с этим, предоставит правильные данные в вашей функции, а также сделает валидацию и документацию правильной схемы *операции пути*.
diff --git a/docs/ru/docs/tutorial/body-nested-models.md b/docs/ru/docs/tutorial/body-nested-models.md
index 430092892..4c914b97f 100644
--- a/docs/ru/docs/tutorial/body-nested-models.md
+++ b/docs/ru/docs/tutorial/body-nested-models.md
@@ -1,63 +1,42 @@
-# Body - Вложенные модели
+# Body - Вложенные модели { #body-nested-models }
-С помощью **FastAPI**, вы можете определять, валидировать, документировать и использовать модели произвольной вложенности (благодаря библиотеке Pydantic).
+С помощью **FastAPI** вы можете определять, валидировать, документировать и использовать модели произвольной глубины вложенности (благодаря Pydantic).
-## Определение полей содержащих списки
+## Поля-списки { #list-fields }
-Вы можете определять атрибут как подтип. Например, тип `list` в Python:
+Вы можете определить атрибут как подтип. Например, Python-тип `list`:
{* ../../docs_src/body_nested_models/tutorial001_py310.py hl[12] *}
-Это приведёт к тому, что обьект `tags` преобразуется в список, несмотря на то что тип его элементов не объявлен.
+Это приведёт к тому, что `tags` будет списком, несмотря на то, что тип его элементов не объявлен.
-## Определение полей содержащих список с определением типов его элементов
+## Поля-списки с параметром типа { #list-fields-with-type-parameter }
-Однако в Python есть способ объявления списков с указанием типов для вложенных элементов:
+В Python есть специальный способ объявлять списки с внутренними типами, или «параметрами типа»:
-### Импортируйте `List` из модуля typing
+### Объявите `list` с параметром типа { #declare-a-list-with-a-type-parameter }
-В Python 3.9 и выше вы можете использовать стандартный тип `list` для объявления аннотаций типов, как мы увидим ниже. 💡
-
-Но в версиях Python до 3.9 (начиная с 3.6) сначала вам необходимо импортировать `List` из стандартного модуля `typing` в Python:
-
-{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-
-### Объявление `list` с указанием типов для вложенных элементов
-
-Объявление типов для элементов (внутренних типов) вложенных в такие типы как `list`, `dict`, `tuple`:
-
-* Если у вас Python версии ниже чем 3.9, импортируйте их аналог из модуля `typing`
-* Передайте внутренний(ие) тип(ы) как "параметры типа", используя квадратные скобки: `[` и `]`
-
-В Python версии 3.9 это будет выглядеть так:
+Для объявления типов, у которых есть параметры типа (внутренние типы), таких как `list`, `dict`, `tuple`, передайте внутренний(ие) тип(ы) как «параметры типа», используя квадратные скобки: `[` и `]`
```Python
my_list: list[str]
```
-В версиях Python до 3.9 это будет выглядеть так:
-
-```Python
-from typing import List
-
-my_list: List[str]
-```
-
Это всё стандартный синтаксис Python для объявления типов.
Используйте этот же стандартный синтаксис для атрибутов модели с внутренними типами.
-Таким образом, в нашем примере мы можем явно указать тип данных для поля `tags` как "список строк":
+Таким образом, в нашем примере мы можем явно указать тип данных для поля `tags` как «список строк»:
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## Типы множеств
+## Типы множеств { #set-types }
-Но затем мы подумали и поняли, что теги не должны повторяться и, вероятно, они должны быть уникальными строками.
+Но затем мы подумали и поняли, что теги не должны повторяться, вероятно, это должны быть уникальные строки.
-И в Python есть специальный тип данных для множеств уникальных элементов - `set`.
+И в Python есть специальный тип данных для множеств уникальных элементов — `set`.
-Тогда мы можем обьявить поле `tags` как множество строк:
+Тогда мы можем объявить поле `tags` как множество строк:
{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
@@ -67,23 +46,23 @@ my_list: List[str]
И они также будут соответствующим образом аннотированы / задокументированы.
-## Вложенные Модели
+## Вложенные модели { #nested-models }
У каждого атрибута Pydantic-модели есть тип.
-Но этот тип может сам быть другой моделью Pydantic.
+Но этот тип сам может быть другой моделью Pydantic.
-Таким образом вы можете объявлять глубоко вложенные JSON "объекты" с определёнными именами атрибутов, типами и валидацией.
+Таким образом, вы можете объявлять глубоко вложенные JSON «объекты» с определёнными именами атрибутов, типами и валидацией.
Всё это может быть произвольно вложенным.
-### Определение подмодели
+### Определение подмодели { #define-a-submodel }
Например, мы можем определить модель `Image`:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### Использование вложенной модели в качестве типа
+### Использование подмодели как типа { #use-the-submodel-as-a-type }
Также мы можем использовать эту модель как тип атрибута:
@@ -107,30 +86,30 @@ my_list: List[str]
Ещё раз: сделав такое объявление, с помощью **FastAPI** вы получите:
-* Поддержку редакторов IDE (автодополнение и т.д), даже для вложенных моделей
+* Поддержку редактора кода (автозавершение и т.д.), даже для вложенных моделей
* Преобразование данных
* Валидацию данных
* Автоматическую документацию
-## Особые типы и валидация
+## Особые типы и валидация { #special-types-and-validation }
-Помимо обычных простых типов, таких как `str`, `int`, `float`, и т.д. Вы можете использовать более сложные базовые типы, которые наследуются от типа `str`.
+Помимо обычных простых типов, таких как `str`, `int`, `float` и т.д., вы можете использовать более сложные простые типы, которые наследуются от `str`.
-Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с документацией по необычным типам Pydantic. Вы увидите некоторые примеры в следующей главе.
+Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с обзором типов Pydantic. Вы увидите некоторые примеры в следующей главе.
-Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из модуля Pydantic вместо типа `str`:
+Например, так как в модели `Image` у нас есть поле `url`, то мы можем объявить его как тип `HttpUrl` из Pydantic вместо типа `str`:
{* ../../docs_src/body_nested_models/tutorial005_py310.py hl[2,8] *}
-Строка будет проверена на соответствие допустимому URL-адресу и задокументирована в JSON схему / OpenAPI.
+Строка будет проверена на соответствие допустимому URL-адресу и задокументирована в JSON Schema / OpenAPI как таковая.
-## Атрибуты, содержащие списки подмоделей
+## Атрибуты, содержащие списки подмоделей { #attributes-with-lists-of-submodels }
-Вы также можете использовать модели Pydantic в качестве типов вложенных в `list`, `set` и т.д:
+Вы также можете использовать модели Pydantic в качестве подтипов для `list`, `set` и т.д.:
{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
-Такая реализация будет ожидать (конвертировать, валидировать, документировать и т.д) JSON-содержимое в следующем формате:
+Такая реализация будет ожидать (конвертировать, валидировать, документировать и т.д.) JSON-содержимое в следующем формате:
```JSON hl_lines="11"
{
@@ -162,7 +141,7 @@ my_list: List[str]
///
-## Глубоко вложенные модели
+## Глубоко вложенные модели { #deeply-nested-models }
Вы можете определять модели с произвольным уровнем вложенности:
@@ -174,15 +153,9 @@ my_list: List[str]
///
-## Тела с чистыми списками элементов
-
-Если верхний уровень значения тела JSON-объекта представляет собой JSON `array` (в Python - `list`), вы можете объявить тип в параметре функции, так же, как в моделях Pydantic:
-
-```Python
-images: List[Image]
-```
+## Тела с чистыми списками элементов { #bodies-of-pure-lists }
-в Python 3.9 и выше:
+Если верхний уровень значения тела JSON-объекта представляет собой JSON `array` (в Python — `list`), вы можете объявить тип в параметре функции, так же как в моделях Pydantic:
```Python
images: list[Image]
@@ -192,33 +165,33 @@ images: list[Image]
{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## Универсальная поддержка редактора
+## Поддержка редактора кода везде { #editor-support-everywhere }
-И вы получаете поддержку редактора везде.
+И вы получаете поддержку редактора кода везде.
Даже для элементов внутри списков:
-Вы не могли бы получить такую поддержку редактора, если бы работали напрямую с `dict`, а не с моделями Pydantic.
+Вы не могли бы получить такую поддержку редактора кода, если бы работали напрямую с `dict`, а не с моделями Pydantic.
Но вы также не должны беспокоиться об этом, входящие словари автоматически конвертируются, а ваш вывод также автоматически преобразуется в формат JSON.
-## Тела запросов с произвольными словарями (`dict` )
+## Тела запросов с произвольными словарями (`dict`) { #bodies-of-arbitrary-dicts }
-Вы также можете объявить тело запроса как `dict` с ключами определенного типа и значениями другого типа данных.
+Вы также можете объявить тело запроса как `dict` с ключами определённого типа и значениями другого типа.
Без необходимости знать заранее, какие значения являются допустимыми для имён полей/атрибутов (как это было бы в случае с моделями Pydantic).
-Это было бы полезно, если вы хотите получить ключи, которые вы еще не знаете.
+Это было бы полезно, если вы хотите получить ключи, которые вы ещё не знаете.
---
-Другой полезный случай - когда вы хотите чтобы ключи были другого типа данных, например, `int`.
+Другой полезный случай — когда вы хотите, чтобы ключи были другого типа данных, например, `int`.
Именно это мы сейчас и увидим здесь.
-В этом случае вы принимаете `dict`, пока у него есть ключи типа `int` со значениями типа `float`:
+В этом случае вы принимаете любой `dict`, пока у него есть ключи типа `int` со значениями типа `float`:
{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
@@ -228,19 +201,19 @@ images: list[Image]
Но Pydantic обеспечивает автоматическое преобразование данных.
-Это значит, что даже если пользователи вашего API могут отправлять только строки в качестве ключей, при условии, что эти строки содержат целые числа, Pydantic автоматический преобразует и валидирует эти данные.
+Это значит, что даже если клиенты вашего API могут отправлять только строки в качестве ключей, при условии, что эти строки содержат целые числа, Pydantic автоматически преобразует и валидирует эти данные.
-А `dict`, с именем `weights`, который вы получите в качестве ответа Pydantic, действительно будет иметь ключи типа `int` и значения типа `float`.
+А `dict`, который вы получите как `weights`, действительно будет иметь ключи типа `int` и значения типа `float`.
///
-## Резюме
+## Резюме { #recap }
С помощью **FastAPI** вы получаете максимальную гибкость, предоставляемую моделями Pydantic, сохраняя при этом простоту, краткость и элегантность вашего кода.
И дополнительно вы получаете:
-* Поддержку редактора (автодополнение доступно везде!)
+* Поддержку редактора кода (автозавершение доступно везде!)
* Преобразование данных (также известно как парсинг / сериализация)
* Валидацию данных
* Документацию схемы данных
diff --git a/docs/ru/docs/tutorial/body-updates.md b/docs/ru/docs/tutorial/body-updates.md
index 99f475a41..4a7adb255 100644
--- a/docs/ru/docs/tutorial/body-updates.md
+++ b/docs/ru/docs/tutorial/body-updates.md
@@ -1,16 +1,16 @@
-# Body - Обновления
+# Body - Обновления { #body-updates }
-## Полное обновление с помощью `PUT`
+## Обновление с заменой при помощи `PUT` { #update-replacing-with-put }
-Для полного обновления элемента можно воспользоваться операцией HTTP `PUT`.
+Чтобы обновить элемент, вы можете использовать операцию HTTP `PUT`.
-Вы можете использовать функцию `jsonable_encoder` для преобразования входных данных в JSON, так как нередки случаи, когда работать можно только с простыми типами данных (например, для хранения в NoSQL-базе данных).
+Вы можете использовать `jsonable_encoder`, чтобы преобразовать входные данные в данные, которые можно сохранить как JSON (например, в NoSQL-базе данных). Например, преобразование `datetime` в `str`.
{* ../../docs_src/body_updates/tutorial001_py310.py hl[28:33] *}
-`PUT` используется для получения данных, которые должны полностью заменить существующие данные.
+`PUT` используется для получения данных, которые должны заменить существующие данные.
-### Предупреждение о замене
+### Предупреждение о замене { #warning-about-replacing }
Это означает, что если вы хотите обновить элемент `bar`, используя `PUT` с телом, содержащим:
@@ -24,11 +24,11 @@
поскольку оно не включает уже сохраненный атрибут `"tax": 20.2`, входная модель примет значение по умолчанию `"tax": 10.5`.
-И данные будут сохранены с этим "новым" `tax`, равным `10,5`.
+И данные будут сохранены с этим «новым» `tax`, равным `10.5`.
-## Частичное обновление с помощью `PATCH`
+## Частичное обновление с помощью `PATCH` { #partial-updates-with-patch }
-Также можно использовать HTTP `PATCH` операцию для *частичного* обновления данных.
+Также можно использовать операцию HTTP `PATCH` для *частичного* обновления данных.
Это означает, что можно передавать только те данные, которые необходимо обновить, оставляя остальные нетронутыми.
@@ -44,36 +44,38 @@
///
-### Использование параметра `exclude_unset` в Pydantic
+### Использование параметра `exclude_unset` в Pydantic { #using-pydantics-exclude-unset-parameter }
-Если необходимо выполнить частичное обновление, то очень полезно использовать параметр `exclude_unset` в методе `.dict()` модели Pydantic.
+Если вы хотите получать частичные обновления, очень полезно использовать параметр `exclude_unset` в `.model_dump()` модели Pydantic.
-Например, `item.dict(exclude_unset=True)`.
+Например, `item.model_dump(exclude_unset=True)`.
-В результате будет сгенерирован словарь, содержащий только те данные, которые были заданы при создании модели `item`, без учета значений по умолчанию. Затем вы можете использовать это для создания словаря только с теми данными, которые были установлены (отправлены в запросе), опуская значения по умолчанию:
+В результате будет сгенерирован `dict`, содержащий только те данные, которые были заданы при создании модели `item`, без учета значений по умолчанию.
+
+Затем вы можете использовать это для создания `dict` только с теми данными, которые были установлены (отправлены в запросе), опуская значения по умолчанию:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
-### Использование параметра `update` в Pydantic
+### Использование параметра `update` в Pydantic { #using-pydantics-update-parameter }
-Теперь можно создать копию существующей модели, используя `.copy()`, и передать параметр `update` с `dict`, содержащим данные для обновления.
+Теперь можно создать копию существующей модели, используя `.model_copy()`, и передать параметр `update` с `dict`, содержащим данные для обновления.
-Например, `stored_item_model.copy(update=update_data)`:
+Например, `stored_item_model.model_copy(update=update_data)`:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
-### Кратко о частичном обновлении
+### Кратко о частичном обновлении { #partial-updates-recap }
В целом, для применения частичных обновлений необходимо:
* (Опционально) использовать `PATCH` вместо `PUT`.
* Извлечь сохранённые данные.
-* Поместить эти данные в Pydantic модель.
+* Поместить эти данные в Pydantic-модель.
* Сгенерировать `dict` без значений по умолчанию из входной модели (с использованием `exclude_unset`).
- * Таким образом, можно обновлять только те значения, которые действительно установлены пользователем, вместо того чтобы переопределять значения, уже сохраненные в модели по умолчанию.
+ * Таким образом, можно обновлять только те значения, которые действительно установлены пользователем, вместо того чтобы переопределять уже сохраненные значения значениями по умолчанию из вашей модели.
* Создать копию хранимой модели, обновив ее атрибуты полученными частичными обновлениями (с помощью параметра `update`).
* Преобразовать скопированную модель в то, что может быть сохранено в вашей БД (например, с помощью `jsonable_encoder`).
- * Это сравнимо с повторным использованием метода модели `.dict()`, но при этом происходит проверка (и преобразование) значений в типы данных, которые могут быть преобразованы в JSON, например, `datetime` в `str`.
+ * Это сравнимо с повторным использованием метода модели `.model_dump()`, но при этом происходит проверка (и преобразование) значений в типы данных, которые могут быть преобразованы в JSON, например, `datetime` в `str`.
* Сохранить данные в своей БД.
* Вернуть обновленную модель.
@@ -81,7 +83,7 @@
/// tip | Подсказка
-Эту же технику можно использовать и для операции HTTP `PUT`.
+На самом деле эту же технику можно использовать и для операции HTTP `PUT`.
Но в приведенном примере используется `PATCH`, поскольку он был создан именно для таких случаев использования.
diff --git a/docs/ru/docs/tutorial/body.md b/docs/ru/docs/tutorial/body.md
index 2c9110226..537d7ebc9 100644
--- a/docs/ru/docs/tutorial/body.md
+++ b/docs/ru/docs/tutorial/body.md
@@ -1,40 +1,41 @@
-# Тело запроса
+# Тело запроса { #request-body }
-Когда вам необходимо отправить данные из клиента (допустим, браузера) в ваш API, вы отправляете их как **тело запроса**.
+Когда вам необходимо отправить данные из клиента (например, браузера) в ваш API, вы отправляете их как **тело запроса**.
-Тело **запроса** --- это данные, отправляемые клиентом в ваш API. Тело **ответа** --- это данные, которые ваш API отправляет клиенту.
+Тело **запроса** — это данные, отправляемые клиентом в ваш API. Тело **ответа** — это данные, которые ваш API отправляет клиенту.
-Ваш API почти всегда отправляет тело **ответа**. Но клиентам не обязательно всегда отправлять тело **запроса**.
+Ваш API почти всегда должен отправлять тело **ответа**. Но клиентам не обязательно всегда отправлять **тело запроса**: иногда они запрашивают только путь, возможно с некоторыми параметрами запроса, но без тела.
-Чтобы объявить тело **запроса**, необходимо использовать модели Pydantic, со всей их мощью и преимуществами.
+Чтобы объявить тело **запроса**, используйте модели Pydantic, со всей их мощью и преимуществами.
/// info | Информация
-Чтобы отправить данные, необходимо использовать один из методов: `POST` (обычно), `PUT`, `DELETE` или `PATCH`.
+Чтобы отправить данные, используйте один из методов: `POST` (чаще всего), `PUT`, `DELETE` или `PATCH`.
-Отправка тела с запросом `GET` имеет неопределенное поведение в спецификациях, тем не менее, оно поддерживается FastAPI только для очень сложных/экстремальных случаев использования.
+Отправка тела с запросом `GET` имеет неопределённое поведение в спецификациях, тем не менее это поддерживается FastAPI, но только для очень сложных/крайних случаев использования.
-Поскольку это не рекомендуется, интерактивная документация со Swagger UI не будет отображать информацию для тела при использовании метода GET, а промежуточные прокси-серверы могут не поддерживать такой вариант запроса.
+Поскольку это не рекомендуется, интерактивная документация со Swagger UI не будет отображать информацию для тела при использовании `GET`, а промежуточные прокси-серверы могут не поддерживать такой вариант запроса.
///
-## Импортирование `BaseModel` из Pydantic
+## Импортируйте `BaseModel` из Pydantic { #import-pydantics-basemodel }
-Первое, что вам необходимо сделать, это импортировать `BaseModel` из пакета `pydantic`:
+Первое, что нужно сделать, — импортировать `BaseModel` из пакета `pydantic`:
-{* ../../docs_src/body/tutorial001.py hl[4] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## Создание вашей собственной модели
+## Создайте модель данных { #create-your-data-model }
-После этого вы описываете вашу модель данных как класс, наследующий от `BaseModel`.
+Затем опишите свою модель данных как класс, наследующийся от `BaseModel`.
-Используйте аннотации типов Python для всех атрибутов:
+Используйте стандартные типы Python для всех атрибутов:
-{* ../../docs_src/body/tutorial001.py hl[7:11] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
-Также как и при описании параметров запроса, когда атрибут модели имеет значение по умолчанию, он является необязательным. Иначе он обязателен. Используйте `None`, чтобы сделать его необязательным без использования конкретных значений по умолчанию.
-Например, модель выше описывает вот такой JSON "объект" (или словарь Python):
+Так же, как при объявлении параметров запроса: когда атрибут модели имеет значение по умолчанию, он не обязателен. Иначе он обязателен. Используйте `None`, чтобы сделать его просто необязательным.
+
+Например, модель выше описывает такой JSON "`object`" (или Python `dict`):
```JSON
{
@@ -45,7 +46,7 @@
}
```
-...поскольку `description` и `tax` являются необязательными (с `None` в качестве значения по умолчанию), вот такой JSON "объект" также подходит:
+...так как `description` и `tax` являются необязательными (со значением по умолчанию `None`), такой JSON "`object`" тоже будет корректным:
```JSON
{
@@ -54,109 +55,112 @@
}
```
-## Объявление как параметра функции
+## Объявите её как параметр { #declare-it-as-a-parameter }
-Чтобы добавить параметр к вашему *обработчику*, объявите его также, как вы объявляли параметры пути или параметры запроса:
+Чтобы добавить её в вашу *операцию пути*, объявите её так же, как вы объявляли параметры пути и параметры запроса:
-{* ../../docs_src/body/tutorial001.py hl[18] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
-...и укажите созданную модель в качестве типа параметра, `Item`.
+...и укажите тип параметра как созданную вами модель, `Item`.
-## Результаты
+## Результаты { #results }
-Всего лишь с помощью аннотации типов Python, **FastAPI**:
+Всего лишь с этой аннотацией типов Python **FastAPI**:
-* Читает тело запроса как JSON.
-* Приводит к соответствующим типам (если есть необходимость).
-* Проверяет корректность данных.
- * Если данные некорректны, будет возращена читаемая и понятная ошибка, показывающая что именно и в каком месте некорректно в данных.
-* Складывает полученные данные в параметр `item`.
- * Поскольку внутри функции вы объявили его с типом `Item`, то теперь у вас есть поддержка со стороны редактора (автодополнение и т.п.) для всех атрибутов и их типов.
-* Генерирует декларативное описание модели в виде JSON Schema, так что вы можете его использовать где угодно, если это имеет значение для вашего проекта.
-* Эти схемы являются частью сгенерированной схемы OpenAPI и используются для автоматического документирования UI.
+* Считает тело запроса как JSON.
+* Приведёт данные к соответствующим типам (если потребуется).
+* Проведёт валидацию данных.
+ * Если данные некорректны, вернёт понятную и наглядную ошибку, указывающую, где именно и что было некорректно.
+* Передаст полученные данные в параметр `item`.
+ * Поскольку внутри функции вы объявили его с типом `Item`, у вас будет поддержка со стороны редактора кода (автозавершение и т. п.) для всех атрибутов и их типов.
+* Сгенерирует определения JSON Schema для вашей модели; вы можете использовать их и в других местах, если это имеет смысл для вашего проекта.
+* Эти схемы будут частью сгенерированной схемы OpenAPI и будут использоваться автоматической документацией UIs.
-## Автоматическое документирование
+## Автоматическая документация { #automatic-docs }
-Схема JSON ваших моделей будет частью сгенерированной схемы OpenAPI и будет отображена в интерактивной документации API:
+JSON Schema ваших моделей будет частью сгенерированной схемы OpenAPI и будет отображаться в интерактивной документации API:
-Также она будет указана в документации по API внутри каждой *операции пути*, в которой используются:
+А также они будут использоваться в документации API внутри каждой *операции пути*, где это требуется:
-## Поддержка редактора
+## Поддержка редактора кода { #editor-support }
-В вашем редакторе внутри вашей функции у вас будут подсказки по типам и автодополнение (это не будет работать, если вы получаете словарь вместо модели Pydantic):
+В вашем редакторе кода внутри функции вы получите подсказки по типам и автозавершение повсюду (этого бы не было, если бы вы получали `dict` вместо модели Pydantic):
-Также вы будете получать ошибки в случае несоответствия типов:
+Также вы получите проверку ошибок при некорректных операциях с типами:
-Это не случайно, весь фреймворк построен вокруг такого дизайна.
+Это не случайность — весь фреймворк построен вокруг такого дизайна.
-И это все тщательно протестировано еще на этапе разработки дизайна, до реализации, чтобы это работало со всеми редакторами.
+И это было тщательно протестировано ещё на этапе проектирования, до реализации, чтобы убедиться, что всё будет работать со всеми редакторами.
-Для поддержки этого даже были внесены некоторые изменения в сам Pydantic.
+В сам Pydantic даже были внесены некоторые изменения для поддержки этого.
-На всех предыдущих скриншотах используется Visual Studio Code.
+Предыдущие скриншоты сделаны в Visual Studio Code.
-Но у вас будет такая же поддержка и с PyCharm, и вообще с любым редактором Python:
+Но вы получите такую же поддержку редактора кода в PyCharm и большинстве других редакторов Python:
-/// tip | Подсказка
+/// tip | Совет
-Если вы используете PyCharm в качестве редактора, то вам стоит попробовать плагин Pydantic PyCharm Plugin.
+Если вы используете PyCharm в качестве редактора кода, вы можете использовать плагин Pydantic PyCharm Plugin.
-Он улучшает поддержку редактором моделей Pydantic в части:
+Он улучшает поддержку моделей Pydantic в редакторе кода, включая:
-* автодополнения,
-* проверки типов,
-* рефакторинга,
-* поиска,
-* инспектирования.
+* автозавершение
+* проверки типов
+* рефакторинг
+* поиск
+* инспекции
///
-## Использование модели
+## Использование модели { #use-the-model }
Внутри функции вам доступны все атрибуты объекта модели напрямую:
-{* ../../docs_src/body/tutorial002.py hl[21] *}
+{* ../../docs_src/body/tutorial002_py310.py *}
+
+## Тело запроса + параметры пути { #request-body-path-parameters }
-## Тело запроса + параметры пути
+Вы можете одновременно объявить параметры пути и тело запроса.
-Вы можете одновременно объявлять параметры пути и тело запроса.
+**FastAPI** распознает, что параметры функции, соответствующие параметрам пути, должны быть **получены из пути**, а параметры функции, объявленные как модели Pydantic, должны быть **получены из тела запроса**.
-**FastAPI** распознает, какие параметры функции соответствуют параметрам пути и должны быть **получены из пути**, а какие параметры функции, объявленные как модели Pydantic, должны быть **получены из тела запроса**.
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-{* ../../docs_src/body/tutorial003.py hl[17:18] *}
-## Тело запроса + параметры пути + параметры запроса
+## Тело запроса + параметры пути + параметры запроса { #request-body-path-query-parameters }
-Вы также можете одновременно объявить параметры для **пути**, **запроса** и **тела запроса**.
+Вы также можете одновременно объявить параметры **тела**, **пути** и **запроса**.
-**FastAPI** распознает каждый из них и возьмет данные из правильного источника.
+**FastAPI** распознает каждый из них и возьмёт данные из правильного источника.
-{* ../../docs_src/body/tutorial004.py hl[18] *}
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
-Параметры функции распознаются следующим образом:
+Параметры функции будут распознаны следующим образом:
-* Если параметр также указан в **пути**, то он будет использоваться как параметр пути.
-* Если аннотация типа параметра содержит **примитивный тип** (`int`, `float`, `str`, `bool` и т.п.), он будет интерпретирован как параметр **запроса**.
-* Если аннотация типа параметра представляет собой **модель Pydantic**, он будет интерпретирован как параметр **тела запроса**.
+* Если параметр также объявлен в **пути**, он будет использоваться как path-параметр.
+* Если параметр имеет **скалярный тип** (например, `int`, `float`, `str`, `bool` и т. п.), он будет интерпретирован как параметр **запроса**.
+* Если параметр объявлен как тип **модели Pydantic**, он будет интерпретирован как **тело** запроса.
/// note | Заметка
-FastAPI понимает, что значение параметра `q` не является обязательным, потому что имеет значение по умолчанию `= None`.
+FastAPI понимает, что значение `q` не является обязательным из-за значения по умолчанию `= None`.
+
+Аннотации типов `str | None` (Python 3.10+) или `Union` в `Union[str, None]` (Python 3.9+) не используются FastAPI для определения обязательности; он узнает, что параметр не обязателен, потому что у него есть значение по умолчанию `= None`.
-Аннотация `Optional` в `Optional[str]` не используется FastAPI, но помогает вашему редактору лучше понимать ваш код и обнаруживать ошибки.
+Но добавление аннотаций типов позволит вашему редактору кода лучше вас поддерживать и обнаруживать ошибки.
///
-## Без Pydantic
+## Без Pydantic { #without-pydantic }
-Если вы не хотите использовать модели Pydantic, вы все еще можете использовать параметры **тела запроса**. Читайте в документации раздел [Тело - Несколько параметров: Единичные значения в теле](body-multiple-params.md#_2){.internal-link target=_blank}.
+Если вы не хотите использовать модели Pydantic, вы также можете использовать параметры **Body**. См. раздел документации [Тело запроса - Несколько параметров: Единичные значения в теле](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/ru/docs/tutorial/cookie-param-models.md b/docs/ru/docs/tutorial/cookie-param-models.md
index 3a57443bb..182813afd 100644
--- a/docs/ru/docs/tutorial/cookie-param-models.md
+++ b/docs/ru/docs/tutorial/cookie-param-models.md
@@ -1,4 +1,4 @@
-# Модели параметров cookie
+# Модели параметров cookie { #cookie-parameter-models }
Если у вас есть группа **cookies**, которые связаны между собой, вы можете создать **Pydantic-модель** для их объявления. 🍪
@@ -16,7 +16,7 @@
///
-## Pydantic-модель для cookies
+## Pydantic-модель для cookies { #cookies-with-a-pydantic-model }
Объявите параметры **cookie**, которые вам нужны, в **Pydantic-модели**, а затем объявите параметр как `Cookie`:
@@ -24,7 +24,7 @@
**FastAPI** **извлечёт** данные для **каждого поля** из **cookies**, полученных в запросе, и выдаст вам объявленную Pydantic-модель.
-## Проверка сгенерированной документации
+## Проверка сгенерированной документации { #check-the-docs }
Вы можете посмотреть объявленные cookies в графическом интерфейсе Документации по пути `/docs`:
@@ -42,7 +42,7 @@
///
-## Запрет дополнительных cookies
+## Запрет дополнительных cookies { #forbid-extra-cookies }
В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** cookies, которые вы хотите получать.
@@ -50,7 +50,7 @@
Вы можете сконфигурировать Pydantic-модель так, чтобы запретить (`forbid`) любые дополнительные (`extra`) поля:
-{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
Если клиент попробует отправить **дополнительные cookies**, то в ответ он получит **ошибку**.
@@ -65,12 +65,12 @@
"type": "extra_forbidden",
"loc": ["cookie", "santa_tracker"],
"msg": "Extra inputs are not permitted",
- "input": "good-list-please"
+ "input": "good-list-please",
}
]
}
```
-## Заключение
+## Заключение { #summary }
Вы можете использовать **Pydantic-модели** для объявления **cookies** в **FastAPI**. 😎
diff --git a/docs/ru/docs/tutorial/cookie-params.md b/docs/ru/docs/tutorial/cookie-params.md
index d1ed943d7..2d2eff8d7 100644
--- a/docs/ru/docs/tutorial/cookie-params.md
+++ b/docs/ru/docs/tutorial/cookie-params.md
@@ -1,20 +1,20 @@
-# Параметры Cookie
+# Параметры Cookie { #cookie-parameters }
Вы можете задать параметры Cookie таким же способом, как `Query` и `Path` параметры.
-## Импорт `Cookie`
+## Импорт `Cookie` { #import-cookie }
Сначала импортируйте `Cookie`:
-{* ../../docs_src/cookie_params/tutorial001_py310.py hl[1] *}
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## Объявление параметров `Cookie`
+## Объявление параметров `Cookie` { #declare-cookie-parameters }
Затем объявляйте параметры cookie, используя ту же структуру, что и с `Path` и `Query`.
-Первое значение - это значение по умолчанию, вы можете передать все дополнительные параметры проверки или аннотации:
+Вы можете задать значение по умолчанию, а также все дополнительные параметры валидации или аннотации:
-{* ../../docs_src/cookie_params/tutorial001_py310.py hl[7] *}
+{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
/// note | Технические детали
@@ -30,6 +30,16 @@
///
-## Резюме
+/// info | Дополнительная информация
+
+Имейте в виду, что, поскольку браузеры обрабатывают cookies особым образом и «за кулисами», они не позволяют JavaScript просто так получать к ним доступ.
+
+Если вы откроете интерфейс документации API на `/docs`, вы сможете увидеть документацию по cookies для ваших операций пути.
+
+Но даже если вы заполните данные и нажмёте «Execute», поскольку UI документации работает с JavaScript, cookies отправлены не будут, и вы увидите сообщение об ошибке, как будто вы не указали никаких значений.
+
+///
+
+## Резюме { #recap }
Объявляйте cookies с помощью `Cookie`, используя тот же общий шаблон, что и `Query`, и `Path`.
diff --git a/docs/ru/docs/tutorial/cors.md b/docs/ru/docs/tutorial/cors.md
index e8bf04576..d09a31e2c 100644
--- a/docs/ru/docs/tutorial/cors.md
+++ b/docs/ru/docs/tutorial/cors.md
@@ -1,10 +1,10 @@
-# CORS (Cross-Origin Resource Sharing)
+# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
Понятие CORS или "Cross-Origin Resource Sharing" относится к ситуациям, при которых запущенный в браузере фронтенд содержит JavaScript-код, который взаимодействует с бэкендом, находящимся на другом "источнике" ("origin").
-## Источник
+## Источник { #origin }
-Источник - это совокупность протокола (`http`, `https`), домена (`myapp.com`, `localhost`, `localhost.tiangolo.com`) и порта (`80`, `443`, `8080`).
+Источник — это совокупность протокола (`http`, `https`), домена (`myapp.com`, `localhost`, `localhost.tiangolo.com`) и порта (`80`, `443`, `8080`).
Поэтому это три разных источника:
@@ -12,69 +12,72 @@
* `https://localhost`
* `http://localhost:8080`
-Даже если они все расположены в `localhost`, они используют разные протоколы и порты, а значит, являются разными источниками.
+Даже если они все расположены в `localhost`, они используют разные протоколы или порты, а значит, являются разными источниками.
-## Шаги
+## Шаги { #steps }
-Допустим, у вас есть фронтенд, запущенный в браузере по адресу `http://localhost:8080`, и его JavaScript-код пытается взаимодействовать с бэкендом, запущенным по адресу `http://localhost` (поскольку мы не указали порт, браузер по умолчанию будет использовать порт `80`).
+Допустим, у вас есть фронтенд, запущенный в браузере по адресу `http://localhost:8080`, и его JavaScript-код пытается взаимодействовать с бэкендом, запущенным по адресу `http://localhost` (поскольку мы не указали порт, браузер по умолчанию будет использовать порт `80`).
-Затем браузер отправит бэкенду HTTP-запрос `OPTIONS`, и если бэкенд вернёт соответствующие заголовки для авторизации взаимодействия с другим источником (`http://localhost:8080`), то браузер разрешит JavaScript-коду на фронтенде отправить запрос на этот бэкенд.
+Затем браузер отправит на бэкенд на `:80` HTTP-запрос `OPTIONS`, и если бэкенд вернёт соответствующие HTTP-заголовки, авторизующие взаимодействие с другим источником (`http://localhost:8080`), то браузер на `:8080` разрешит JavaScript на фронтенде отправить свой запрос на бэкенд на `:80`.
-Чтобы это работало, у бэкенда должен быть список "разрешённых источников" ("allowed origins").
+Чтобы это работало, у бэкенда на `:80` должен быть список "разрешённых источников" ("allowed origins").
-В таком случае этот список должен содержать `http://localhost:8080`, чтобы фронтенд работал корректно.
+В таком случае этот список должен содержать `http://localhost:8080`, чтобы фронтенд на `:8080` работал корректно.
-## Подстановочный символ `"*"`
+## Подстановочный символ "*" { #wildcards }
В качестве списка источников можно указать подстановочный символ `"*"` ("wildcard"), чтобы разрешить любые источники.
-Но тогда не будут разрешены некоторые виды взаимодействия, включая всё связанное с учётными данными: куки, заголовки Authorization с Bearer-токенами наподобие тех, которые мы использовали ранее и т.п.
+Но тогда будут разрешены только некоторые виды взаимодействия, и всё, что связано с учётными данными, будет исключено: куки, HTTP-заголовки Authorization, как при использовании Bearer-токенов, и т.п.
Поэтому, чтобы всё работало корректно, лучше явно указывать список разрешённых источников.
-## Использование `CORSMiddleware`
+## Использование `CORSMiddleware` { #use-corsmiddleware }
-Вы можете настроить этот механизм в вашем **FastAPI** приложении, используя `CORSMiddleware`.
+Вы можете настроить это в вашем **FastAPI**-приложении, используя `CORSMiddleware`.
* Импортируйте `CORSMiddleware`.
* Создайте список разрешённых источников (в виде строк).
-* Добавьте его как "middleware" к вашему **FastAPI** приложению.
+* Добавьте его как "middleware" (промежуточный слой) к вашему **FastAPI**-приложению.
Вы также можете указать, разрешает ли ваш бэкенд использование:
-* Учётных данных (включая заголовки Authorization, куки и т.п.).
+* Учётных данных (HTTP-заголовки Authorization, куки и т.п.).
* Отдельных HTTP-методов (`POST`, `PUT`) или всех вместе, используя `"*"`.
* Отдельных HTTP-заголовков или всех вместе, используя `"*"`.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
-`CORSMiddleware` использует для параметров "запрещающие" значения по умолчанию, поэтому вам нужно явным образом разрешить использование отдельных источников, методов или заголовков, чтобы браузеры могли использовать их в кросс-доменном контексте.
+`CORSMiddleware` использует "запрещающие" значения по умолчанию, поэтому вам нужно явным образом разрешить использование отдельных источников, методов или заголовков, чтобы браузеры могли использовать их в кросс-доменном контексте.
Поддерживаются следующие аргументы:
* `allow_origins` - Список источников, на которые разрешено выполнять кросс-доменные запросы. Например, `['https://example.org', 'https://www.example.org']`. Можно использовать `['*']`, чтобы разрешить любые источники.
-* `allow_origin_regex` - Регулярное выражение для определения источников, на которые разрешено выполнять кросс-доменные запросы. Например, `'https://.*\.example\.org'`.
-* `allow_methods` - Список HTTP-методов, которые разрешены для кросс-доменных запросов. По умолчанию равно `['GET']`. Можно использовать `['*']`, чтобы разрешить все стандартные методы.
-* `allow_headers` - Список HTTP-заголовков, которые должны поддерживаться при кросс-доменных запросах. По умолчанию равно `[]`. Можно использовать `['*']`, чтобы разрешить все заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` и `Content-Type` всегда разрешены для простых CORS-запросов.
-* `allow_credentials` - указывает, что куки разрешены в кросс-доменных запросах. По умолчанию равно `False`. Также, `allow_origins` нельзя присвоить `['*']`, если разрешено использование учётных данных. В таком случае должен быть указан список источников.
-* `expose_headers` - Указывает любые заголовки ответа, которые должны быть доступны браузеру. По умолчанию равно `[]`.
-* `max_age` - Устанавливает максимальное время в секундах, в течение которого браузер кэширует CORS-ответы. По умолчанию равно `600`.
+* `allow_origin_regex` - Регулярное выражение для определения источников, на которые разрешено выполнять кросс-доменные запросы. Например, `'https://.*\.example\.org'`.
+* `allow_methods` - Список HTTP-методов, которые разрешены для кросс-доменных запросов. По умолчанию `['GET']`. Можно использовать `['*']`, чтобы разрешить все стандартные методы.
+* `allow_headers` - Список HTTP-заголовков запроса, которые должны поддерживаться при кросс-доменных запросах. По умолчанию `[]`. Можно использовать `['*']`, чтобы разрешить все заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` и `Content-Type` всегда разрешены для простых CORS-запросов.
+* `allow_credentials` - Указывает, что куки разрешены в кросс-доменных запросах. По умолчанию `False`.
+
+ Ни один из параметров `allow_origins`, `allow_methods` и `allow_headers` не может быть установлен в `['*']`, если `allow_credentials` имеет значение `True`. Все они должны быть указаны явно.
+
+* `expose_headers` - Указывает любые заголовки ответа, которые должны быть доступны браузеру. По умолчанию `[]`.
+* `max_age` - Устанавливает максимальное время в секундах, в течение которого браузер кэширует CORS-ответы. По умолчанию `600`.
`CORSMiddleware` отвечает на два типа HTTP-запросов...
-### CORS-запросы с предварительной проверкой
+### CORS-запросы с предварительной проверкой { #cors-preflight-requests }
-Это любые `OPTIONS` запросы с заголовками `Origin` и `Access-Control-Request-Method`.
+Это любые `OPTIONS`-запросы с заголовками `Origin` и `Access-Control-Request-Method`.
В этом случае middleware перехватит входящий запрос и отправит соответствующие CORS-заголовки в ответе, а также ответ `200` или `400` в информационных целях.
-### Простые запросы
+### Простые запросы { #simple-requests }
Любые запросы с заголовком `Origin`. В этом случае middleware передаст запрос дальше как обычно, но добавит соответствующие CORS-заголовки к ответу.
-## Больше информации
+## Больше информации { #more-info }
-Для получения более подробной информации о CORS, обратитесь к Документации CORS от Mozilla.
+Для получения более подробной информации о CORS обратитесь к документации CORS от Mozilla.
/// note | Технические детали
diff --git a/docs/ru/docs/tutorial/debugging.md b/docs/ru/docs/tutorial/debugging.md
index 05806f087..51955835e 100644
--- a/docs/ru/docs/tutorial/debugging.md
+++ b/docs/ru/docs/tutorial/debugging.md
@@ -1,14 +1,14 @@
-# Отладка
+# Отладка { #debugging }
Вы можете подключить отладчик в своем редакторе, например, в Visual Studio Code или PyCharm.
-## Вызов `uvicorn`
+## Вызов `uvicorn` { #call-uvicorn }
В вашем FastAPI приложении, импортируйте и вызовите `uvicorn` напрямую:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### Описание `__name__ == "__main__"`
+### Описание `__name__ == "__main__"` { #about-name-main }
Главная цель использования `__name__ == "__main__"` в том, чтобы код выполнялся при запуске файла с помощью:
@@ -26,7 +26,7 @@ $ python myapp.py
from myapp import app
```
-#### Больше деталей
+#### Больше деталей { #more-details }
Давайте назовём ваш файл `myapp.py`.
@@ -78,7 +78,7 @@ from myapp import app
///
-## Запуск вашего кода с помощью отладчика
+## Запуск вашего кода с помощью отладчика { #run-your-code-with-your-debugger }
Так как вы запускаете сервер Uvicorn непосредственно из вашего кода, вы можете вызвать Python программу (ваше FastAPI приложение) напрямую из отладчика.
diff --git a/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md
index 8037872b9..a38e885d4 100644
--- a/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/ru/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -1,28 +1,30 @@
-# Классы как зависимости
+# Классы как зависимости { #classes-as-dependencies }
Прежде чем углубиться в систему **Внедрения Зависимостей**, давайте обновим предыдущий пример.
-## `Словарь` из предыдущего примера
+## `dict` из предыдущего примера { #a-dict-from-the-previous-example }
-В предыдущем примере мы возвращали `словарь` из нашей зависимости:
+В предыдущем примере мы возвращали `dict` из нашей зависимости:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[9] *}
-Но затем мы получаем `словарь` в параметре `commons` *функции операции пути*. И мы знаем, что редакторы не могут обеспечить достаточную поддержку для `словаря`, поскольку они не могут знать их ключи и типы значений.
+Но затем мы получаем `dict` в параметре `commons` *функции-обработчика пути*.
+
+И мы знаем, что редакторы кода не могут обеспечить достаточную поддержку (например, автозавершение) для `dict`, поскольку они не могут знать их ключи и типы значений.
Мы можем сделать лучше...
-## Что делает зависимость
+## Что делает зависимость { #what-makes-a-dependency }
До сих пор вы видели зависимости, объявленные как функции.
-Но это не единственный способ объявления зависимостей (хотя, вероятно, более распространенный).
+Но это не единственный способ объявления зависимостей (хотя он, вероятно, более распространенный).
-Ключевым фактором является то, что зависимость должна быть "вызываемой".
+Ключевым фактором является то, что зависимость должна быть «вызываемой».
-В Python "**вызываемый**" - это все, что Python может "вызвать", как функцию.
+В Python «**вызываемый**» — это всё, что Python может «вызвать», как функцию.
-Так, если у вас есть объект `something` (который может _не_ быть функцией) и вы можете "вызвать" его (выполнить) как:
+Так, если у вас есть объект `something` (который может и _не_ быть функцией) и вы можете «вызвать» его (выполнить) так:
```Python
something()
@@ -34,9 +36,9 @@ something()
something(some_argument, some_keyword_argument="foo")
```
-в таком случае он является "вызываемым".
+в таком случае он является «вызываемым».
-## Классы как зависимости
+## Классы как зависимости { #classes-as-dependencies_1 }
Вы можете заметить, что для создания экземпляра класса в Python используется тот же синтаксис.
@@ -53,17 +55,17 @@ fluffy = Cat(name="Mr Fluffy")
В данном случае `fluffy` является экземпляром класса `Cat`.
-А чтобы создать `fluffy`, вы "вызываете" `Cat`.
+А чтобы создать `fluffy`, вы «вызываете» `Cat`.
Таким образом, класс в Python также является **вызываемым**.
Тогда в **FastAPI** в качестве зависимости можно использовать класс Python.
-На самом деле FastAPI проверяет, что переданный объект является "вызываемым" (функция, класс или что-либо еще) и указаны необходимые для его вызова параметры.
+На самом деле FastAPI проверяет, что переданный объект является «вызываемым» (функция, класс или что-либо еще) и какие параметры у него определены.
-Если вы передаёте что-то, что можно "вызывать" в качестве зависимости в **FastAPI**, то он будет анализировать параметры, необходимые для "вызова" этого объекта и обрабатывать их так же, как параметры *функции операции пути*. Включая подзависимости.
+Если вы передаёте «вызываемый» объект в качестве зависимости в **FastAPI**, он проанализирует параметры, необходимые для этого «вызываемого» объекта, и обработает их так же, как параметры *функции-обработчика пути*. Включая подзависимости.
-Это относится и к вызываемым объектам без параметров. Работа с ними происходит точно так же, как и для *функций операции пути* без параметров.
+Это относится и к вызываемым объектам без параметров. Работа с ними происходит точно так же, как и для *функций-обработчиков пути* без параметров.
Теперь мы можем изменить зависимость `common_parameters`, указанную выше, на класс `CommonQueryParams`:
@@ -73,55 +75,55 @@ fluffy = Cat(name="Mr Fluffy")
{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[12] *}
-...имеет те же параметры, что и ранее используемая функция `common_parameters`:
+...он имеет те же параметры, что и ранее используемая функция `common_parameters`:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8] *}
-Эти параметры и будут использоваться **FastAPI** для "решения" зависимости.
+Эти параметры и будут использоваться **FastAPI** для «решения» зависимости.
В обоих случаях она будет иметь:
* Необязательный параметр запроса `q`, представляющий собой `str`.
* Параметр запроса `skip`, представляющий собой `int`, по умолчанию `0`.
-* Параметр запроса `limit`, представляющий собой `int`, по умолчанию равный `100`.
+* Параметр запроса `limit`, представляющий собой `int`, по умолчанию `100`.
-В обоих случаях данные будут конвертированы, валидированы, документированы по схеме OpenAPI и т.д.
+В обоих случаях данные будут конвертированы, валидированы, задокументированы в схеме OpenAPI и т.д.
-## Как это использовать
+## Как это использовать { #use-it }
Теперь вы можете объявить свою зависимость, используя этот класс.
{* ../../docs_src/dependencies/tutorial002_an_py310.py hl[19] *}
-**FastAPI** вызывает класс `CommonQueryParams`. При этом создается "экземпляр" этого класса, который будет передан в качестве параметра `commons` в вашу функцию.
+**FastAPI** вызывает класс `CommonQueryParams`. При этом создается «экземпляр» этого класса, который будет передан в качестве параметра `commons` в вашу функцию.
-## Аннотация типа или `Depends`
+## Аннотация типа и `Depends` { #type-annotation-vs-depends }
Обратите внимание, что в приведенном выше коде мы два раза пишем `CommonQueryParams`:
-//// tab | Python 3.6+ без Annotated
-
-/// tip | Подсказка
-
-Рекомендуется использовать версию с `Annotated` если возможно.
-
-///
+//// tab | Python 3.9+
```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
```
////
-//// tab | Python 3.6+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | Подсказка
+
+Рекомендуется использовать версию с `Annotated`, если возможно.
+
+///
```Python
-commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+commons: CommonQueryParams = Depends(CommonQueryParams)
```
////
-Последний параметр `CommonQueryParams`, в:
+Последний `CommonQueryParams`, в:
```Python
... Depends(CommonQueryParams)
@@ -129,13 +131,13 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
...это то, что **FastAPI** будет использовать, чтобы узнать, что является зависимостью.
-Из него FastAPI извлечёт объявленные параметры и именно их будет вызывать.
+Из него FastAPI извлечёт объявленные параметры, и именно его FastAPI будет вызывать.
---
В этом случае первый `CommonQueryParams`, в:
-//// tab | Python 3.6+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, ...
@@ -143,11 +145,11 @@ commons: Annotated[CommonQueryParams, ...
////
-//// tab | Python 3.6+ без Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Подсказка
-Рекомендуется использовать версию с `Annotated` если возможно.
+Рекомендуется использовать версию с `Annotated`, если возможно.
///
@@ -161,7 +163,7 @@ commons: CommonQueryParams ...
На самом деле можно написать просто:
-//// tab | Python 3.6+
+//// tab | Python 3.9+
```Python
commons: Annotated[Any, Depends(CommonQueryParams)]
@@ -169,11 +171,11 @@ commons: Annotated[Any, Depends(CommonQueryParams)]
////
-//// tab | Python 3.6+ без Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Подсказка
-Рекомендуется использовать версию с `Annotated` если возможно.
+Рекомендуется использовать версию с `Annotated`, если возможно.
///
@@ -187,42 +189,43 @@ commons = Depends(CommonQueryParams)
{* ../../docs_src/dependencies/tutorial003_an_py310.py hl[19] *}
-Но объявление типа приветствуется, так как в этом случае ваш редактор будет знать, что будет передано в качестве параметра `commons`, и тогда он сможет помочь вам с автодополнением, проверкой типов и т.д:
+Но объявление типа приветствуется, так как в этом случае ваш редактор кода будет знать, что будет передано в качестве параметра `commons`, и тогда он сможет помочь вам с автозавершением, проверкой типов и т.д.:
-## Сокращение
+## Сокращение { #shortcut }
Но вы видите, что здесь мы имеем некоторое повторение кода, дважды написав `CommonQueryParams`:
-//// tab | Python 3.6+ без Annotated
-
-/// tip | Подсказка
-
-Рекомендуется использовать версию с `Annotated` если возможно.
-
-///
+//// tab | Python 3.9+
```Python
-commons: CommonQueryParams = Depends(CommonQueryParams)
+commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
```
////
-//// tab | Python 3.6+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | Подсказка
+
+Рекомендуется использовать версию с `Annotated`, если возможно.
+
+///
```Python
-commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
+commons: CommonQueryParams = Depends(CommonQueryParams)
```
////
-Для случаев, когда зависимостью является *конкретный* класс, который **FastAPI** "вызовет" для создания экземпляра этого класса, можно использовать укороченную запись.
+**FastAPI** предоставляет сокращение для таких случаев, когда зависимость — это *конкретный* класс, который **FastAPI** будет «вызывать» для создания экземпляра этого класса.
+Для этих конкретных случаев вы можете сделать следующее.
Вместо того чтобы писать:
-//// tab | Python 3.6+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
@@ -230,11 +233,11 @@ commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]
////
-//// tab | Python 3.6+ без Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Подсказка
-Рекомендуется использовать версию с `Annotated` если возможно.
+Рекомендуется использовать версию с `Annotated`, если возможно.
///
@@ -246,7 +249,7 @@ commons: CommonQueryParams = Depends(CommonQueryParams)
...следует написать:
-//// tab | Python 3.6+
+//// tab | Python 3.9+
```Python
commons: Annotated[CommonQueryParams, Depends()]
@@ -254,11 +257,11 @@ commons: Annotated[CommonQueryParams, Depends()]
////
-//// tab | Python 3.6 без Annotated
+//// tab | Python 3.9+ non-Annotated
/// tip | Подсказка
-Рекомендуется использовать версию с `Annotated` если возможно.
+Рекомендуется использовать версию с `Annotated`, если возможно.
///
@@ -278,7 +281,7 @@ commons: CommonQueryParams = Depends()
/// tip | Подсказка
-Если это покажется вам более запутанным, чем полезным, не обращайте внимания, это вам не *нужно*.
+Если это покажется вам более запутанным, чем полезным, не обращайте внимания — это вам не *нужно*.
Это просто сокращение. Потому что **FastAPI** заботится о том, чтобы помочь вам свести к минимуму повторение кода.
diff --git a/docs/ru/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/ru/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index 0e4eb95be..ef5664448 100644
--- a/docs/ru/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/ru/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -1,4 +1,4 @@
-# Зависимости в декораторах операции пути
+# Зависимости в декораторах операции пути { #dependencies-in-path-operation-decorators }
В некоторых случаях, возвращаемое значение зависимости не используется внутри *функции операции пути*.
@@ -8,7 +8,7 @@
Для таких ситуаций, вместо объявления *функции операции пути* с параметром `Depends`, вы можете добавить список зависимостей `dependencies` в *декоратор операции пути*.
-## Добавление `dependencies` в *декоратор операции пути*
+## Добавление `dependencies` (зависимостей) в *декоратор операции пути* { #add-dependencies-to-the-path-operation-decorator }
*Декоратор операции пути* получает необязательный аргумент `dependencies`.
@@ -36,23 +36,23 @@
///
-## Исключения в dependencies и возвращаемые значения
+## Исключения в Зависимостях и возвращаемые значения { #dependencies-errors-and-return-values }
Вы можете использовать те же *функции* зависимостей, что и обычно.
-### Требования к зависимостям
+### Требования к зависимостям { #dependency-requirements }
Они могут объявлять требования к запросу (например заголовки) или другие подзависимости:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### Вызов исключений
+### Вызов исключений { #raise-exceptions }
Зависимости из dependencies могут вызывать исключения с помощью `raise`, как и обычные зависимости:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### Возвращаемые значения
+### Возвращаемые значения { #return-values }
И они могут возвращать значения или нет, эти значения использоваться не будут.
@@ -60,10 +60,10 @@
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## Dependencies для группы *операций путей*
+## Зависимости для группы *операций путей* { #dependencies-for-a-group-of-path-operations }
-Позже, читая о том как структурировать большие приложения ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), возможно, многофайловые, вы узнаете как объявить единый параметр `dependencies` для всей группы *операций путей*.
+Позже, читая о том как структурировать большие приложения ([Большие приложения — несколько файлов](../../tutorial/bigger-applications.md){.internal-link target=_blank}), возможно, многофайловые, вы узнаете как объявить единый параметр `dependencies` для всей группы *операций путей*.
-## Глобальный Dependencies
+## Глобальные Зависимости { #global-dependencies }
Далее мы увидим, как можно добавить dependencies для всего `FastAPI` приложения, так чтобы они применялись к каждой *операции пути*.
diff --git a/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md
index e64f6777c..dc202db61 100644
--- a/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/ru/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -1,125 +1,139 @@
-# Зависимости с yield
+# Зависимости с yield { #dependencies-with-yield }
-FastAPI поддерживает зависимости, которые выполняют некоторые дополнительные действия после завершения работы.
+FastAPI поддерживает зависимости, которые выполняют некоторые дополнительные шаги после завершения.
-Для этого используйте `yield` вместо `return`, а дополнительный код напишите после него.
+Для этого используйте `yield` вместо `return`, а дополнительные шаги (код) напишите после него.
/// tip | Подсказка
-Обязательно используйте `yield` один-единственный раз.
+Убедитесь, что используете `yield` только один раз на одну зависимость.
///
/// note | Технические детали
-Любая функция, с которой может работать:
+Любая функция, с которой можно корректно использовать:
* `@contextlib.contextmanager` или
* `@contextlib.asynccontextmanager`
-будет корректно использоваться в качестве **FastAPI**-зависимости.
+будет корректной для использования в качестве зависимости **FastAPI**.
-На самом деле, FastAPI использует эту пару декораторов "под капотом".
+На самом деле, FastAPI использует эти два декоратора внутренне.
///
-## Зависимость базы данных с помощью `yield`
+## Зависимость базы данных с помощью `yield` { #a-database-dependency-with-yield }
-Например, с его помощью можно создать сессию работы с базой данных и закрыть его после завершения.
+Например, с его помощью можно создать сессию работы с базой данных и закрыть её после завершения.
-Перед созданием ответа будет выполнен только код до и включая `yield`.
+Перед созданием ответа будет выполнен только код до и включая оператор `yield`:
-{* ../../docs_src/dependencies/tutorial007.py hl[2:4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[2:4] *}
-Полученное значение и есть то, что будет внедрено в функцию операции пути и другие зависимости:
+Значение, полученное из `yield`, внедряется в *операции пути* и другие зависимости:
-{* ../../docs_src/dependencies/tutorial007.py hl[4] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[4] *}
-Код, следующий за оператором `yield`, выполняется после доставки ответа:
+Код, следующий за оператором `yield`, выполняется после ответа:
-{* ../../docs_src/dependencies/tutorial007.py hl[5:6] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[5:6] *}
/// tip | Подсказка
-Можно использовать как `async` так и обычные функции.
+Можно использовать как `async`, так и обычные функции.
-**FastAPI** это корректно обработает, и в обоих случаях будет делать то же самое, что и с обычными зависимостями.
+**FastAPI** корректно обработает каждый вариант, так же как и с обычными зависимостями.
///
-## Зависимость с `yield` и `try` одновременно
+## Зависимость с `yield` и `try` { #a-dependency-with-yield-and-try }
-Если использовать блок `try` в зависимости с `yield`, то будет получено всякое исключение, которое было выброшено при использовании зависимости.
+Если использовать блок `try` в зависимости с `yield`, то вы получите любое исключение, которое было выброшено при использовании зависимости.
-Например, если какой-то код в какой-то момент в середине, в другой зависимости или в *функции операции пути*, сделал "откат" транзакции базы данных или создал любую другую ошибку, то вы получите исключение в своей зависимости.
+Например, если какой-то код в какой-то момент в середине, в другой зависимости или в *операции пути*, сделал "откат" транзакции базы данных или создал любую другую ошибку, то вы получите это исключение в своей зависимости.
Таким образом, можно искать конкретное исключение внутри зависимости с помощью `except SomeException`.
-Таким же образом можно использовать `finally`, чтобы убедиться, что обязательные шаги при выходе выполнены, независимо от того, было ли исключение или нет.
+Точно так же можно использовать `finally`, чтобы убедиться, что обязательные шаги при выходе выполнены независимо от того, было ли исключение или нет.
-{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
+{* ../../docs_src/dependencies/tutorial007_py39.py hl[3,5] *}
-## Подзависимости с `yield`
+## Подзависимости с `yield` { #sub-dependencies-with-yield }
Вы можете иметь подзависимости и "деревья" подзависимостей любого размера и формы, и любая из них или все они могут использовать `yield`.
-**FastAPI** будет следить за тем, чтобы "код по выходу" в каждой зависимости с `yield` выполнялся в правильном порядке.
+**FastAPI** проследит за тем, чтобы «код выхода» в каждой зависимости с `yield` выполнялся в правильном порядке.
-Например, `dependency_c` может иметь зависимость от `dependency_b`, а `dependency_b` от `dependency_a`:
+Например, `dependency_c` может зависеть от `dependency_b`, а `dependency_b` — от `dependency_a`:
{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[6,14,22] *}
И все они могут использовать `yield`.
-В этом случае `dependency_c` для выполнения своего кода выхода нуждается в том, чтобы значение из `dependency_b` (здесь `dep_b`) было еще доступно.
+В этом случае `dependency_c` для выполнения своего кода выхода нуждается в том, чтобы значение из `dependency_b` (здесь `dep_b`) всё ещё было доступно.
-И, в свою очередь, `dependency_b` нуждается в том, чтобы значение из `dependency_a` (здесь `dep_a`) было доступно для ее завершающего кода.
+И, в свою очередь, `dependency_b` нуждается в том, чтобы значение из `dependency_a` (здесь `dep_a`) было доступно для её кода выхода.
{* ../../docs_src/dependencies/tutorial008_an_py39.py hl[18:19,26:27] *}
-Точно так же можно иметь часть зависимостей с `yield`, часть с `return`, и какие-то из них могут зависеть друг от друга.
+Точно так же можно иметь часть зависимостей с `yield`, часть — с `return`, и какие-то из них могут зависеть друг от друга.
Либо у вас может быть одна зависимость, которая требует несколько других зависимостей с `yield` и т.д.
-Комбинации зависимостей могут быть какими вам угодно.
+Комбинации зависимостей могут быть какими угодно.
-**FastAPI** проследит за тем, чтобы все выполнялось в правильном порядке.
+**FastAPI** проследит за тем, чтобы всё выполнялось в правильном порядке.
/// note | Технические детали
-Это работает благодаря Контекстным менеджерам в Python.
+Это работает благодаря менеджерам контекста в Python.
+
+**FastAPI** использует их внутренне для достижения этого.
///
- **FastAPI** использует их "под капотом" с этой целью.
+## Зависимости с `yield` и `HTTPException` { #dependencies-with-yield-and-httpexception }
-## Зависимости с `yield` и `HTTPException`
+Вы видели, что можно использовать зависимости с `yield` и иметь блоки `try`, которые пытаются выполнить некоторый код, а затем запускают код выхода в `finally`.
-Вы видели, что можно использовать зависимости с `yield` совместно с блоком `try`, отлавливающие исключения.
+Также вы можете использовать `except`, чтобы поймать вызванное исключение и что-то с ним сделать.
-Таким же образом вы можете поднять исключение `HTTPException` или что-то подобное в завершающем коде, после `yield`.
+Например, вы можете вызвать другое исключение, например `HTTPException`.
-Код выхода в зависимостях с `yield` выполняется *после* отправки ответа, поэтому [Обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} уже будет запущен. В коде выхода (после `yield`) нет ничего, перехватывающего исключения, брошенные вашими зависимостями.
+/// tip | Подсказка
-Таким образом, если после `yield` возникает `HTTPException`, то стандартный (или любой пользовательский) обработчик исключений, который перехватывает `HTTPException` и возвращает ответ HTTP 400, уже не сможет перехватить это исключение.
+Это довольно продвинутая техника, и в большинстве случаев она вам не понадобится, так как вы можете вызывать исключения (включая `HTTPException`) в остальном коде вашего приложения, например, в *функции-обработчике пути*.
-Благодаря этому все, что установлено в зависимости (например, сеанс работы с БД), может быть использовано, например, фоновыми задачами.
+Но если понадобится — возможность есть. 🤓
-Фоновые задачи выполняются *после* отправки ответа. Поэтому нет возможности поднять `HTTPException`, так как нет даже возможности изменить уже отправленный ответ.
+///
-Но если фоновая задача создает ошибку в БД, то, по крайней мере, можно сделать откат или чисто закрыть сессию в зависимости с помощью `yield`, а также, возможно, занести ошибку в журнал или сообщить о ней в удаленную систему отслеживания.
+{* ../../docs_src/dependencies/tutorial008b_an_py39.py hl[18:22,31] *}
-Если у вас есть код, который, как вы знаете, может вызвать исключение, сделайте самую обычную/"питонячью" вещь и добавьте блок `try` в этот участок кода.
+Если вы хотите перехватывать исключения и формировать на их основе пользовательский ответ, создайте [Пользовательский обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
-Если у вас есть пользовательские исключения, которые вы хотите обрабатывать *до* возврата ответа и, возможно, модифицировать ответ, даже вызывая `HTTPException`, создайте [Cобственный обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
+## Зависимости с `yield` и `except` { #dependencies-with-yield-and-except }
-/// tip | Подсказка
+Если вы ловите исключение с помощью `except` в зависимости с `yield` и не вызываете его снова (или не вызываете новое исключение), FastAPI не сможет заметить, что было исключение — так же, как это происходит в обычном Python:
-Вы все еще можете вызывать исключения, включая `HTTPException`, *до* `yield`. Но не после.
+{* ../../docs_src/dependencies/tutorial008c_an_py39.py hl[15:16] *}
-///
+В этом случае клиент получит *HTTP 500 Internal Server Error*, как и должно быть, поскольку мы не вызываем `HTTPException` или что-то подобное, но на сервере **не будет никаких логов** или других указаний на то, какая была ошибка. 😱
+
+### Всегда делайте `raise` в зависимостях с `yield` и `except` { #always-raise-in-dependencies-with-yield-and-except }
+
+Если вы ловите исключение в зависимости с `yield`, то, если вы не вызываете другой `HTTPException` или что-то подобное, вам следует повторно вызвать исходное исключение.
-Последовательность выполнения примерно такая, как на этой схеме. Время течет сверху вниз. А каждый столбец - это одна из частей, взаимодействующих с кодом или выполняющих код.
+Вы можете повторно вызвать то же самое исключение с помощью `raise`:
+
+{* ../../docs_src/dependencies/tutorial008d_an_py39.py hl[17] *}
+
+Теперь клиент получит тот же *HTTP 500 Internal Server Error*, но на сервере в логах будет наше пользовательское `InternalError`. 😎
+
+## Выполнение зависимостей с `yield` { #execution-of-dependencies-with-yield }
+
+Последовательность выполнения примерно такая, как на этой схеме. Время течёт сверху вниз. А каждый столбец — это одна из частей, взаимодействующих с кодом или выполняющих код.
```mermaid
sequenceDiagram
@@ -130,85 +144,101 @@ participant dep as Dep with yield
participant operation as Path Operation
participant tasks as Background tasks
- Note over client,tasks: Can raise exception for dependency, handled after response is sent
- Note over client,operation: Can raise HTTPException and can change the response
+ Note over client,operation: Can raise exceptions, including HTTPException
client ->> dep: Start request
Note over dep: Run code up to yield
- opt raise
- dep -->> handler: Raise HTTPException
+ opt raise Exception
+ dep -->> handler: Raise Exception
handler -->> client: HTTP error response
- dep -->> dep: Raise other exception
end
dep ->> operation: Run dependency, e.g. DB session
opt raise
- operation -->> dep: Raise HTTPException
- dep -->> handler: Auto forward exception
+ operation -->> dep: Raise Exception (e.g. HTTPException)
+ opt handle
+ dep -->> dep: Can catch exception, raise a new HTTPException, raise other exception
+ end
handler -->> client: HTTP error response
- operation -->> dep: Raise other exception
- dep -->> handler: Auto forward exception
end
+
operation ->> client: Return response to client
Note over client,operation: Response is already sent, can't change it anymore
opt Tasks
operation -->> tasks: Send background tasks
end
opt Raise other exception
- tasks -->> dep: Raise other exception
- end
- Note over dep: After yield
- opt Handle other exception
- dep -->> dep: Handle exception, can't change response. E.g. close DB session.
+ tasks -->> tasks: Handle exceptions in the background task code
end
```
/// info | Дополнительная информация
-Клиенту будет отправлен только **один ответ**. Это может быть один из ответов об ошибке или это будет ответ от *операции пути*.
+Клиенту будет отправлен только **один ответ**. Это может быть один из ответов об ошибке или ответ от *операции пути*.
-После отправки одного из этих ответов никакой другой ответ не может быть отправлен.
+После отправки одного из этих ответов никакой другой ответ отправить нельзя.
///
/// tip | Подсказка
-На этой диаграмме показано "HttpException", но вы также можете вызвать любое другое исключение, для которого вы создаете [Пользовательский обработчик исключений](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
-
-Если вы создадите какое-либо исключение, оно будет передано зависимостям с yield, включая `HttpException`, а затем **снова** обработчикам исключений. Если для этого исключения нет обработчика исключений, то оно будет обработано внутренним "ServerErrorMiddleware" по умолчанию, возвращающим код состояния HTTP 500, чтобы уведомить клиента, что на сервере произошла ошибка.
+Если вы вызовете какое-либо исключение в коде из *функции-обработчика пути*, оно будет передано зависимостям с `yield`, включая `HTTPException`. В большинстве случаев вы захотите повторно вызвать то же самое исключение или новое из зависимости с `yield`, чтобы убедиться, что оно корректно обработано.
///
-## Зависимости с `yield`, `HTTPException` и фоновыми задачами
+## Ранний выход и `scope` { #early-exit-and-scope }
-/// warning | Внимание
+Обычно «код выхода» зависимостей с `yield` выполняется **после того, как ответ** отправлен клиенту.
-Скорее всего, вам не нужны эти технические подробности, вы можете пропустить этот раздел и продолжить ниже.
+Но если вы знаете, что не будете использовать зависимость после возврата из *функции-обработчика пути*, вы можете использовать `Depends(scope="function")`, чтобы сообщить FastAPI, что он должен закрыть зависимость после возврата из *функции-обработчика пути*, но **до того**, как **ответ будет отправлен**.
-Эти подробности полезны, главным образом, если вы использовали версию FastAPI до 0.106.0 и использовали ресурсы из зависимостей с `yield` в фоновых задачах.
+{* ../../docs_src/dependencies/tutorial008e_an_py39.py hl[12,16] *}
-///
+`Depends()` принимает параметр `scope`, который может быть:
-До версии FastAPI 0.106.0 вызывать исключения после `yield` было невозможно, код выхода в зависимостях с `yield` выполнялся *после* отправки ответа, поэтому [Обработчик Ошибок](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} уже был бы запущен.
+* `"function"`: начать зависимость до *функции-обработчика пути*, которая обрабатывает запрос, завершить зависимость после окончания *функции-обработчика пути*, но **до того**, как ответ будет отправлен обратно клиенту. То есть функция зависимости будет выполнена **вокруг** *функции-обработчика пути*.
+* `"request"`: начать зависимость до *функции-обработчика пути*, которая обрабатывает запрос (как и при использовании `"function"`), но завершить **после** того, как ответ будет отправлен обратно клиенту. То есть функция зависимости будет выполнена **вокруг** цикла запроса (**request**) и ответа.
-Это было сделано главным образом для того, чтобы позволить использовать те же объекты, "отданные" зависимостями, внутри фоновых задач, поскольку код выхода будет выполняться после завершения фоновых задач.
+Если не указано и в зависимости есть `yield`, по умолчанию будет `scope` со значением `"request"`.
-Тем не менее, поскольку это означало бы ожидание ответа в сети, а также ненужное удержание ресурса в зависимости от доходности (например, соединение с базой данных), это было изменено в FastAPI 0.106.0.
+### `scope` для подзависимостей { #scope-for-sub-dependencies }
-/// tip | Подсказка
+Когда вы объявляете зависимость с `scope="request"` (значение по умолчанию), любая подзависимость также должна иметь `scope` равный `"request"`.
-Кроме того, фоновая задача обычно представляет собой независимый набор логики, который должен обрабатываться отдельно, со своими собственными ресурсами (например, собственным подключением к базе данных).
-Таким образом, вы, вероятно, получите более чистый код.
+Но зависимость со `scope` равным `"function"` может иметь зависимости со `scope` `"function"` и со `scope` `"request"`.
-///
+Это потому, что любая зависимость должна иметь возможность выполнить свой код выхода раньше подзависимостей, так как ей может понадобиться использовать их во время своего кода выхода.
+
+```mermaid
+sequenceDiagram
+
+participant client as Client
+participant dep_req as Зависимость scope="request"
+participant dep_func as Зависимость scope="function"
+participant operation as Функция-обработчик пути
+
+ client ->> dep_req: Запрос
+ Note over dep_req: Выполнить код до yield
+ dep_req ->> dep_func: Передать значение
+ Note over dep_func: Выполнить код до yield
+ dep_func ->> operation: Выполнить функцию-обработчик пути
+ operation ->> dep_func: Выход из функции-обработчика пути
+ Note over dep_func: Выполнить код после yield
+ Note over dep_func: ✅ Зависимость закрыта
+ dep_func ->> client: Отправить ответ клиенту
+ Note over client: Ответ отправлен
+ Note over dep_req: Выполнить код после yield
+ Note over dep_req: ✅ Зависимость закрыта
+```
-Если вы полагались на это поведение, то теперь вам следует создавать ресурсы для фоновых задач внутри самой фоновой задачи, а внутри использовать только те данные, которые не зависят от ресурсов зависимостей с `yield`.
+## Зависимости с `yield`, `HTTPException`, `except` и фоновыми задачами { #dependencies-with-yield-httpexception-except-and-background-tasks }
-Например, вместо того чтобы использовать ту же сессию базы данных, вы создадите новую сессию базы данных внутри фоновой задачи и будете получать объекты из базы данных с помощью этой новой сессии. А затем, вместо того чтобы передавать объект из базы данных в качестве параметра в функцию фоновой задачи, вы передадите идентификатор этого объекта, а затем снова получите объект в функции фоновой задачи.
+Зависимости с `yield` со временем эволюционировали, чтобы покрыть разные сценарии и исправить некоторые проблемы.
-## Контекстные менеджеры
+Если вы хотите посмотреть, что менялось в разных версиях FastAPI, вы можете прочитать об этом подробнее в продвинутом руководстве: [Продвинутые зависимости — зависимости с `yield`, `HTTPException`, `except` и фоновыми задачами](../../advanced/advanced-dependencies.md#dependencies-with-yield-httpexception-except-and-background-tasks){.internal-link target=_blank}.
+## Контекстные менеджеры { #context-managers }
-### Что такое "контекстные менеджеры"
+### Что такое «контекстные менеджеры» { #what-are-context-managers }
-"Контекстные менеджеры" - это любые объекты Python, которые можно использовать в операторе `with`.
+«Контекстные менеджеры» — это любые объекты Python, которые можно использовать в операторе `with`.
Например, можно использовать `with` для чтения файла:
@@ -218,41 +248,41 @@ with open("./somefile.txt") as f:
print(contents)
```
-Под капотом" open("./somefile.txt") создаёт объект называемый "контекстным менеджером".
+Под капотом вызов `open("./somefile.txt")` создаёт объект, называемый «контекстным менеджером».
Когда блок `with` завершается, он обязательно закрывает файл, даже если были исключения.
-Когда вы создаете зависимость с помощью `yield`, **FastAPI** внутренне преобразует ее в контекстный менеджер и объединяет с некоторыми другими связанными инструментами.
+Когда вы создаёте зависимость с `yield`, **FastAPI** внутренне создаёт для неё менеджер контекста и сочетает его с некоторыми другими связанными инструментами.
-### Использование менеджеров контекста в зависимостях с помощью `yield`
+### Использование менеджеров контекста в зависимостях с `yield` { #using-context-managers-in-dependencies-with-yield }
/// warning | Внимание
-Это более или менее "продвинутая" идея.
+Это, более или менее, «продвинутая» идея.
Если вы только начинаете работать с **FastAPI**, то лучше пока пропустить этот пункт.
///
-В Python для создания менеджеров контекста можно создать класс с двумя методами: `__enter__()` и `__exit__()`.
+В Python можно создавать менеджеры контекста, создав класс с двумя методами: `__enter__()` и `__exit__()`.
-Вы также можете использовать их внутри зависимостей **FastAPI** с `yield`, используя операторы
+Их также можно использовать внутри зависимостей **FastAPI** с `yield`, применяя операторы
`with` или `async with` внутри функции зависимости:
-{* ../../docs_src/dependencies/tutorial010.py hl[1:9,13] *}
+{* ../../docs_src/dependencies/tutorial010_py39.py hl[1:9,13] *}
/// tip | Подсказка
-Другой способ создания контекстного менеджера - с помощью:
+Другой способ создания менеджера контекста — с помощью:
* `@contextlib.contextmanager` или
* `@contextlib.asynccontextmanager`
-используйте их для оформления функции с одним `yield`.
+оформив ими функцию с одним `yield`.
-Это то, что **FastAPI** использует внутри себя для зависимостей с `yield`.
+Именно это **FastAPI** использует внутренне для зависимостей с `yield`.
-Но использовать декораторы для зависимостей FastAPI не обязательно (да и не стоит).
+Но использовать эти декораторы для зависимостей FastAPI не обязательно (и не стоит).
FastAPI сделает это за вас на внутреннем уровне.
diff --git a/docs/ru/docs/tutorial/dependencies/global-dependencies.md b/docs/ru/docs/tutorial/dependencies/global-dependencies.md
index 5d2e70f6e..2347c6dd8 100644
--- a/docs/ru/docs/tutorial/dependencies/global-dependencies.md
+++ b/docs/ru/docs/tutorial/dependencies/global-dependencies.md
@@ -1,15 +1,15 @@
-# Глобальные зависимости
+# Глобальные зависимости { #global-dependencies }
Для некоторых типов приложений может потребоваться добавить зависимости ко всему приложению.
-Подобно тому, как вы можете [добавлять зависимости через параметр `dependencies` в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, вы можете добавлять зависимости сразу ко всему `FastAPI` приложению.
+Подобно тому, как вы можете [добавлять `dependencies` (зависимости) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, вы можете добавлять зависимости сразу ко всему `FastAPI` приложению.
В этом случае они будут применяться ко всем *операциям пути* в приложении:
-{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[16] *}
+{* ../../docs_src/dependencies/tutorial012_an_py39.py hl[17] *}
-Все способы [добавления зависимостей в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} по-прежнему применимы, но в данном случае зависимости применяются ко всем *операциям пути* приложения.
+Все способы [добавления `dependencies` (зависимостей) в *декораторах операций пути*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} по-прежнему применимы, но в данном случае зависимости применяются ко всем *операциям пути* приложения.
-## Зависимости для групп *операций пути*
+## Зависимости для групп *операций пути* { #dependencies-for-groups-of-path-operations }
-Позднее, читая о том, как структурировать более крупные [приложения, содержащие много файлов](../../tutorial/bigger-applications.md){.internal-link target=_blank}, вы узнаете, как объявить один параметр dependencies для целой группы *операций пути*.
+Позднее, читая о том, как структурировать более крупные [приложения, содержащие много файлов](../../tutorial/bigger-applications.md){.internal-link target=_blank}, вы узнаете, как объявить один параметр `dependencies` для целой группы *операций пути*.
diff --git a/docs/ru/docs/tutorial/dependencies/index.md b/docs/ru/docs/tutorial/dependencies/index.md
index 28790bd5a..98b0d59c6 100644
--- a/docs/ru/docs/tutorial/dependencies/index.md
+++ b/docs/ru/docs/tutorial/dependencies/index.md
@@ -1,91 +1,97 @@
-# Зависимости
+# Зависимости { #dependencies }
-**FastAPI** имеет очень мощную и интуитивную систему **Dependency Injection**.
+**FastAPI** имеет очень мощную, но интуитивную систему **Инъекция зависимостей**.
-Она проектировалась таким образом, чтобы быть простой в использовании и облегчить любому разработчику интеграцию других компонентов с **FastAPI**.
+Она спроектирована так, чтобы быть очень простой в использовании и облегчать любому разработчику интеграцию других компонентов с **FastAPI**.
-## Что такое "Dependency Injection" (инъекция зависимости)
+## Что такое инъекция зависимостей («Dependency Injection») { #what-is-dependency-injection }
-**"Dependency Injection"** в программировании означает, что у вашего кода (в данном случае, вашей *функции обработки пути*) есть способы объявить вещи, которые запрашиваются для работы и использования: "зависимости".
+В программировании **«Dependency Injection»** означает, что у вашего кода (в данном случае у ваших *функций обработки пути*) есть способ объявить вещи, которые требуются для его работы и использования: «зависимости».
-И потом эта система (в нашем случае **FastAPI**) организует всё, что требуется, чтобы обеспечить ваш код этой зависимостью (сделать "инъекцию" зависимости).
+И затем эта система (в нашем случае **FastAPI**) позаботится о том, чтобы сделать всё необходимое для предоставления вашему коду этих зависимостей (сделать «инъекцию» зависимостей).
Это очень полезно, когда вам нужно:
* Обеспечить общую логику (один и тот же алгоритм снова и снова).
-* Общее соединение с базой данных.
-* Обеспечение безопасности, аутентификации, запроса роли и т.п.
-* И многое другое.
+* Разделять соединения с базой данных.
+* Обеспечить безопасность, аутентификацию, требования к ролям и т. п.
+* И многое другое...
-Всё это минимизирует повторение кода.
+Всё это при минимизации повторения кода.
-## Первые шаги
+## Первые шаги { #first-steps }
-Давайте рассмотрим очень простой пример. Он настолько простой, что на данный момент почти бесполезный.
+Давайте рассмотрим очень простой пример. Он настолько простой, что пока не очень полезен.
-Но таким способом мы можем сфокусироваться на том, как же всё таки работает система **Dependency Injection**.
+Но так мы сможем сосредоточиться на том, как работает система **Dependency Injection**.
-### Создание зависимости или "зависимого"
-Давайте для начала сфокусируемся на зависимостях.
+### Создайте зависимость, или «dependable» (от чего что-то зависит) { #create-a-dependency-or-dependable }
+
+Сначала сосредоточимся на зависимости.
+
+Это просто функция, которая может принимать те же параметры, что и *функция обработки пути*:
-Это просто функция, которая может принимать все те же параметры, что и *функции обработки пути*:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[8:9] *}
-**И всё.**
+И всё.
**2 строки.**
-И теперь она той же формы и структуры, что и все ваши *функции обработки пути*.
+И она имеет ту же форму и структуру, что и все ваши *функции обработки пути*.
-Вы можете думать об *функции обработки пути* как о функции без "декоратора" (без `@app.get("/some-path")`).
+Можно думать о ней как о *функции обработки пути* без «декоратора» (без `@app.get("/some-path")`).
-И она может возвращать всё, что требуется.
+И она может возвращать что угодно.
-В этом случае, эта зависимость ожидает:
+В этом случае эта зависимость ожидает:
-* Необязательный query-параметр `q` с типом `str`
-* Необязательный query-параметр `skip` с типом `int`, и значением по умолчанию `0`
-* Необязательный query-параметр `limit` с типом `int`, и значением по умолчанию `100`
+* Необязательный query-параметр `q` типа `str`.
+* Необязательный query-параметр `skip` типа `int`, по умолчанию `0`.
+* Необязательный query-параметр `limit` типа `int`, по умолчанию `100`.
-И в конце она возвращает `dict`, содержащий эти значения.
+А затем просто возвращает `dict`, содержащий эти значения.
/// info | Информация
-**FastAPI** добавил поддержку для `Annotated` (и начал её рекомендовать) в версии 0.95.0.
+FastAPI добавил поддержку `Annotated` (и начал рекомендовать его использование) в версии 0.95.0.
- Если у вас более старая версия, будут ошибки при попытке использовать `Annotated`.
+Если у вас более старая версия, вы получите ошибки при попытке использовать `Annotated`.
-Убедитесь, что вы [Обновили FastAPI версию](../../deployment/versions.md#fastapi_2){.internal-link target=_blank} до, как минимум 0.95.1, перед тем как использовать `Annotated`.
+Убедитесь, что вы [обновили версию FastAPI](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} как минимум до 0.95.1, прежде чем использовать `Annotated`.
///
-### Import `Depends`
+### Импорт `Depends` { #import-depends }
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
-### Объявите зависимость в "зависимом"
+### Объявите зависимость в «зависимом» { #declare-the-dependency-in-the-dependant }
-Точно так же, как вы использовали `Body`, `Query` и т.д. с вашей *функцией обработки пути* для параметров, используйте `Depends` с новым параметром:
+Точно так же, как вы используете `Body`, `Query` и т. д. с параметрами вашей *функции обработки пути*, используйте `Depends` с новым параметром:
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[13,18] *}
-`Depends` работает немного иначе. Вы передаёте в `Depends` одиночный параметр, который будет похож на функцию.
+Хотя вы используете `Depends` в параметрах вашей функции так же, как `Body`, `Query` и т. д., `Depends` работает немного иначе.
+
+В `Depends` вы передаёте только один параметр.
+
+Этот параметр должен быть чем-то вроде функции.
-Вы **не вызываете его** на месте (не добавляете скобочки в конце: 👎 *your_best_func()*👎), просто передаёте как параметр в `Depends()`.
+Вы **не вызываете её** напрямую (не добавляйте круглые скобки в конце), просто передаёте её как параметр в `Depends()`.
-И потом функция берёт параметры так же, как *функция обработки пути*.
+И эта функция принимает параметры так же, как *функции обработки пути*.
/// tip | Подсказка
-В следующей главе вы увидите, какие другие вещи, помимо функций, можно использовать в качестве зависимостей.
+В следующей главе вы увидите, какие ещё «вещи», помимо функций, можно использовать в качестве зависимостей.
///
-Каждый раз, когда новый запрос приходит, **FastAPI** позаботится о:
+Каждый раз, когда приходит новый запрос, **FastAPI** позаботится о:
-* Вызове вашей зависимости ("зависимого") функции с корректными параметрами.
+* Вызове вашей зависимости («dependable») с корректными параметрами.
* Получении результата из вашей функции.
-* Назначении результата в параметр в вашей *функции обработки пути*.
+* Присваивании этого результата параметру в вашей *функции обработки пути*.
```mermaid
graph TB
@@ -98,121 +104,121 @@ common_parameters --> read_items
common_parameters --> read_users
```
-Таким образом, вы пишете общий код один раз, и **FastAPI** позаботится о его вызове для ваших *операций с путями*.
+Таким образом, вы пишете общий код один раз, а **FastAPI** позаботится о его вызове для ваших *операций пути*.
/// check | Проверка
-Обратите внимание, что вы не создаёте специальный класс и не передаёте его куда-то в **FastAPI** для регистрации, или что-то в этом роде.
+Обратите внимание, что вам не нужно создавать специальный класс и передавать его куда-то в **FastAPI**, чтобы «зарегистрировать» его или что-то подобное.
-Вы просто передаёте это в `Depends`, и **FastAPI** знает, что делать дальше.
+Вы просто передаёте его в `Depends`, и **FastAPI** знает, что делать дальше.
///
-## Объединяем с `Annotated` зависимостями
+## Использование зависимости с `Annotated` в нескольких местах { #share-annotated-dependencies }
-В приведенном выше примере есть небольшое **повторение кода**.
+В приведённых выше примерах есть небольшое **повторение кода**.
-Когда вам нужно использовать `common_parameters()` зависимость, вы должны написать весь параметр с аннотацией типов и `Depends()`:
+Когда вам нужно использовать зависимость `common_parameters()`, вы должны написать весь параметр с аннотацией типа и `Depends()`:
```Python
commons: Annotated[dict, Depends(common_parameters)]
```
-Но потому что мы используем `Annotated`, мы можем хранить `Annotated` значение в переменной и использовать его в нескольких местах:
+Но поскольку мы используем `Annotated`, мы можем сохранить это значение `Annotated` в переменную и использовать его в нескольких местах:
{* ../../docs_src/dependencies/tutorial001_02_an_py310.py hl[12,16,21] *}
/// tip | Подсказка
-Это стандартный синтаксис python и называется "type alias", это не особенность **FastAPI**.
+Это стандартный Python, это называется «type alias», и это не особенность **FastAPI**.
-Но потому что **FastAPI** базируется на стандартах Python, включая `Annotated`, вы можете использовать этот трюк в вашем коде. 😎
+Но поскольку **FastAPI** основан на стандартах Python, включая `Annotated`, вы можете использовать этот трюк в своём коде. 😎
///
-Зависимости продолжат работу как ожидалось, и **лучшая часть** в том, что **информация о типе будет сохранена**. Это означает, что ваш редактор кода будет корректно обрабатывать **автодополнения**, **встроенные ошибки** и так далее. То же самое относится и к инструментам, таким как `mypy`.
+Зависимости продолжат работать как ожидалось, и **лучшая часть** в том, что **информация о типах будет сохранена**, а значит, ваш редактор кода продолжит предоставлять **автозавершение**, **встроенные ошибки** и т.д. То же относится и к другим инструментам, таким как `mypy`.
-Это очень полезно, когда вы интегрируете это в **большую кодовую базу**, используя **одинаковые зависимости** снова и снова во **многих** ***операциях пути***.
+Это особенно полезно, когда вы используете это в **большой кодовой базе**, где вы используете **одни и те же зависимости** снова и снова во **многих *операциях пути***.
-## Использовать `async` или не `async`
+## Использовать `async` или не `async` { #to-async-or-not-to-async }
-Для зависимостей, вызванных **FastAPI** (то же самое, что и ваши *функции обработки пути*), те же правила, что приняты для определения ваших функций.
+Поскольку зависимости также вызываются **FastAPI** (как и ваши *функции обработки пути*), применяются те же правила при определении ваших функций.
Вы можете использовать `async def` или обычное `def`.
-Вы также можете объявить зависимости с `async def` внутри обычной `def` *функции обработки пути*, или `def` зависимости внутри `async def` *функции обработки пути*, и так далее.
+И вы можете объявлять зависимости с `async def` внутри обычных *функций обработки пути* `def`, или зависимости `def` внутри *функций обработки пути* `async def` и т. д.
-Это всё не важно. **FastAPI** знает, что нужно сделать. 😎
+Это не важно. **FastAPI** знает, что делать.
-/// note | Информация
+/// note | Примечание
-Если вам эта тема не знакома, прочтите [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} раздел о `async` и `await` в документации.
+Если вы не уверены, посмотрите раздел [Async: *"In a hurry?"*](../../async.md#in-a-hurry){.internal-link target=_blank} о `async` и `await` в документации.
///
-## Интеграция с OpenAPI
+## Интеграция с OpenAPI { #integrated-with-openapi }
-Все заявления о запросах, валидаторы, требования ваших зависимостей (и подзависимостей) будут интегрированы в соответствующую OpenAPI-схему.
+Все объявления запросов, проверки и требования ваших зависимостей (и подзависимостей) будут интегрированы в ту же схему OpenAPI.
-В интерактивной документации будет вся информация по этим зависимостям тоже:
+Поэтому в интерактивной документации будет вся информация и из этих зависимостей:
-## Простое использование
+## Простое использование { #simple-usage }
-Если вы посмотрите на фото, *функция обработки пути* объявляется каждый раз, когда вычисляется путь, и тогда **FastAPI** позаботится о вызове функции с корректными параметрами, извлекая информацию из запроса.
+Если посмотреть, *функции обработки пути* объявляются для использования всякий раз, когда *путь* и *операция* совпадают, и тогда **FastAPI** заботится о вызове функции с корректными параметрами, извлекая данные из запроса.
-На самом деле, все (или большинство) веб-фреймворков работают по схожему сценарию.
+На самом деле все (или большинство) веб-фреймворков работают таким же образом.
-Вы никогда не вызываете эти функции на месте. Их вызовет ваш фреймворк (в нашем случае, **FastAPI**).
+Вы никогда не вызываете эти функции напрямую. Их вызывает ваш фреймворк (в нашем случае **FastAPI**).
-С системой Dependency Injection, вы можете сообщить **FastAPI**, что ваша *функция обработки пути* "зависит" от чего-то ещё, что должно быть извлечено перед вашей *функцией обработки пути*, и **FastAPI** позаботится об извлечении и инъекции результата.
+С системой **Dependency Injection** вы также можете сообщить **FastAPI**, что ваша *функция обработки пути* «зависит» от чего-то, что должно быть выполнено перед вашей *функцией обработки пути*, и **FastAPI** позаботится о его выполнении и «инъекции» результатов.
-Другие распространённые термины для описания схожей идеи "dependency injection" являются:
+Другие распространённые термины для описания той же идеи «dependency injection»:
-- ресурсность
-- доставка
-- сервисность
-- инъекция
-- компонентность
+* ресурсы
+* провайдеры
+* сервисы
+* внедряемые зависимости
+* компоненты
-## **FastAPI** подключаемые модули
+## Плагины **FastAPI** { #fastapi-plug-ins }
-Инъекции и модули могут быть построены с использованием системы **Dependency Injection**. Но на самом деле, **нет необходимости создавать новые модули**, просто используя зависимости, можно объявить бесконечное количество интеграций и взаимодействий, которые доступны вашей *функции обработки пути*.
+Интеграции и «плагины» могут быть построены с использованием системы **Dependency Injection**. Но на самом деле **нет необходимости создавать «плагины»**, так как, используя зависимости, можно объявить бесконечное количество интеграций и взаимодействий, которые становятся доступными вашим *функциям обработки пути*.
-И зависимости могут быть созданы очень простым и интуитивным способом, что позволяет вам просто импортировать нужные пакеты Python и интегрировать их в API функции за пару строк.
+И зависимости можно создавать очень простым и интуитивным способом, который позволяет просто импортировать нужные пакеты Python и интегрировать их с вашими API-функциями в пару строк кода, *буквально*.
Вы увидите примеры этого в следующих главах о реляционных и NoSQL базах данных, безопасности и т.д.
-## Совместимость с **FastAPI**
+## Совместимость с **FastAPI** { #fastapi-compatibility }
-Простота Dependency Injection делает **FastAPI** совместимым с:
+Простота системы **Dependency Injection** делает **FastAPI** совместимым с:
-- всеми реляционными базами данных
-- NoSQL базами данных
-- внешними пакетами
-- внешними API
-- системами авторизации, аутентификации
-- системами мониторинга использования API
-- системами ввода данных ответов
-- и так далее.
+* всеми реляционными базами данных
+* NoSQL базами данных
+* внешними пакетами
+* внешними API
+* системами аутентификации и авторизации
+* системами мониторинга использования API
+* системами инъекции данных в ответы
+* и т.д.
-## Просто и сильно
+## Просто и мощно { #simple-and-powerful }
-Хотя иерархическая система Dependency Injection очень проста для описания и использования, она по-прежнему очень мощная.
+Хотя иерархическая система dependency injection очень проста для определения и использования, она по-прежнему очень мощная.
-Вы можете описывать зависимости в очередь, и они уже будут вызываться друг за другом.
+Вы можете определять зависимости, которые, в свою очередь, могут иметь собственные зависимости.
-Когда иерархическое дерево построено, система **Dependency Injection** берет на себя решение всех зависимостей для вас (и их подзависимостей) и обеспечивает (инъектирует) результат на каждом шаге.
+В итоге строится иерархическое дерево зависимостей, и система **Dependency Injection** берёт на себя решение всех этих зависимостей (и их подзависимостей) и предоставляет (инъектирует) результаты на каждом шаге.
Например, у вас есть 4 API-эндпоинта (*операции пути*):
-- `/items/public/`
-- `/items/private/`
-- `/users/{user_id}/activate`
-- `/items/pro/`
+* `/items/public/`
+* `/items/private/`
+* `/users/{user_id}/activate`
+* `/items/pro/`
-Тогда вы можете требовать разные права для каждого из них, используя зависимости и подзависимости:
+тогда вы можете добавить разные требования к правам для каждого из них только с помощью зависимостей и подзависимостей:
```mermaid
graph TB
@@ -237,8 +243,8 @@ admin_user --> activate_user
paying_user --> pro_items
```
-## Интегрировано с **OpenAPI**
+## Интегрировано с **OpenAPI** { #integrated-with-openapi_1 }
-Все эти зависимости, объявляя свои требования, также добавляют параметры, проверки и т.д. к вашим операциям *path*.
+Все эти зависимости, объявляя свои требования, также добавляют параметры, проверки и т.д. к вашим *операциям пути*.
-**FastAPI** позаботится о добавлении всего этого в схему открытого API, чтобы это отображалось в системах интерактивной документации.
+**FastAPI** позаботится о добавлении всего этого в схему OpenAPI, чтобы это отображалось в системах интерактивной документации.
diff --git a/docs/ru/docs/tutorial/dependencies/sub-dependencies.md b/docs/ru/docs/tutorial/dependencies/sub-dependencies.md
index 5e8de0c4a..da31a6682 100644
--- a/docs/ru/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/ru/docs/tutorial/dependencies/sub-dependencies.md
@@ -1,4 +1,4 @@
-# Подзависимости
+# Подзависимости { #sub-dependencies }
Вы можете создавать зависимости, которые имеют **подзависимости**.
@@ -6,7 +6,7 @@
**FastAPI** сам займётся их управлением.
-## Провайдер зависимости
+## Первая зависимость { #first-dependency-dependable }
Можно создать первую зависимость следующим образом:
@@ -16,9 +16,9 @@
Это довольно просто (хотя и не очень полезно), но поможет нам сосредоточиться на том, как работают подзависимости.
-## Вторая зависимость
+## Вторая зависимость, «зависимость» и «зависимая» { #second-dependency-dependable-and-dependant }
-Затем можно создать еще одну функцию зависимости, которая в то же время содержит внутри себя первую зависимость (таким образом, она тоже является "зависимой"):
+Затем можно создать еще одну функцию зависимости, которая одновременно объявляет свою собственную зависимость (таким образом, она тоже является «зависимой»):
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[13] *}
@@ -29,7 +29,7 @@
* Она также объявляет необязательный куки-параметр `last_query` в виде строки.
* Если пользователь не указал параметр `q` в запросе, то мы используем последний использованный запрос, который мы ранее сохранили в куки-параметре `last_query`.
-## Использование зависимости
+## Использование зависимости { #use-the-dependency }
Затем мы можем использовать зависимость вместе с:
@@ -54,7 +54,7 @@ read_query["/items/"]
query_extractor --> query_or_cookie_extractor --> read_query
```
-## Использование одной и той же зависимости несколько раз
+## Использование одной и той же зависимости несколько раз { #using-the-same-dependency-multiple-times }
Если одна из ваших зависимостей объявлена несколько раз для одной и той же *функции операции пути*, например, несколько зависимостей имеют общую подзависимость, **FastAPI** будет знать, что вызывать эту подзависимость нужно только один раз за запрос.
@@ -62,7 +62,7 @@ query_extractor --> query_or_cookie_extractor --> read_query
В расширенном сценарии, когда вы знаете, что вам нужно, чтобы зависимость вызывалась на каждом шаге (возможно, несколько раз) в одном и том же запросе, вместо использования "кэшированного" значения, вы можете установить параметр `use_cache=False` при использовании `Depends`:
-//// tab | Python 3.6+
+//// tab | Python 3.9+
```Python hl_lines="1"
async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_cache=False)]):
@@ -71,7 +71,7 @@ async def needy_dependency(fresh_value: Annotated[str, Depends(get_value, use_ca
////
-//// tab | Python 3.6+ без Annotated
+//// tab | Python 3.9+ без Annotated
/// tip | Подсказка
@@ -86,7 +86,7 @@ async def needy_dependency(fresh_value: str = Depends(get_value, use_cache=False
////
-## Резюме
+## Резюме { #recap }
Помимо всех этих умных слов, используемых здесь, система внедрения зависимостей довольно проста.
diff --git a/docs/ru/docs/tutorial/encoder.md b/docs/ru/docs/tutorial/encoder.md
index 4ed5039b3..16981f79d 100644
--- a/docs/ru/docs/tutorial/encoder.md
+++ b/docs/ru/docs/tutorial/encoder.md
@@ -1,4 +1,4 @@
-# JSON кодировщик
+# JSON-совместимый кодировщик { #json-compatible-encoder }
В некоторых случаях может потребоваться преобразование типа данных (например, Pydantic-модели) в тип, совместимый с JSON (например, `dict`, `list` и т.д.).
@@ -6,7 +6,7 @@
Для этого **FastAPI** предоставляет функцию `jsonable_encoder()`.
-## Использование `jsonable_encoder`
+## Использование `jsonable_encoder` { #using-the-jsonable-encoder }
Представим, что у вас есть база данных `fake_db`, которая принимает только JSON-совместимые данные.
@@ -14,21 +14,21 @@
В таком случае объект `datetime` следует преобразовать в строку соответствующую формату ISO.
-Точно так же эта база данных не может принять Pydantic модель (объект с атрибутами), а только `dict`.
+Точно так же эта база данных не может принять Pydantic-модель (объект с атрибутами), а только `dict`.
Для этого можно использовать функцию `jsonable_encoder`.
-Она принимает объект, например, модель Pydantic, и возвращает его версию, совместимую с JSON:
+Она принимает объект, например, Pydantic-модель, и возвращает его версию, совместимую с JSON:
{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
-В данном примере она преобразует Pydantic модель в `dict`, а `datetime` - в `str`.
+В данном примере она преобразует Pydantic-модель в `dict`, а `datetime` - в `str`.
Результатом её вызова является объект, который может быть закодирован с помощью функции из стандартной библиотеки Python – `json.dumps()`.
Функция не возвращает большой `str`, содержащий данные в формате JSON (в виде строки). Она возвращает стандартную структуру данных Python (например, `dict`) со значениями и подзначениями, которые совместимы с JSON.
-/// note | Технические детали
+/// note | Примечание
`jsonable_encoder` фактически используется **FastAPI** внутри системы для преобразования данных. Однако он полезен и во многих других сценариях.
diff --git a/docs/ru/docs/tutorial/extra-data-types.md b/docs/ru/docs/tutorial/extra-data-types.md
index 6d6d4aa9f..3b52b5d74 100644
--- a/docs/ru/docs/tutorial/extra-data-types.md
+++ b/docs/ru/docs/tutorial/extra-data-types.md
@@ -1,4 +1,4 @@
-# Дополнительные типы данных
+# Дополнительные типы данных { #extra-data-types }
До сих пор вы использовали простые типы данных, такие как:
@@ -9,15 +9,15 @@
Но вы также можете использовать и более сложные типы.
-При этом у вас останутся те же возможности , что и до сих пор:
+При этом у вас останутся те же возможности, что и до сих пор:
-* Отличная поддержка редактора.
+* Отличная поддержка редактора кода.
* Преобразование данных из входящих запросов.
* Преобразование данных для ответа.
* Валидация данных.
* Автоматическая аннотация и документация.
-## Другие типы данных
+## Другие типы данных { #other-data-types }
Ниже перечислены некоторые из дополнительных типов данных, которые вы можете использовать:
@@ -36,7 +36,7 @@
* `datetime.timedelta`:
* Встроенный в Python `datetime.timedelta`.
* В запросах и ответах будет представлен в виде общего количества секунд типа `float`.
- * Pydantic также позволяет представить его как "Кодировку разницы во времени ISO 8601", см. документацию для получения дополнительной информации.
+ * Pydantic также позволяет представить его как "Кодировку разницы во времени ISO 8601", см. документацию для получения дополнительной информации.
* `frozenset`:
* В запросах и ответах обрабатывается так же, как и `set`:
* В запросах будет прочитан список, исключены дубликаты и преобразован в `set`.
@@ -49,14 +49,14 @@
* `Decimal`:
* Встроенный в Python `Decimal`.
* В запросах и ответах обрабатывается так же, как и `float`.
-* Вы можете проверить все допустимые типы данных pydantic здесь: Типы данных Pydantic.
+* Вы можете проверить все допустимые типы данных Pydantic здесь: Типы данных Pydantic.
-## Пример
+## Пример { #example }
Вот пример *операции пути* с параметрами, который демонстрирует некоторые из вышеперечисленных типов.
-{* ../../docs_src/extra_data_types/tutorial001.py hl[1,3,12:16] *}
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
Обратите внимание, что параметры внутри функции имеют свой естественный тип данных, и вы, например, можете выполнять обычные манипуляции с датами, такие как:
-{* ../../docs_src/extra_data_types/tutorial001.py hl[18:19] *}
+{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[18:19] *}
diff --git a/docs/ru/docs/tutorial/extra-models.md b/docs/ru/docs/tutorial/extra-models.md
index 5b51aa402..03156f2b4 100644
--- a/docs/ru/docs/tutorial/extra-models.md
+++ b/docs/ru/docs/tutorial/extra-models.md
@@ -1,4 +1,4 @@
-# Дополнительные модели
+# Дополнительные модели { #extra-models }
В продолжение прошлого примера будет уже обычным делом иметь несколько связанных между собой моделей.
@@ -16,19 +16,19 @@
///
-## Множественные модели
+## Множественные модели { #multiple-models }
Ниже изложена основная идея того, как могут выглядеть эти модели с полями для паролей, а также описаны места, где они используются:
{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *}
-### Про `**user_in.dict()`
+### Про `**user_in.model_dump()` { #about-user-in-model-dump }
-#### `.dict()` из Pydantic
+#### `.model_dump()` из Pydantic { #pydantics-model-dump }
-`user_in` - это Pydantic-модель класса `UserIn`.
+`user_in` — это Pydantic-модель класса `UserIn`.
-У Pydantic-моделей есть метод `.dict()`, который возвращает `dict` с данными модели.
+У Pydantic-моделей есть метод `.model_dump()`, который возвращает `dict` с данными модели.
Поэтому, если мы создадим Pydantic-объект `user_in` таким способом:
@@ -39,10 +39,10 @@ user_in = UserIn(username="john", password="secret", email="john.doe@example.com
и затем вызовем:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
```
-то теперь у нас есть `dict` с данными модели в переменной `user_dict` (это `dict` вместо объекта Pydantic-модели).
+то теперь у нас есть `dict` с данными в переменной `user_dict` (это `dict` вместо объекта Pydantic-модели).
И если мы вызовем:
@@ -50,7 +50,7 @@ user_dict = user_in.dict()
print(user_dict)
```
-мы можем получить `dict` с такими данными:
+мы получим Python `dict` с:
```Python
{
@@ -61,9 +61,9 @@ print(user_dict)
}
```
-#### Распаковка `dict`
+#### Распаковка `dict` { #unpacking-a-dict }
-Если мы возьмём `dict` наподобие `user_dict` и передадим его в функцию (или класс), используя `**user_dict`, Python распакует его. Он передаст ключи и значения `user_dict` напрямую как аргументы типа ключ-значение.
+Если мы возьмём `dict` наподобие `user_dict` и передадим его в функцию (или класс), используя `**user_dict`, Python его "распакует". Он передаст ключи и значения `user_dict` напрямую как аргументы типа ключ-значение.
Поэтому, продолжая описанный выше пример с `user_dict`, написание такого кода:
@@ -71,7 +71,7 @@ print(user_dict)
UserInDB(**user_dict)
```
-Будет работать так же, как примерно такой код:
+будет эквивалентно:
```Python
UserInDB(
@@ -82,7 +82,7 @@ UserInDB(
)
```
-Или, если для большей точности мы напрямую используем `user_dict` с любым потенциальным содержимым, то этот пример будет выглядеть так:
+Или, более точно, если использовать `user_dict` напрямую, с любым содержимым, которое он может иметь в будущем:
```Python
UserInDB(
@@ -93,34 +93,34 @@ UserInDB(
)
```
-#### Pydantic-модель из содержимого другой модели
+#### Pydantic-модель из содержимого другой { #a-pydantic-model-from-the-contents-of-another }
-Как в примере выше мы получили `user_dict` из `user_in.dict()`, этот код:
+Как в примере выше мы получили `user_dict` из `user_in.model_dump()`, этот код:
```Python
-user_dict = user_in.dict()
+user_dict = user_in.model_dump()
UserInDB(**user_dict)
```
будет равнозначен такому:
```Python
-UserInDB(**user_in.dict())
+UserInDB(**user_in.model_dump())
```
-...потому что `user_in.dict()` - это `dict`, и затем мы указываем, чтобы Python его "распаковал", когда передаём его в `UserInDB` и ставим перед ним `**`.
+...потому что `user_in.model_dump()` — это `dict`, и затем мы указываем, чтобы Python его "распаковал", когда передаём его в `UserInDB` с префиксом `**`.
Таким образом мы получаем Pydantic-модель на основе данных из другой Pydantic-модели.
-#### Распаковка `dict` и дополнительные именованные аргументы
+#### Распаковка `dict` и дополнительные именованные аргументы { #unpacking-a-dict-and-extra-keywords }
И затем, если мы добавим дополнительный именованный аргумент `hashed_password=hashed_password` как здесь:
```Python
-UserInDB(**user_in.dict(), hashed_password=hashed_password)
+UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
```
-... то мы получим что-то подобное:
+...то в итоге получится что-то подобное:
```Python
UserInDB(
@@ -134,13 +134,13 @@ UserInDB(
/// warning | Предупреждение
-Цель использованных в примере вспомогательных функций - не более чем демонстрация возможных операций с данными, но, конечно, они не обеспечивают настоящую безопасность.
+Вспомогательные дополнительные функции `fake_password_hasher` и `fake_save_user` используются только для демонстрации возможного потока данных и, конечно, не обеспечивают настоящую безопасность.
///
-## Сократите дублирование
+## Сократите дублирование { #reduce-duplication }
-Сокращение дублирования кода - это одна из главных идей **FastAPI**.
+Сокращение дублирования кода — это одна из главных идей **FastAPI**.
Поскольку дублирование кода повышает риск появления багов, проблем с безопасностью, проблем десинхронизации кода (когда вы обновляете код в одном месте, но не обновляете в другом), и т.д.
@@ -156,23 +156,23 @@ UserInDB(
{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
-## `Union` или `anyOf`
+## `Union` или `anyOf` { #union-or-anyof }
-Вы можете определить ответ как `Union` из двух типов. Это означает, что ответ должен соответствовать одному из них.
+Вы можете объявить HTTP-ответ как `Union` из двух или более типов. Это означает, что HTTP-ответ может быть любым из них.
Он будет определён в OpenAPI как `anyOf`.
-Для этого используйте стандартные аннотации типов в Python `typing.Union`:
+Для этого используйте стандартную аннотацию типов в Python `typing.Union`:
/// note | Примечание
-При объявлении `Union`, сначала указывайте наиболее детальные типы, затем менее детальные. В примере ниже более детальный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`.
+При объявлении `Union` сначала указывайте наиболее специфичный тип, затем менее специфичный. В примере ниже более специфичный `PlaneItem` стоит перед `CarItem` в `Union[PlaneItem, CarItem]`.
///
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
-### `Union` в Python 3.10
+### `Union` в Python 3.10 { #union-in-python-3-10 }
В этом примере мы передаём `Union[PlaneItem, CarItem]` в качестве значения аргумента `response_model`.
@@ -184,19 +184,19 @@ UserInDB(
some_variable: PlaneItem | CarItem
```
-Но если мы помещаем его в `response_model=PlaneItem | CarItem` мы получим ошибку, потому что Python попытается произвести **некорректную операцию** между `PlaneItem` и `CarItem` вместо того, чтобы интерпретировать это как аннотацию типа.
+Но если мы поместим это в присваивание `response_model=PlaneItem | CarItem`, мы получим ошибку, потому что Python попытается произвести **некорректную операцию** между `PlaneItem` и `CarItem` вместо того, чтобы интерпретировать это как аннотацию типа.
-## Список моделей
+## Список моделей { #list-of-models }
-Таким же образом вы можете определять ответы как списки объектов.
+Таким же образом вы можете объявлять HTTP-ответы, возвращающие списки объектов.
-Для этого используйте `typing.List` из стандартной библиотеки Python (или просто `list` в Python 3.9 и выше):
+Для этого используйте стандартный `typing.List` в Python (или просто `list` в Python 3.9 и выше):
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
-## Ответ с произвольным `dict`
+## Ответ с произвольным `dict` { #response-with-arbitrary-dict }
-Вы также можете определить ответ, используя произвольный одноуровневый `dict` и определяя только типы ключей и значений без использования Pydantic-моделей.
+Вы также можете объявить HTTP-ответ, используя обычный произвольный `dict`, объявив только тип ключей и значений, без использования Pydantic-модели.
Это полезно, если вы заранее не знаете корректных названий полей/атрибутов (которые будут нужны при использовании Pydantic-модели).
@@ -204,8 +204,8 @@ some_variable: PlaneItem | CarItem
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
-## Резюме
+## Резюме { #recap }
-Используйте несколько Pydantic-моделей и свободно применяйте наследование для каждой из них.
+Используйте несколько Pydantic-моделей и свободно применяйте наследование для каждого случая.
-Вам не обязательно иметь единственную модель данных для каждой сущности, если эта сущность должна иметь возможность быть в разных "состояниях". Как в случае с "сущностью" пользователя, у которого есть состояния с полями `password`, `password_hash` и без пароля.
+Вам не обязательно иметь единственную модель данных для каждой сущности, если эта сущность должна иметь возможность быть в разных "состояниях". Как в случае с "сущностью" пользователя, у которого есть состояние, включающее `password`, `password_hash` и отсутствие пароля.
diff --git a/docs/ru/docs/tutorial/first-steps.md b/docs/ru/docs/tutorial/first-steps.md
index cb3d19a71..798c03d51 100644
--- a/docs/ru/docs/tutorial/first-steps.md
+++ b/docs/ru/docs/tutorial/first-steps.md
@@ -1,106 +1,122 @@
-# Первые шаги
+# Первые шаги { #first-steps }
-Самый простой FastAPI файл может выглядеть так:
+Самый простой файл FastAPI может выглядеть так:
-{* ../../docs_src/first_steps/tutorial001.py *}
+{* ../../docs_src/first_steps/tutorial001_py39.py *}
-Скопируйте в файл `main.py`.
+Скопируйте это в файл `main.py`.
Запустите сервер в режиме реального времени:
get операцию
+* по пути `/`
+* с использованием get операции
-/// info | `@decorator` Дополнительная информация
+/// info | Информация о `@decorator`
-Синтаксис `@something` в Python называется "декоратор".
+Синтаксис `@something` в Python называется «декоратор».
-Вы помещаете его над функцией. Как красивую декоративную шляпу (думаю, что оттуда и происходит этот термин).
+Его размещают над функцией. Как красивая декоративная шляпа (кажется, отсюда и пошёл термин).
-"Декоратор" принимает функцию ниже и выполняет с ней какое-то действие.
+«Декоратор» берёт функцию ниже и делает с ней что-то.
-В нашем случае, этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` и **операции** `get`.
+В нашем случае этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` с **операцией** `get`.
-Это и есть "**декоратор операции пути**".
+Это и есть «декоратор операции пути».
///
-Можно также использовать операции:
+Можно также использовать другие операции:
* `@app.post()`
* `@app.put()`
@@ -278,58 +302,79 @@ https://example.com/items/foo
/// tip | Подсказка
-Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
+Вы можете использовать каждый метод (HTTP-операцию) так, как считаете нужным.
-**FastAPI** не навязывает определенного значения для каждого метода.
+**FastAPI** не навязывает какого-либо конкретного смысла.
-Информация здесь представлена как рекомендация, а не требование.
+Эта информация дана как рекомендация, а не требование.
-Например, при использовании GraphQL обычно все действия выполняются только с помощью POST операций.
+Например, при использовании GraphQL обычно все действия выполняются только с помощью POST-операций.
///
-### Шаг 4: определите **функцию операции пути**
+### Шаг 4: определите **функцию операции пути** { #step-4-define-the-path-operation-function }
-Вот "**функция операции пути**":
+Вот наша «функция операции пути»:
* **путь**: `/`.
* **операция**: `get`.
-* **функция**: функция ниже "декоратора" (ниже `@app.get("/")`).
+* **функция**: функция ниже «декоратора» (ниже `@app.get("/")`).
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *}
-Это обычная Python функция.
+Это функция на Python.
-**FastAPI** будет вызывать её каждый раз при получении `GET` запроса к URL "`/`".
+**FastAPI** будет вызывать её каждый раз, когда получает запрос к URL «`/`» с операцией `GET`.
-В данном случае это асинхронная функция.
+В данном случае это асинхронная (`async`) функция.
---
-Вы также можете определить ее как обычную функцию вместо `async def`:
+Вы также можете определить её как обычную функцию вместо `async def`:
-{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *}
-/// note | Технические детали
+/// note | Примечание
-Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#_1){.internal-link target=_blank}.
+Если вы не знаете, в чём разница, посмотрите [Асинхронность: *"Нет времени?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
///
-### Шаг 5: верните результат
+### Шаг 5: верните содержимое { #step-5-return-the-content }
-{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *}
Вы можете вернуть `dict`, `list`, отдельные значения `str`, `int` и т.д.
-Также можно вернуть модели Pydantic (рассмотрим это позже).
+Также можно вернуть модели Pydantic (подробнее об этом позже).
+
+Многие другие объекты и модели будут автоматически преобразованы в JSON (включая ORM и т. п.). Попробуйте использовать те, что вам привычнее, с высокой вероятностью они уже поддерживаются.
+
+### Шаг 6: разверните приложение { #step-6-deploy-it }
+
+Разверните приложение в **FastAPI Cloud** одной командой: `fastapi deploy`. 🎉
+
+#### О FastAPI Cloud { #about-fastapi-cloud }
+
+**FastAPI Cloud** создан тем же автором и командой, что и **FastAPI**.
+
+Он упрощает процесс **создания образа**, **развертывания** и **доступа** к API с минимальными усилиями.
+
+Он переносит тот же **опыт разработчика** при создании приложений с FastAPI на их **развертывание** в облаке. 🎉
+
+FastAPI Cloud — основной спонсор и источник финансирования для open-source проектов «FastAPI и друзья». ✨
+
+#### Развертывание у других облачных провайдеров { #deploy-to-other-cloud-providers }
+
+FastAPI — open-source и основан на стандартах. Вы можете развернуть приложения FastAPI у любого облачного провайдера по вашему выбору.
-Многие объекты и модели будут автоматически преобразованы в JSON (включая ORM). Пробуйте использовать другие объекты, которые предпочтительней для Вас, вероятно, они уже поддерживаются.
+Следуйте руководствам вашего облачного провайдера, чтобы развернуть приложения FastAPI у них. 🤓
-## Резюме
+## Резюме { #recap }
-* Импортируем `FastAPI`.
-* Создаём экземпляр `app`.
-* Пишем **декоратор операции пути** (такой как `@app.get("/")`).
-* Пишем **функцию операции пути** (`def root(): ...`).
-* Запускаем сервер в режиме разработки (`uvicorn main:app --reload`).
+* Импортируйте `FastAPI`.
+* Создайте экземпляр `app`.
+* Напишите **декоратор операции пути**, например `@app.get("/")`.
+* Определите **функцию операции пути**; например, `def root(): ...`.
+* Запустите сервер разработки командой `fastapi dev`.
+* При желании разверните приложение командой `fastapi deploy`.
diff --git a/docs/ru/docs/tutorial/handling-errors.md b/docs/ru/docs/tutorial/handling-errors.md
index c596abe1f..2e00d7075 100644
--- a/docs/ru/docs/tutorial/handling-errors.md
+++ b/docs/ru/docs/tutorial/handling-errors.md
@@ -1,4 +1,4 @@
-# Обработка ошибок
+# Обработка ошибок { #handling-errors }
Существует множество ситуаций, когда необходимо сообщить об ошибке клиенту, использующему ваш API.
@@ -19,15 +19,15 @@
Помните ли ошибки **"404 Not Found "** (и шутки) ?
-## Использование `HTTPException`
+## Использование `HTTPException` { #use-httpexception }
Для возврата клиенту HTTP-ответов с ошибками используется `HTTPException`.
-### Импортируйте `HTTPException`
+### Импортируйте `HTTPException` { #import-httpexception }
-{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *}
-### Вызовите `HTTPException` в своем коде
+### Вызовите `HTTPException` в своем коде { #raise-an-httpexception-in-your-code }
`HTTPException` - это обычное исключение Python с дополнительными данными, актуальными для API.
@@ -39,9 +39,9 @@
В данном примере, когда клиент запрашивает элемент по несуществующему ID, возникает исключение со статус-кодом `404`:
-{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *}
-### Возвращаемый ответ
+### Возвращаемый ответ { #the-resulting-response }
Если клиент запросит `http://example.com/items/foo` (`item_id` `"foo"`), то он получит статус-код 200 и ответ в формате JSON:
@@ -69,7 +69,7 @@
///
-## Добавление пользовательских заголовков
+## Добавление пользовательских заголовков { #add-custom-headers }
В некоторых ситуациях полезно иметь возможность добавлять пользовательские заголовки к ошибке HTTP. Например, для некоторых типов безопасности.
@@ -77,11 +77,11 @@
Но в случае, если это необходимо для продвинутого сценария, можно добавить пользовательские заголовки:
-{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
+{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *}
-## Установка пользовательских обработчиков исключений
+## Установка пользовательских обработчиков исключений { #install-custom-exception-handlers }
-Вы можете добавить пользовательские обработчики исключений с помощью то же самое исключение - утилиты от Starlette.
+Вы можете добавить пользовательские обработчики исключений с помощью тех же утилит обработки исключений из Starlette.
Допустим, у вас есть пользовательское исключение `UnicornException`, которое вы (или используемая вами библиотека) можете `вызвать`.
@@ -89,7 +89,7 @@
Можно добавить собственный обработчик исключений с помощью `@app.exception_handler()`:
-{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *}
Здесь, если запросить `/unicorns/yolo`, то *операция пути* вызовет `UnicornException`.
@@ -109,7 +109,7 @@
///
-## Переопределение стандартных обработчиков исключений
+## Переопределение стандартных обработчиков исключений { #override-the-default-exception-handlers }
**FastAPI** имеет некоторые обработчики исключений по умолчанию.
@@ -117,7 +117,7 @@
Вы можете переопределить эти обработчики исключений на свои собственные.
-### Переопределение исключений проверки запроса
+### Переопределение обработчика исключений проверки запроса { #override-request-validation-exceptions }
Когда запрос содержит недопустимые данные, **FastAPI** внутренне вызывает ошибку `RequestValidationError`.
@@ -127,7 +127,7 @@
Обработчик исключения получит объект `Request` и исключение.
-{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *}
Теперь, если перейти к `/items/foo`, то вместо стандартной JSON-ошибки с:
@@ -149,36 +149,17 @@
вы получите текстовую версию:
```
-1 validation error
-path -> item_id
- value is not a valid integer (type=type_error.integer)
+Validation errors:
+Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer
```
-#### `RequestValidationError` или `ValidationError`
-
-/// warning | Внимание
-
-Это технические детали, которые можно пропустить, если они не важны для вас сейчас.
-
-///
-
-`RequestValidationError` является подклассом Pydantic `ValidationError`.
-
-**FastAPI** использует его для того, чтобы, если вы используете Pydantic-модель в `response_model`, и ваши данные содержат ошибку, вы увидели ошибку в журнале.
-
-Но клиент/пользователь этого не увидит. Вместо этого клиент получит сообщение "Internal Server Error" с кодом состояния HTTP `500`.
-
-Так и должно быть, потому что если в вашем *ответе* или где-либо в вашем коде (не в *запросе* клиента) возникает Pydantic `ValidationError`, то это действительно ошибка в вашем коде.
-
-И пока вы не устраните ошибку, ваши клиенты/пользователи не должны иметь доступа к внутренней информации о ней, так как это может привести к уязвимости в системе безопасности.
-
-### Переопределите обработчик ошибок `HTTPException`
+### Переопределите обработчик ошибок `HTTPException` { #override-the-httpexception-error-handler }
Аналогичным образом можно переопределить обработчик `HTTPException`.
Например, для этих ошибок можно вернуть обычный текстовый ответ вместо JSON:
-{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *}
/// note | Технические детали
@@ -188,13 +169,21 @@ path -> item_id
///
-### Используйте тело `RequestValidationError`
+/// warning | Внимание
+
+Имейте в виду, что `RequestValidationError` содержит информацию об имени файла и строке, где произошла ошибка валидации, чтобы вы могли при желании отобразить её в логах с релевантными данными.
+
+Но это означает, что если вы просто преобразуете её в строку и вернёте эту информацию напрямую, вы можете допустить небольшую утечку информации о своей системе, поэтому здесь код извлекает и показывает каждую ошибку отдельно.
+
+///
+
+### Используйте тело `RequestValidationError` { #use-the-requestvalidationerror-body }
Ошибка `RequestValidationError` содержит полученное `тело` с недопустимыми данными.
Вы можете использовать его при разработке приложения для регистрации тела и его отладки, возврата пользователю и т.д.
-{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
+{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *}
Теперь попробуйте отправить недействительный элемент, например:
@@ -226,21 +215,19 @@ path -> item_id
}
```
-#### `HTTPException` в FastAPI или в Starlette
+#### `HTTPException` в FastAPI или в Starlette { #fastapis-httpexception-vs-starlettes-httpexception }
**FastAPI** имеет собственный `HTTPException`.
Класс ошибок **FastAPI** `HTTPException` наследует от класса ошибок Starlette `HTTPException`.
-Единственное отличие заключается в том, что `HTTPException` от **FastAPI** позволяет добавлять заголовки, которые будут включены в ответ.
-
-Он необходим/используется внутри системы для OAuth 2.0 и некоторых утилит безопасности.
+Единственное отличие состоит в том, что `HTTPException` в **FastAPI** принимает любые данные, пригодные для преобразования в JSON, в поле `detail`, тогда как `HTTPException` в Starlette принимает для него только строки.
Таким образом, вы можете продолжать вызывать `HTTPException` от **FastAPI** как обычно в своем коде.
Но когда вы регистрируете обработчик исключений, вы должны зарегистрировать его для `HTTPException` от Starlette.
-Таким образом, если какая-либо часть внутреннего кода Starlette, расширение или плагин Starlette вызовет исключение Starlette `HTTPException`, ваш обработчик сможет перехватить и обработать его.
+Таким образом, если какая-либо часть внутреннего кодa Starlette, расширение или плагин Starlette вызовет исключение Starlette `HTTPException`, ваш обработчик сможет перехватить и обработать его.
В данном примере, чтобы иметь возможность использовать оба `HTTPException` в одном коде, исключения Starlette переименованы в `StarletteHTTPException`:
@@ -248,10 +235,10 @@ path -> item_id
from starlette.exceptions import HTTPException as StarletteHTTPException
```
-### Переиспользование обработчиков исключений **FastAPI**
+### Переиспользование обработчиков исключений **FastAPI** { #reuse-fastapis-exception-handlers }
Если вы хотите использовать исключение вместе с теми же обработчиками исключений по умолчанию из **FastAPI**, вы можете импортировать и повторно использовать обработчики исключений по умолчанию из `fastapi.exception_handlers`:
-{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+{* ../../docs_src/handling_errors/tutorial006_py39.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
index 4f54e3e15..fc1fb06d6 100644
--- a/docs/ru/docs/tutorial/header-param-models.md
+++ b/docs/ru/docs/tutorial/header-param-models.md
@@ -1,4 +1,4 @@
-# Модели Header-параметров
+# Модели Header-параметров { #header-parameter-models }
Если у вас есть группа связанных **header-параметров**, то вы можете объединить их в одну **Pydantic-модель**.
@@ -10,7 +10,7 @@
///
-## Header-параметры в виде Pydantic-модели
+## Header-параметры в виде Pydantic-модели { #header-parameters-with-a-pydantic-model }
Объявите нужные **header-параметры** в **Pydantic-модели** и затем аннотируйте параметр как `Header`:
@@ -18,7 +18,7 @@
**FastAPI** **извлечёт** данные для **каждого поля** из **заголовков** запроса и выдаст заданную вами Pydantic-модель.
-## Проверьте документацию
+## Проверьте документацию { #check-the-docs }
Вы можете посмотреть нужные header-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`:
@@ -26,7 +26,7 @@
-## Как запретить дополнительные заголовки
+## Как запретить дополнительные заголовки { #forbid-extra-headers }
В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** заголовки, которые вы хотите получать.
@@ -51,7 +51,7 @@
}
```
-## Как отключить автоматическое преобразование подчеркиваний
+## Как отключить автоматическое преобразование подчеркиваний { #disable-convert-underscores }
Как и в случае с обычными заголовками, если у вас в именах параметров имеются символы подчеркивания, они **автоматически преобразовываются в дефис**.
@@ -67,6 +67,6 @@
///
-## Резюме
+## Резюме { #summary }
Вы можете использовать **Pydantic-модели** для объявления **header-параметров** в **FastAPI**. 😎
diff --git a/docs/ru/docs/tutorial/header-params.md b/docs/ru/docs/tutorial/header-params.md
index e892cfc07..5ce5cb129 100644
--- a/docs/ru/docs/tutorial/header-params.md
+++ b/docs/ru/docs/tutorial/header-params.md
@@ -1,14 +1,14 @@
-# Header-параметры
+# Header-параметры { #header-parameters }
Вы можете определить параметры заголовка таким же образом, как вы определяете параметры `Query`, `Path` и `Cookie`.
-## Импорт `Header`
+## Импорт `Header` { #import-header }
Сперва импортируйте `Header`:
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *}
-## Объявление параметров `Header`
+## Объявление параметров `Header` { #declare-header-parameters }
Затем объявите параметры заголовка, используя ту же структуру, что и с `Path`, `Query` и `Cookie`.
@@ -24,13 +24,13 @@
///
-/// info | Дополнительная информация
+/// info | Информация
Чтобы объявить заголовки, важно использовать `Header`, иначе параметры интерпретируются как query-параметры.
///
-## Автоматическое преобразование
+## Автоматическое преобразование { #automatic-conversion }
`Header` обладает небольшой дополнительной функциональностью в дополнение к тому, что предоставляют `Path`, `Query` и `Cookie`.
@@ -54,7 +54,7 @@
///
-## Повторяющиеся заголовки
+## Повторяющиеся заголовки { #duplicate-headers }
Есть возможность получать несколько заголовков с одним и тем же именем, но разными значениями.
@@ -84,7 +84,7 @@ X-Token: bar
}
```
-## Резюме
+## Резюме { #recap }
Объявляйте заголовки с помощью `Header`, используя тот же общий шаблон, как при `Query`, `Path` и `Cookie`.
diff --git a/docs/ru/docs/tutorial/index.md b/docs/ru/docs/tutorial/index.md
index ddca2fbb1..6674c6720 100644
--- a/docs/ru/docs/tutorial/index.md
+++ b/docs/ru/docs/tutorial/index.md
@@ -1,83 +1,95 @@
-# Учебник - Руководство пользователя
+# Учебник - Руководство пользователя { #tutorial-user-guide }
-В этом руководстве шаг за шагом показано, как использовать **FastApi** с большинством его функций.
+В этом руководстве шаг за шагом показано, как использовать **FastAPI** с большинством его функций.
-Каждый раздел постепенно основывается на предыдущих, но он структурирован по отдельным темам, так что вы можете перейти непосредственно к конкретной теме для решения ваших конкретных потребностей в API.
+Каждый раздел постепенно основывается на предыдущих, но структура разделяет темы, так что вы можете сразу перейти к нужной теме для решения ваших конкретных задач по API.
-Он также создан для использования в качестве будущего справочника.
+Он также создан как справочник на будущее, чтобы вы могли вернуться и посмотреть именно то, что вам нужно.
-Так что вы можете вернуться и посмотреть именно то, что вам нужно.
+## Запустите код { #run-the-code }
-## Запустите код
+Все блоки кода можно копировать и использовать напрямую (это действительно протестированные файлы Python).
-Все блоки кода можно копировать и использовать напрямую (на самом деле это проверенные файлы Python).
-
-Чтобы запустить любой из примеров, скопируйте код в файл `main.py` и запустите `uvicorn` с параметрами:
+Чтобы запустить любой из примеров, скопируйте код в файл `main.py` и запустите `fastapi dev` с:
contact| Параметр | Тип | Описание |
|---|---|---|
name | str | Идентификационное имя контактного лица/организации. |
url | str | URL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL. |
email | str | Email адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса. |
license_info| Параметр | Тип | Описание |
|---|---|---|
name | str | ОБЯЗАТЕЛЬНО (если установлен параметр license_info). Название лицензии, используемой для API |
url | str | URL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL. |
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. |
-## Метаданные для тегов
+## Идентификатор лицензии { #license-identifier }
+
+Начиная с OpenAPI 3.1.0 и FastAPI 0.99.0, вы также можете задать `license_info` с помощью `identifier` вместо `url`.
+
+К примеру:
+
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
+
+## Метаданные для тегов { #metadata-for-tags }
Вы также можете добавить дополнительные метаданные для различных тегов, используемых для группировки ваших операций пути с помощью параметра `openapi_tags`.
@@ -43,13 +52,13 @@
* `description`: `str`-значение с кратким описанием для внешней документации.
* `url` (**обязательно**): `str`-значение с URL-адресом для внешней документации.
-### Создание метаданных для тегов
+### Создание метаданных для тегов { #create-metadata-for-tags }
Давайте попробуем сделать это на примере с тегами для `users` и `items`.
Создайте метаданные для ваших тегов и передайте их в параметре `openapi_tags`:
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}
Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_).
@@ -59,30 +68,31 @@
///
-### Используйте собственные теги
+### Используйте собственные теги { #use-your-tags }
+
Используйте параметр `tags` с вашими *операциями пути* (и `APIRouter`ами), чтобы присвоить им различные теги:
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
/// info | Дополнительная информация
-Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#_3){.internal-link target=_blank}.
+Узнайте больше о тегах в [Конфигурации операции пути](path-operation-configuration.md#tags){.internal-link target=_blank}.
///
-### Проверьте документацию
+### Проверьте документацию { #check-the-docs }
Теперь, если вы проверите документацию, вы увидите всю дополнительную информацию:
-### Порядок расположения тегов
+### Порядок расположения тегов { #order-of-tags }
-Порядок расположения словарей метаданных для каждого тега определяет также порядок, отображаемый в документах UI
+Порядок расположения словарей метаданных для каждого тега определяет также порядок, отображаемый в UI документации.
К примеру, несмотря на то, что `users` будут идти после `items` в алфавитном порядке, они отображаются раньше, потому что мы добавляем свои метаданные в качестве первого словаря в списке.
-## URL-адреса OpenAPI
+## URL-адрес OpenAPI { #openapi-url }
По умолчанию схема OpenAPI отображена по адресу `/openapi.json`.
@@ -90,13 +100,13 @@
К примеру, чтобы задать её отображение по адресу `/api/v1/openapi.json`:
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}
-Если вы хотите отключить схему OpenAPI полностью, вы можете задать `openapi_url=None`, это также отключит пользовательские интерфейсы документации, которые его использует.
+Если вы хотите отключить схему OpenAPI полностью, вы можете задать `openapi_url=None`, это также отключит пользовательские интерфейсы документации, которые её используют.
-## URL-адреса документации
+## URL-адреса документации { #docs-urls }
-Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, среди которых
+Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, которые включены:
* **Swagger UI**: отображаемый по адресу `/docs`.
* Вы можете задать его URL с помощью параметра `docs_url`.
@@ -107,4 +117,4 @@
К примеру, чтобы задать отображение Swagger UI по адресу `/documentation` и отключить ReDoc:
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/ru/docs/tutorial/middleware.md b/docs/ru/docs/tutorial/middleware.md
index 845e881e1..a83d3c011 100644
--- a/docs/ru/docs/tutorial/middleware.md
+++ b/docs/ru/docs/tutorial/middleware.md
@@ -1,4 +1,4 @@
-# Middleware (Промежуточный слой)
+# Middleware (Промежуточный слой) { #middleware }
Вы можете добавить промежуточный слой (middleware) в **FastAPI** приложение.
@@ -17,11 +17,11 @@
Если у вас есть зависимости с `yield`, то код выхода (код после `yield`) будет выполняться *после* middleware.
-Если у вас имеются некие фоновые задачи (см. документацию), то они будут запущены после middleware.
+Если были какие‑либо фоновые задачи (рассматриваются в разделе [Фоновые задачи](background-tasks.md){.internal-link target=_blank}, вы увидите это позже), они будут запущены *после* всех middleware.
///
-## Создание middleware
+## Создание middleware { #create-a-middleware }
Для создания middleware используйте декоратор `@app.middleware("http")`.
@@ -33,13 +33,13 @@
* Затем она возвращает ответ `response`, сгенерированный *операцией пути*.
* Также имеется возможность видоизменить `response`, перед тем как его вернуть.
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip | Примечание
Имейте в виду, что можно добавлять свои собственные заголовки при помощи префикса 'X-'.
-Если же вы хотите добавить собственные заголовки, которые клиент сможет увидеть в браузере, то вам потребуется добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, см. документацию Starlette's CORS docs.
+Если же вы хотите добавить собственные заголовки, которые клиент сможет увидеть в браузере, то вам потребуется добавить их в настройки CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}), используя параметр `expose_headers`, см. документацию Starlette's CORS docs.
///
@@ -51,7 +51,7 @@
///
-### До и после `response`
+### До и после `response` { #before-and-after-the-response }
Вы можете добавить код, использующий `request` до передачи его какой-либо *операции пути*.
@@ -59,7 +59,7 @@
Например, вы можете добавить собственный заголовок `X-Process-Time`, содержащий время в секундах, необходимое для обработки запроса и генерации ответа:
-{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *}
/// tip | Примечание
@@ -67,8 +67,31 @@
///
-## Другие middleware
+## Порядок выполнения нескольких middleware { #multiple-middleware-execution-order }
+
+Когда вы добавляете несколько middleware с помощью декоратора `@app.middleware()` или метода `app.add_middleware()`, каждое новое middleware оборачивает приложение, формируя стек. Последнее добавленное middleware — самое внешнее (*outermost*), а первое — самое внутреннее (*innermost*).
+
+На пути обработки запроса сначала выполняется самое внешнее middleware.
+
+На пути формирования ответа оно выполняется последним.
+
+Например:
+
+```Python
+app.add_middleware(MiddlewareA)
+app.add_middleware(MiddlewareB)
+```
+
+Это приводит к следующему порядку выполнения:
+
+* **Запрос**: MiddlewareB → MiddlewareA → маршрут
+
+* **Ответ**: маршрут → MiddlewareA → MiddlewareB
+
+Такое стековое поведение обеспечивает предсказуемый и управляемый порядок выполнения middleware.
+
+## Другие middleware { #other-middlewares }
О других middleware вы можете узнать больше в разделе [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.
-В следующем разделе вы можете прочитать, как настроить CORS с помощью middleware.
+В следующем разделе вы можете прочитать, как настроить CORS с помощью middleware.
diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md
index af471ca69..96a54ffea 100644
--- a/docs/ru/docs/tutorial/path-operation-configuration.md
+++ b/docs/ru/docs/tutorial/path-operation-configuration.md
@@ -1,4 +1,4 @@
-# Конфигурация операций пути
+# Конфигурация операций пути { #path-operation-configuration }
Существует несколько параметров, которые вы можете передать вашему *декоратору операций пути* для его настройки.
@@ -8,7 +8,7 @@
///
-## Коды состояния
+## Статус-код ответа { #response-status-code }
Вы можете определить (HTTP) `status_code`, который будет использован в ответах вашей *операции пути*.
@@ -18,7 +18,7 @@
{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}
-Этот код состояния будет использован в ответе и будет добавлен в схему OpenAPI.
+Этот статус-код будет использован в ответе и будет добавлен в схему OpenAPI.
/// note | Технические детали
@@ -28,7 +28,7 @@
///
-## Теги
+## Теги { #tags }
Вы можете добавлять теги к вашим *операциям пути*, добавив параметр `tags` с `list` заполненным `str`-значениями (обычно в нём только одна строка):
@@ -38,7 +38,7 @@
-### Теги с перечислениями
+### Теги с перечислениями { #tags-with-enums }
Если у вас большое приложение, вы можете прийти к необходимости добавить **несколько тегов**, и возможно, вы захотите убедиться в том, что всегда используете **один и тот же тег** для связанных *операций пути*.
@@ -46,15 +46,15 @@
**FastAPI** поддерживает это так же, как и в случае с обычными строками:
-{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
+{* ../../docs_src/path_operation_configuration/tutorial002b_py39.py hl[1,8:10,13,18] *}
-## Краткое и развёрнутое содержание
+## Краткое и развёрнутое содержание { #summary-and-description }
Вы можете добавить параметры `summary` и `description`:
{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
-## Описание из строк документации
+## Описание из строк документации { #description-from-docstring }
Так как описания обычно длинные и содержат много строк, вы можете объявить описание *операции пути* в функции строки документации и **FastAPI** прочитает её отсюда.
@@ -66,7 +66,7 @@
-## Описание ответа
+## Описание ответа { #response-description }
Вы можете указать описание ответа с помощью параметра `response_description`:
@@ -78,7 +78,7 @@
///
-/// check | Технические детали
+/// check
OpenAPI указывает, что каждой *операции пути* необходимо описание ответа.
@@ -88,11 +88,11 @@ OpenAPI указывает, что каждой *операции пути* не
-## Обозначение *операции пути* как устаревшей
+## Обозначение *операции пути* как устаревшей { #deprecate-a-path-operation }
Если вам необходимо пометить *операцию пути* как устаревшую, при этом не удаляя её, передайте параметр `deprecated`:
-{* ../../docs_src/path_operation_configuration/tutorial006.py hl[16] *}
+{* ../../docs_src/path_operation_configuration/tutorial006_py39.py hl[16] *}
Он будет четко помечен как устаревший в интерактивной документации:
@@ -102,6 +102,6 @@ OpenAPI указывает, что каждой *операции пути* не
-## Резюме
+## Резюме { #recap }
Вы можете легко конфигурировать и добавлять метаданные в ваши *операции пути*, передавая параметры *декораторам операций пути*.
diff --git a/docs/ru/docs/tutorial/path-params-numeric-validations.md b/docs/ru/docs/tutorial/path-params-numeric-validations.md
index dca267f78..f0fe78805 100644
--- a/docs/ru/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/ru/docs/tutorial/path-params-numeric-validations.md
@@ -1,8 +1,8 @@
-# Path-параметры и валидация числовых данных
+# Path-параметры и валидация числовых данных { #path-parameters-and-numeric-validations }
Так же, как с помощью `Query` вы можете добавлять валидацию и метаданные для query-параметров, так и с помощью `Path` вы можете добавлять такую же валидацию и метаданные для path-параметров.
-## Импорт Path
+## Импорт `Path` { #import-path }
Сначала импортируйте `Path` из `fastapi`, а также импортируйте `Annotated`:
@@ -14,11 +14,11 @@
Если вы используете более старую версию, вы столкнётесь с ошибками при попытке использовать `Annotated`.
-Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#fastapi_2){.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать `Annotated`.
+Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} как минимум до 0.95.1 перед тем, как использовать `Annotated`.
///
-## Определите метаданные
+## Определите метаданные { #declare-metadata }
Вы можете указать все те же параметры, что и для `Query`.
@@ -28,15 +28,11 @@
/// note | Примечание
-Path-параметр всегда является обязательным, поскольку он составляет часть пути.
-
-Поэтому следует объявить его с помощью `...`, чтобы обозначить, что этот параметр обязательный.
-
-Тем не менее, даже если вы объявите его как `None` или установите для него значение по умолчанию, это ни на что не повлияет и параметр останется обязательным.
+Path-параметр всегда является обязательным, поскольку он должен быть частью пути. Даже если вы объявите его как `None` или зададите значение по умолчанию, это ни на что не повлияет — параметр всё равно будет обязательным.
///
-## Задайте нужный вам порядок параметров
+## Задайте нужный вам порядок параметров { #order-the-parameters-as-you-need }
/// tip | Подсказка
@@ -58,25 +54,13 @@ Path-параметр всегда является обязательным, п
Поэтому вы можете определить функцию так:
-//// tab | Python 3.8 без Annotated
-
-/// tip | Подсказка
-
-Рекомендуется использовать версию с `Annotated` если возможно.
-
-///
-
-```Python hl_lines="7"
-{!> ../../docs_src/path_params_numeric_validations/tutorial002.py!}
-```
-
-////
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *}
-Но имейте в виду, что если вы используете `Annotated`, вы не столкнётесь с этой проблемой, так как вы не используете `Query()` или `Path()` в качестве значения по умолчанию для параметра функции.
+Но имейте в виду, что если вы используете `Annotated`, вы не столкнётесь с этой проблемой, так как вы не используете значения по умолчанию параметров функции для `Query()` или `Path()`.
-{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
-## Задайте нужный вам порядок параметров, полезные приёмы
+## Задайте нужный вам порядок параметров, полезные приёмы { #order-the-parameters-as-you-need-tricks }
/// tip | Подсказка
@@ -97,25 +81,25 @@ Path-параметр всегда является обязательным, п
Передайте `*` в качестве первого параметра функции.
-Python не будет ничего делать с `*`, но он будет знать, что все следующие параметры являются именованными аргументами (парами ключ-значение), также известными как kwargs, даже если у них нет значений по умолчанию.
+Python не будет ничего делать с `*`, но он будет знать, что все следующие параметры являются именованными аргументами (парами ключ-значение), также известными как kwargs, даже если у них нет значений по умолчанию.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
-### Лучше с `Annotated`
+### Лучше с `Annotated` { #better-with-annotated }
-Имейте в виду, что если вы используете `Annotated`, то, поскольку вы не используете значений по умолчанию для параметров функции, то у вас не возникнет подобной проблемы и вам не придётся использовать `*`.
+Имейте в виду, что если вы используете `Annotated`, то, поскольку вы не используете значений по умолчанию для параметров функции, у вас не возникнет подобной проблемы и вам, вероятно, не придётся использовать `*`.
{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
-## Валидация числовых данных: больше или равно
+## Валидация числовых данных: больше или равно { #number-validations-greater-than-or-equal }
С помощью `Query` и `Path` (и других классов, которые мы разберём позже) вы можете добавлять ограничения для числовых данных.
-В этом примере при указании `ge=1`, параметр `item_id` должен быть больше или равен `1` ("`g`reater than or `e`qual").
+В этом примере при указании `ge=1`, параметр `item_id` должен быть целым числом "`g`reater than or `e`qual" — больше или равно `1`.
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
-## Валидация числовых данных: больше и меньше или равно
+## Валидация числовых данных: больше и меньше или равно { #number-validations-greater-than-and-less-than-or-equal }
То же самое применимо к:
@@ -124,19 +108,19 @@ Python не будет ничего делать с `*`, но он будет з
{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
-## Валидация числовых данных: числа с плавающей точкой, больше и меньше
+## Валидация числовых данных: числа с плавающей точкой, больше и меньше { #number-validations-floats-greater-than-and-less-than }
Валидация также применима к значениям типа `float`.
-В этом случае становится важной возможность добавить ограничение gt, вместо ge, поскольку в таком случае вы можете, например, создать ограничение, чтобы значение было больше `0`, даже если оно меньше `1`.
+В этом случае становится важной возможность добавить ограничение gt, вместо ge, поскольку в таком случае вы можете, например, создать ограничение, чтобы значение было больше `0`, даже если оно меньше `1`.
Таким образом, `0.5` будет корректным значением. А `0.0` или `0` — нет.
-То же самое справедливо и для lt.
+То же самое справедливо и для lt.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## Резюме
+## Резюме { #recap }
С помощью `Query`, `Path` (и других классов, которые мы пока не затронули) вы можете добавлять метаданные и строковую валидацию тем же способом, как и в главе [Query-параметры и валидация строк](query-params-str-validations.md){.internal-link target=_blank}.
@@ -149,7 +133,7 @@ Python не будет ничего делать с `*`, но он будет з
/// info | Информация
-`Query`, `Path` и другие классы, которые мы разберём позже, являются наследниками общего класса `Param`.
+`Query`, `Path` и другие классы, которые вы разберёте позже, являются наследниками общего класса `Param`.
Все они используют те же параметры для дополнительной валидации и метаданных, которые вы видели ранее.
diff --git a/docs/ru/docs/tutorial/path-params.md b/docs/ru/docs/tutorial/path-params.md
index 5c2d82a65..83a7ed3ff 100644
--- a/docs/ru/docs/tutorial/path-params.md
+++ b/docs/ru/docs/tutorial/path-params.md
@@ -1,8 +1,8 @@
-# Path-параметры
+# Path-параметры { #path-parameters }
Вы можете определить "параметры" или "переменные" пути, используя синтаксис форматированных строк Python:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
Значение параметра пути `item_id` будет передано в функцию в качестве аргумента `item_id`.
@@ -12,21 +12,21 @@
{"item_id":"foo"}
```
-## Параметры пути с типами
+## Параметры пути с типами { #path-parameters-with-types }
-Вы можете объявить тип параметра пути в функции, используя стандартные аннотации типов Python.
+Вы можете объявить тип параметра пути в функции, используя стандартные аннотации типов Python:
-{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *}
Здесь, `item_id` объявлен типом `int`.
/// check | Заметка
-Это обеспечит поддержку редактора внутри функции (проверка ошибок, автодополнение и т.п.).
+Это обеспечит поддержку редактора кода внутри функции (проверка ошибок, автозавершение и т.п.).
///
-## Преобразование данных
+## Преобразование данных { #data-conversion }
Если запустите этот пример и перейдёте по адресу: http://127.0.0.1:8000/items/3, то увидите ответ:
@@ -38,44 +38,45 @@
Обратите внимание на значение `3`, которое получила (и вернула) функция. Это целочисленный Python `int`, а не строка `"3"`.
-Используя определения типов, **FastAPI** выполняет автоматический "парсинг" запросов.
+Используя такое объявление типов, **FastAPI** выполняет автоматический "парсинг" запросов.
///
-## Проверка данных
+## Валидация данных { #data-validation }
Если откроете браузер по адресу http://127.0.0.1:8000/items/foo, то увидите интересную HTTP-ошибку:
```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"
+ }
+ ]
}
```
-из-за того, что параметр пути `item_id` имеет значение `"foo"`, которое не является типом `int`.
+из-за того, что параметр пути `item_id` имеет значение `"foo"`, которое не является типом `int`.
-Та же ошибка возникнет, если вместо `int` передать `float` , например: http://127.0.0.1:8000/items/4.2
+Та же ошибка возникнет, если вместо `int` передать `float`, например: http://127.0.0.1:8000/items/4.2
/// check | Заметка
-**FastAPI** обеспечивает проверку типов, используя всё те же определения типов.
+**FastAPI** обеспечивает валидацию данных, используя всё те же определения типов.
-Обратите внимание, что в тексте ошибки явно указано место не прошедшее проверку.
+Обратите внимание, что в тексте ошибки явно указано место, не прошедшее проверку.
Это очень полезно при разработке и отладке кода, который взаимодействует с API.
///
-## Документация
+## Документация { #documentation }
И теперь, когда откроете браузер по адресу: http://127.0.0.1:8000/docs, то увидите вот такую автоматически сгенерированную документацию API:
@@ -89,17 +90,17 @@
///
-## Преимущества стандартизации, альтернативная документация
+## Преимущества стандартизации, альтернативная документация { #standards-based-benefits-alternative-documentation }
-Поскольку сгенерированная схема соответствует стандарту OpenAPI, её можно использовать со множеством совместимых инструментов.
+Поскольку сгенерированная схема соответствует стандарту OpenAPI, её можно использовать со множеством совместимых инструментов.
-Именно поэтому, FastAPI сам предоставляет альтернативную документацию API (используя ReDoc), которую можно получить по адресу: http://127.0.0.1:8000/redoc.
+Именно поэтому, **FastAPI** сам предоставляет альтернативную документацию API (используя ReDoc), которую можно получить по адресу: http://127.0.0.1:8000/redoc.
По той же причине, есть множество совместимых инструментов, включая инструменты генерации кода для многих языков.
-## Pydantic
+## Pydantic { #pydantic }
Вся проверка данных выполняется под капотом с помощью Pydantic. Поэтому вы можете быть уверены в качестве обработки данных.
@@ -107,7 +108,7 @@
Некоторые из них рассматриваются в следующих главах данного руководства.
-## Порядок имеет значение
+## Порядок имеет значение { #order-matters }
При создании *операций пути* можно столкнуться с ситуацией, когда путь является фиксированным.
@@ -117,22 +118,21 @@
Поскольку *операции пути* выполняются в порядке их объявления, необходимо, чтобы путь для `/users/me` был объявлен раньше, чем путь для `/users/{user_id}`:
-
-{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *}
Иначе путь для `/users/{user_id}` также будет соответствовать `/users/me`, "подразумевая", что он получает параметр `user_id` со значением `"me"`.
Аналогично, вы не можете переопределить операцию с путем:
-{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
Первый будет выполняться всегда, так как путь совпадает первым.
-## Предопределенные значения
+## Предопределенные значения { #predefined-values }
Что если нам нужно заранее определить допустимые *параметры пути*, которые *операция пути* может принимать? В таком случае можно использовать стандартное перечисление `Enum` Python.
-### Создание класса `Enum`
+### Создание класса `Enum` { #create-an-enum-class }
Импортируйте `Enum` и создайте подкласс, который наследуется от `str` и `Enum`.
@@ -140,47 +140,41 @@
Затем создайте атрибуты класса с фиксированными допустимыми значениями:
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
-
-/// info | Дополнительная информация
-
-Перечисления (enum) доступны в Python начиная с версии 3.4.
-
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip | Подсказка
-Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей машинного обучения.
+Если интересно, то "AlexNet", "ResNet" и "LeNet" - это названия моделей Машинного обучения.
///
-### Определение *параметра пути*
+### Определение *параметра пути* { #declare-a-path-parameter }
Определите *параметр пути*, используя в аннотации типа класс перечисления (`ModelName`), созданный ранее:
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
-### Проверьте документацию
+### Проверьте документацию { #check-the-docs }
Поскольку доступные значения *параметра пути* определены заранее, интерактивная документация может наглядно их отображать:
-### Работа с *перечислениями* в Python
+### Работа с *перечислениями* в Python { #working-with-python-enumerations }
Значение *параметра пути* будет *элементом перечисления*.
-#### Сравнение *элементов перечисления*
+#### Сравнение *элементов перечисления* { #compare-enumeration-members }
Вы можете сравнить это значение с *элементом перечисления* класса `ModelName`:
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
-#### Получение *значения перечисления*
+#### Получение *значения перечисления* { #get-the-enumeration-value }
Можно получить фактическое значение (в данном случае - `str`) с помощью `model_name.value` или в общем случае `your_enum_member.value`:
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip | Подсказка
@@ -188,13 +182,13 @@
///
-#### Возврат *элементов перечисления*
+#### Возврат *элементов перечисления* { #return-enumeration-members }
Из *операции пути* можно вернуть *элементы перечисления*, даже вложенные в тело JSON (например в `dict`).
Они будут преобразованы в соответствующие значения (в данном случае - строки) перед их возвратом клиенту:
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}
Вы отправите клиенту такой JSON-ответ:
```JSON
@@ -204,7 +198,7 @@
}
```
-## Path-параметры, содержащие пути
+## Path-параметры, содержащие пути { #path-parameters-containing-paths }
Предположим, что есть *операция пути* с путем `/files/{file_path}`.
@@ -212,7 +206,7 @@
Тогда URL для этого файла будет такой: `/files/home/johndoe/myfile.txt`.
-### Поддержка OpenAPI
+### Поддержка OpenAPI { #openapi-support }
OpenAPI не поддерживает способов объявления *параметра пути*, содержащего внутри *путь*, так как это может привести к сценариям, которые сложно определять и тестировать.
@@ -220,7 +214,7 @@ OpenAPI не поддерживает способов объявления *п
Документация по-прежнему будет работать, хотя и не добавит никакой информации о том, что параметр должен содержать путь.
-### Конвертер пути
+### Конвертер пути { #path-convertor }
Благодаря одной из опций Starlette, можете объявить *параметр пути*, содержащий *путь*, используя URL вроде:
@@ -232,7 +226,7 @@ OpenAPI не поддерживает способов объявления *п
Можете использовать так:
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}
/// tip | Подсказка
@@ -242,13 +236,14 @@ OpenAPI не поддерживает способов объявления *п
///
-## Резюме
+## Резюме { #recap }
+
Используя **FastAPI** вместе со стандартными объявлениями типов Python (короткими и интуитивно понятными), вы получаете:
-* Поддержку редактора (проверку ошибок, автозаполнение и т.п.)
+* Поддержку редактора кода (проверку ошибок, автозавершение и т.п.)
* "Парсинг" данных
* Валидацию данных
-* Автоматическую документацию API с указанием типов параметров.
+* Аннотации API и автоматическую документацию
И объявлять типы достаточно один раз.
diff --git a/docs/ru/docs/tutorial/query-param-models.md b/docs/ru/docs/tutorial/query-param-models.md
index 4d76d09e8..5ad7f1d99 100644
--- a/docs/ru/docs/tutorial/query-param-models.md
+++ b/docs/ru/docs/tutorial/query-param-models.md
@@ -1,4 +1,4 @@
-# Модели Query-Параметров
+# Модели Query-Параметров { #query-parameter-models }
Если у вас есть группа связанных **query-параметров**, то вы можете объединить их в одну **Pydantic-модель**.
@@ -10,7 +10,7 @@
///
-## Pydantic-Модель для Query-Параметров
+## Pydantic-Модель для Query-Параметров { #query-parameters-with-a-pydantic-model }
Объявите нужные **query-параметры** в **Pydantic-модели**, а после аннотируйте параметр как `Query`:
@@ -18,7 +18,7 @@
**FastAPI извлечёт** данные соответствующие **каждому полю модели** из **query-параметров** запроса и выдаст вам объявленную Pydantic-модель заполненную ими.
-## Проверьте Сгенерированную Документацию
+## Проверьте Сгенерированную Документацию { #check-the-docs }
Вы можете посмотреть query-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`:
@@ -26,7 +26,7 @@
-## Запретить Дополнительные Query-Параметры
+## Запретить Дополнительные Query-Параметры { #forbid-extra-query-parameters }
В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** query-параметры, которые вы хотите получить.
@@ -57,12 +57,12 @@ https://example.com/items/?limit=10&tool=plumbus
}
```
-## Заключение
+## Заключение { #summary }
Вы можете использовать **Pydantic-модели** для объявления **query-параметров** в **FastAPI**. 😎
/// tip | Совет
-Спойлер: вы также можете использовать Pydantic-модели для группировки кук (cookies) и заголовков (headers), но об этом вы прочитаете позже. 🤫
+Спойлер: вы также можете использовать Pydantic-модели, чтобы объявлять cookies и HTTP-заголовки, но об этом вы прочитаете позже. 🤫
///
diff --git a/docs/ru/docs/tutorial/query-params-str-validations.md b/docs/ru/docs/tutorial/query-params-str-validations.md
index 13b7015db..2bc2fb22c 100644
--- a/docs/ru/docs/tutorial/query-params-str-validations.md
+++ b/docs/ru/docs/tutorial/query-params-str-validations.md
@@ -1,61 +1,51 @@
-# Query-параметры и валидация строк
+# Query-параметры и валидация строк { #query-parameters-and-string-validations }
-**FastAPI** позволяет определять дополнительную информацию и валидацию для ваших параметров.
+**FastAPI** позволяет определять дополнительную информацию и выполнять валидацию для ваших параметров.
-Давайте рассмотрим следующий пример:
+Рассмотрим это приложение в качестве примера:
{* ../../docs_src/query_params_str_validations/tutorial001_py310.py hl[7] *}
-Query-параметр `q` имеет тип `Union[str, None]` (или `str | None` в Python 3.10). Это означает, что входной параметр будет типа `str`, но может быть и `None`. Ещё параметр имеет значение по умолчанию `None`, из-за чего FastAPI определит параметр как необязательный.
+Query-параметр `q` имеет тип `str | None`, это означает, что он имеет тип `str`, но также может быть `None`. Значение по умолчанию действительно `None`, поэтому FastAPI будет знать, что он не обязателен.
-/// note | Технические детали
+/// note | Примечание
-FastAPI определит параметр `q` как необязательный, потому что его значение по умолчанию `= None`.
+FastAPI поймёт, что значение `q` не обязательно, из‑за значения по умолчанию `= None`.
-`Union` в `Union[str, None]` позволит редактору кода оказать вам лучшую поддержку и найти ошибки.
+Аннотация `str | None` позволит вашему редактору кода обеспечить лучшую поддержку и находить ошибки.
///
-## Расширенная валидация
+## Дополнительная валидация { #additional-validation }
-Добавим дополнительное условие валидации параметра `q` - **длина строки не более 50 символов** (условие проверяется всякий раз, когда параметр `q` не является `None`).
+Мы собираемся добавить ограничение: хотя `q` и необязателен, когда он передан, **его длина не должна превышать 50 символов**.
-### Импорт `Query` и `Annotated`
+### Импорт `Query` и `Annotated` { #import-query-and-annotated }
-Чтобы достичь этого, первым делом нам нужно импортировать:
+Чтобы сделать это, сначала импортируйте:
-* `Query` из пакета `fastapi`:
-* `Annotated` из пакета `typing` (или из `typing_extensions` для Python ниже 3.9)
+* `Query` из `fastapi`
+* `Annotated` из `typing`
-//// tab | Python 3.10+
-
-В Python 3.9 или выше, `Annotated` является частью стандартной библиотеки, таким образом вы можете импортировать его из `typing`.
-
-```Python hl_lines="1 3"
-{!> ../../docs_src/query_params_str_validations/tutorial002_an_py310.py!}
-```
-
-////
+{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-//// tab | Python 3.8+
+/// info | Дополнительная информация
-В версиях Python ниже Python 3.9 `Annotation` импортируется из `typing_extensions`.
+Поддержка `Annotated` (и рекомендация использовать его) появилась в FastAPI версии 0.95.0.
-Эта библиотека будет установлена вместе с FastAPI.
+Если у вас более старая версия, при попытке использовать `Annotated` вы получите ошибки.
-```Python hl_lines="3-4"
-{!> ../../docs_src/query_params_str_validations/tutorial002_an.py!}
-```
+Убедитесь, что вы [обновили версию FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} как минимум до 0.95.1 перед использованием `Annotated`.
-////
+///
-## `Annotated` как тип для query-параметра `q`
+## Использовать `Annotated` в типе для параметра `q` { #use-annotated-in-the-type-for-the-q-parameter }
-Помните, как ранее я говорил об Annotated? Он может быть использован для добавления метаданных для ваших параметров в разделе [Введение в аннотации типов Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
+Помните, я уже говорил, что `Annotated` можно использовать для добавления метаданных к параметрам в разделе [Введение в типы Python](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
-Пришло время использовать их в FastAPI. 🚀
+Пришло время использовать его с FastAPI. 🚀
-У нас была аннотация следующего типа:
+У нас была такая аннотация типа:
//// tab | Python 3.10+
@@ -65,7 +55,7 @@ q: str | None = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Union[str, None] = None
@@ -73,7 +63,7 @@ q: Union[str, None] = None
////
-Вот что мы получим, если обернём это в `Annotated`:
+Мы «обернём» это в `Annotated`, и получится:
//// tab | Python 3.10+
@@ -83,7 +73,7 @@ q: Annotated[str | None] = None
////
-//// tab | Python 3.8+
+//// tab | Python 3.9+
```Python
q: Annotated[Union[str, None]] = None
@@ -91,173 +81,147 @@ q: Annotated[Union[str, None]] = None
////
-Обе эти версии означают одно и тоже. `q` - это параметр, который может быть `str` или `None`, и по умолчанию он будет принимать `None`.
+Обе версии означают одно и то же: `q` — параметр, который может быть `str` или `None`, и по умолчанию равен `None`.
-Давайте повеселимся. 🎉
+А теперь к самому интересному. 🎉
-## Добавим `Query` в `Annotated` для query-параметра `q`
+## Добавим `Query` в `Annotated` для параметра `q` { #add-query-to-annotated-in-the-q-parameter }
-Теперь, когда у нас есть `Annotated`, где мы можем добавить больше метаданных, добавим `Query` со значением параметра `max_length` равным 50:
+Теперь, когда у нас есть `Annotated`, куда можно поместить дополнительную информацию (в нашем случае — дополнительные правила валидации), добавим `Query` внутрь `Annotated` и установим параметр `max_length` равным `50`:
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[9] *}
-Обратите внимание, что значение по умолчанию всё ещё `None`, так что параметр остаётся необязательным.
+Обратите внимание, что значение по умолчанию по‑прежнему `None`, то есть параметр остаётся необязательным.
-Однако теперь, имея `Query(max_length=50)` внутри `Annotated`, мы говорим FastAPI, что мы хотим извлечь это значение из параметров query-запроса (что произойдёт в любом случае 🤷), и что мы хотим иметь **дополнительные условия валидации** для этого значения (для чего мы и делаем это - чтобы получить дополнительную валидацию). 😎
+Но теперь, добавив `Query(max_length=50)` внутрь `Annotated`, мы говорим FastAPI, что этому значению нужна **дополнительная валидация** — максимум 50 символов. 😎
-Теперь FastAPI:
+/// tip | Совет
-* **Валидирует** (проверяет), что полученные данные состоят максимум из 50 символов
-* Показывает **исчерпывающую ошибку** (будет описание местонахождения ошибки и её причины) для клиента в случаях, когда данные не валидны
-* **Задокументирует** параметр в схему OpenAPI *операции пути* (что будет отображено в **UI автоматической документации**)
+Здесь мы используем `Query()`, потому что это **query-параметр**. Позже мы увидим другие — `Path()`, `Body()`, `Header()` и `Cookie()`, — они также принимают те же аргументы, что и `Query()`.
-## Альтернативный (устаревший) способ задать `Query` как значение по умолчанию
+///
-В предыдущих версиях FastAPI (ниже 0.95.0) необходимо было использовать `Query` как значение по умолчанию для query-параметра. Так было вместо размещения его в `Annotated`, так что велика вероятность, что вам встретится такой код. Сейчас объясню.
+Теперь FastAPI будет:
-/// tip | Подсказка
+* **валидировать** данные, удостоверяясь, что максимальная длина — 50 символов;
+* показывать **понятную ошибку** клиенту, если данные невалидны;
+* **документировать** параметр в *операции пути* схемы OpenAPI (он будет показан в **UI автоматической документации**).
-При написании нового кода и везде где это возможно, используйте `Annotated`, как было описано ранее. У этого способа есть несколько преимуществ (о них дальше) и никаких недостатков. 🍰
+## Альтернатива (устаревшее): `Query` как значение по умолчанию { #alternative-old-query-as-the-default-value }
-///
+В предыдущих версиях FastAPI (до 0.95.0) требовалось использовать `Query` как значение по умолчанию для параметра вместо помещения его в `Annotated`. Скорее всего вы ещё встретите такой код, поэтому поясню.
-Вот как вы могли бы использовать `Query()` в качестве значения по умолчанию параметра вашей функции, установив для параметра `max_length` значение 50:
+/// tip | Подсказка
-{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
+Для нового кода и везде, где это возможно, используйте `Annotated`, как описано выше. У этого есть несколько преимуществ (см. ниже) и нет недостатков. 🍰
-В таком случае (без использования `Annotated`), мы заменили значение по умолчанию с `None` на `Query()` в функции. Теперь нам нужно установить значение по умолчанию для query-параметра `Query(default=None)`, что необходимо для тех же целей, как когда ранее просто указывалось значение по умолчанию (по крайней мере, для FastAPI).
+///
-Таким образом:
+Вот как можно использовать `Query()` как значение по умолчанию для параметра функции, установив `max_length` равным 50:
-```Python
-q: Union[str, None] = Query(default=None)
-```
-
-...делает параметр необязательным со значением по умолчанию `None`, также как это делает:
+{* ../../docs_src/query_params_str_validations/tutorial002_py310.py hl[7] *}
-```Python
-q: Union[str, None] = None
-```
+Так как в этом случае (без `Annotated`) мы заменяем в функции значение по умолчанию `None` на `Query()`, теперь нужно указать значение по умолчанию через параметр `Query(default=None)`, это служит той же цели — задать значение по умолчанию (по крайней мере для FastAPI).
-И для Python 3.10 и выше:
+Итак:
```Python
q: str | None = Query(default=None)
```
-...делает параметр необязательным со значением по умолчанию `None`, также как это делает:
+...делает параметр необязательным со значением по умолчанию `None`, так же как:
```Python
q: str | None = None
```
-Но он явно объявляет его как query-параметр.
+Но вариант с `Query` явно объявляет его как query-параметр.
-/// info | Дополнительная информация
-
-Запомните, важной частью объявления параметра как необязательного является:
-
-```Python
-= None
-```
-
-или:
-
-```Python
-= Query(default=None)
-```
-
-так как `None` указан в качестве значения по умолчанию, параметр будет **необязательным**.
-
-`Union[str, None]` позволит редактору кода оказать вам лучшую поддержку. Но это не то, на что обращает внимание FastAPI для определения необязательности параметра.
-
-///
-
-Теперь, мы можем указать больше параметров для `Query`. В данном случае, параметр `max_length` применяется к строкам:
+Затем мы можем передать и другие параметры в `Query`. В данном случае — параметр `max_length`, применимый к строкам:
```Python
-q: Union[str, None] = Query(default=None, max_length=50)
+q: str | None = Query(default=None, max_length=50)
```
-Входные данные будут проверены. Если данные недействительны, тогда будет указано на ошибку в запросе (будет описание местонахождения ошибки и её причины). Кроме того, параметр задокументируется в схеме OpenAPI данной *операции пути*.
+Это провалидирует данные, покажет понятную ошибку, если данные невалидны, и задокументирует параметр в *операции пути* схемы OpenAPI.
-### Использовать `Query` как значение по умолчанию или добавить в `Annotated`
+### `Query` как значение по умолчанию или внутри `Annotated` { #query-as-the-default-value-or-in-annotated }
-Когда `Query` используется внутри `Annotated`, вы не можете использовать параметр `default` у `Query`.
+Помните, что при использовании `Query` внутри `Annotated` нельзя указывать параметр `default` у `Query`.
-Вместо этого, используйте обычное указание значения по умолчанию для параметра функции. Иначе, это будет несовместимо.
+Вместо этого используйте обычное значение по умолчанию параметра функции. Иначе это будет неоднозначно.
-Следующий пример не рабочий:
+Например, так делать нельзя:
```Python
q: Annotated[str, Query(default="rick")] = "morty"
```
-...потому что нельзя однозначно определить, что именно должно быть значением по умолчанию: `"rick"` или `"morty"`.
+...потому что непонятно, какое значение должно быть по умолчанию: `"rick"` или `"morty"`.
-Вам следует использовать (предпочтительно):
+Следовательно, используйте (предпочтительно):
```Python
q: Annotated[str, Query()] = "rick"
```
-...или как в старом коде, который вам может попасться:
+...или в старой кодовой базе вы увидите:
```Python
q: str = Query(default="rick")
```
-### Преимущества `Annotated`
+### Преимущества `Annotated` { #advantages-of-annotated }
-**Рекомендуется использовать `Annotated`** вместо значения по умолчанию в параметрах функции, потому что так **лучше** по нескольким причинам. 🤓
+**Рекомендуется использовать `Annotated`** вместо задания значения по умолчанию в параметрах функции — так **лучше** по нескольким причинам. 🤓
-Значение **по умолчанию** у **параметров функции** - это **действительно значение по умолчанию**, что более интуитивно понятно для пользователей Python. 😌
+**Значение по умолчанию** у **параметра функции** — это **настоящее значение по умолчанию**, что более интуитивно для Python. 😌
-Вы можете **вызвать** ту же функцию в **иных местах** без FastAPI, и она **сработает как ожидается**. Если это **обязательный** параметр (без значения по умолчанию), ваш **редактор кода** сообщит об ошибке. **Python** также укажет на ошибку, если вы вызовете функцию без передачи ей обязательного параметра.
+Вы можете **вызвать** эту же функцию в **других местах** без FastAPI, и она будет **работать как ожидается**. Если есть **обязательный** параметр (без значения по умолчанию), ваш **редактор** сообщит об ошибке, **Python** тоже пожалуется, если вы запустите её без передачи обязательного параметра.
-Если вы вместо `Annotated` используете **(устаревший) стиль значений по умолчанию**, тогда при вызове этой функции без FastAPI в **другом месте** вам необходимо **помнить** о передаче аргументов функции, чтобы она работала корректно. В противном случае, значения будут отличаться от тех, что вы ожидаете (например, `QueryInfo` или что-то подобное вместо `str`). И ни ваш редактор кода, ни Python не будут жаловаться на работу этой функции, только когда вычисления внутри дадут сбой.
+Если вы не используете `Annotated`, а применяете **(устаревший) стиль со значением по умолчанию**, то при вызове этой функции без FastAPI в **других местах** вам нужно **помнить** о том, что надо передать аргументы, чтобы всё работало корректно, иначе значения будут не такими, как вы ожидаете (например, вместо `str` будет `QueryInfo` или что-то подобное). И ни редактор, ни Python не будут ругаться при самом вызове функции — ошибка проявится лишь при операциях внутри.
-Так как `Annotated` может принимать более одной аннотации метаданных, то теперь вы можете использовать ту же функцию с другими инструментами, например Typer. 🚀
+Так как `Annotated` может содержать больше одной аннотации метаданных, теперь вы можете использовать ту же функцию и с другими инструментами, например с Typer. 🚀
-## Больше валидации
+## Больше валидаций { #add-more-validations }
-Вы также можете добавить параметр `min_length`:
+Можно также добавить параметр `min_length`:
{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *}
-## Регулярные выражения
+## Регулярные выражения { #add-regular-expressions }
-Вы можете определить регулярное выражение, которому должен соответствовать параметр:
+Вы можете определить регулярное выражение `pattern`, которому должен соответствовать параметр:
{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *}
-Данное регулярное выражение проверяет, что полученное значение параметра:
+Данный шаблон регулярного выражения проверяет, что полученное значение параметра:
-* `^`: начало строки.
-* `fixedquery`: в точности содержит строку `fixedquery`.
-* `$`: конец строки, не имеет символов после `fixedquery`.
+* `^`: начинается с следующих символов, до них нет символов.
+* `fixedquery`: имеет точное значение `fixedquery`.
+* `$`: заканчивается здесь, после `fixedquery` нет никаких символов.
-Не переживайте, если **"регулярное выражение"** вызывает у вас трудности. Это достаточно сложная тема для многих людей. Вы можете сделать множество вещей без использования регулярных выражений.
+Если вы теряетесь во всех этих идеях про **«регулярные выражения»**, не переживайте. Это сложная тема для многих. Многое можно сделать и без них.
-Но когда они вам понадобятся, и вы закончите их освоение, то не будет проблемой использовать их в **FastAPI**.
+Теперь вы знаете, что когда они понадобятся, вы сможете использовать их в **FastAPI**.
-## Значения по умолчанию
+## Значения по умолчанию { #default-values }
-Вы точно также можете указать любое значение `по умолчанию`, как ранее указывали `None`.
+Конечно, можно использовать и другие значения по умолчанию, не только `None`.
-Например, вы хотите для параметра запроса `q` указать, что он должен состоять минимум из 3 символов (`min_length=3`) и иметь значение по умолчанию `"fixedquery"`:
+Допустим, вы хотите объявить, что query-параметр `q` должен иметь `min_length` равный `3` и значение по умолчанию `"fixedquery"`:
{* ../../docs_src/query_params_str_validations/tutorial005_an_py39.py hl[9] *}
-/// note | Технические детали
+/// note | Примечание
-Наличие значения по умолчанию делает параметр необязательным.
+Наличие значения по умолчанию любого типа, включая `None`, делает параметр необязательным.
///
-## Обязательный параметр
+## Обязательные параметры { #required-parameters }
-Когда вам не требуется дополнительная валидация или дополнительные метаданные для параметра запроса, вы можете сделать параметр `q` обязательным просто не указывая значения по умолчанию. Например:
+Когда не требуется объявлять дополнительные проверки или метаданные, можно сделать query-параметр `q` обязательным, просто не указывая значение по умолчанию, например:
```Python
q: str
@@ -266,60 +230,42 @@ q: str
вместо:
```Python
-q: Union[str, None] = None
-```
-
-Но у нас query-параметр определён как `Query`. Например:
-
-//// tab | Annotated
-
-```Python
-q: Annotated[Union[str, None], Query(min_length=3)] = None
+q: str | None = None
```
-////
-
-//// tab | без Annotated
+Но сейчас мы объявляем его через `Query`, например так:
```Python
-q: Union[str, None] = Query(default=None, min_length=3)
+q: Annotated[str | None, Query(min_length=3)] = None
```
-////
-
-В таком случае, чтобы сделать query-параметр `Query` обязательным, вы можете просто не указывать значение по умолчанию:
+Поэтому, когда вам нужно объявить значение как обязательное при использовании `Query`, просто не указывайте значение по умолчанию:
{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
-### Обязательный параметр с `None`
+### Обязательный, но может быть `None` { #required-can-be-none }
-Вы можете определить, что параметр может принимать `None`, но всё ещё является обязательным. Это может потребоваться для того, чтобы пользователи явно указали параметр, даже если его значение будет `None`.
+Можно объявить, что параметр может принимать `None`, но при этом остаётся обязательным. Это заставит клиентов отправлять значение, даже если это значение — `None`.
-Чтобы этого добиться, вам нужно определить `None` как валидный тип для параметра запроса, но также указать `default=...`:
+Для этого объявите, что `None` — валидный тип, но просто не задавайте значение по умолчанию:
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
-/// tip | Подсказка
-
-Pydantic, мощь которого используется в FastAPI для валидации и сериализации, имеет специальное поведение для `Optional` или `Union[Something, None]` без значения по умолчанию. Вы можете узнать об этом больше в документации Pydantic, раздел Обязательные Опциональные поля.
-
-///
-
-## Множество значений для query-параметра
+## Query-параметр - список / несколько значений { #query-parameter-list-multiple-values }
-Для query-параметра `Query` можно указать, что он принимает список значений (множество значений).
+Когда вы явно объявляете query-параметр через `Query`, можно также указать, что он принимает список значений, иначе говоря — несколько значений.
-Например, query-параметр `q` может быть указан в URL несколько раз. И если вы ожидаете такой формат запроса, то можете указать это следующим образом:
+Например, чтобы объявить query-параметр `q`, который может встречаться в URL несколько раз, можно написать:
{* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *}
-Затем, получив такой URL:
+Тогда при таком URL:
```
http://localhost:8000/items/?q=foo&q=bar
```
-вы бы получили несколько значений (`foo` и `bar`), которые относятся к параметру `q`, в виде Python `list` внутри вашей *функции обработки пути*, в *параметре функции* `q`.
+вы получите множественные значения *query-параметров* `q` (`foo` и `bar`) в виде Python-`list` внутри вашей *функции-обработчика пути*, в *параметре функции* `q`.
Таким образом, ответ на этот URL будет:
@@ -332,29 +278,29 @@ http://localhost:8000/items/?q=foo&q=bar
}
```
-/// tip | Подсказка
+/// tip | Совет
-Чтобы объявить query-параметр типом `list`, как в примере выше, вам нужно явно использовать `Query`, иначе он будет интерпретирован как тело запроса.
+Чтобы объявить query-параметр типа `list`, как в примере выше, нужно явно использовать `Query`, иначе он будет интерпретирован как тело запроса.
///
-Интерактивная документация API будет обновлена соответствующим образом, где будет разрешено множество значений:
+Интерактивная документация API обновится соответствующим образом и позволит передавать несколько значений:
-### Query-параметр со множеством значений по умолчанию
+### Query-параметр - список / несколько значений со значением по умолчанию { #query-parameter-list-multiple-values-with-defaults }
-Вы также можете указать тип `list` со списком значений по умолчанию на случай, если вам их не предоставят:
+Можно также определить значение по умолчанию как `list`, если ничего не передано:
{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
-Если вы перейдёте по ссылке:
+Если вы перейдёте по адресу:
```
http://localhost:8000/items/
```
-значение по умолчанию для `q` будет: `["foo", "bar"]` и ответом для вас будет:
+значение по умолчанию для `q` будет: `["foo", "bar"]`, и ответом будет:
```JSON
{
@@ -365,45 +311,45 @@ http://localhost:8000/items/
}
```
-#### Использование `list`
+#### Просто `list` { #using-just-list }
-Вы также можете использовать `list` напрямую вместо `List[str]` (или `list[str]` в Python 3.9+):
+Можно использовать `list` напрямую вместо `list[str]`:
{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
-/// note | Технические детали
+/// note | Примечание
-Запомните, что в таком случае, FastAPI не будет проверять содержимое списка.
+Имейте в виду, что в этом случае FastAPI не будет проверять содержимое списка.
-Например, для List[int] список будет провалидирован (и задокументирован) на содержание только целочисленных элементов. Но для простого `list` такой проверки не будет.
+Например, `list[int]` проверит (и задокументирует), что элементы списка — целые числа. А просто `list` — нет.
///
-## Больше метаданных
+## Больше метаданных { #declare-more-metadata }
-Вы можете добавить больше информации об query-параметре.
+Можно добавить больше информации о параметре.
-Указанная информация будет включена в генерируемую OpenAPI документацию и использована в пользовательском интерфейсе и внешних инструментах.
+Эта информация будет включена в сгенерированную OpenAPI-схему и использована интерфейсами документации и внешними инструментами.
-/// note | Технические детали
+/// note | Примечание
-Имейте в виду, что разные инструменты могут иметь разные уровни поддержки OpenAPI.
+Помните, что разные инструменты могут иметь разный уровень поддержки OpenAPI.
-Некоторые из них могут не отображать (на данный момент) всю заявленную дополнительную информацию, хотя в большинстве случаев отсутствующая функция уже запланирована к разработке.
+Некоторые из них пока могут не показывать всю дополнительную информацию, хотя в большинстве случаев недостающая возможность уже запланирована к разработке.
///
-Вы можете указать название query-параметра, используя параметр `title`:
+Можно задать `title`:
{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
-Добавить описание, используя параметр `description`:
+И `description`:
{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## Псевдонимы параметров
+## Псевдонимы параметров { #alias-parameters }
-Представьте, что вы хотите использовать query-параметр с названием `item-query`.
+Представьте, что вы хотите, чтобы параметр назывался `item-query`.
Например:
@@ -411,54 +357,117 @@ http://localhost:8000/items/
http://127.0.0.1:8000/items/?item-query=foobaritems
```
-Но `item-query` является невалидным именем переменной в Python.
+Но `item-query` — недопустимое имя переменной в Python.
-Наиболее похожее валидное имя `item_query`.
+Ближайший вариант — `item_query`.
-Но вам всё равно необходим `item-query`...
+Но вам всё равно нужно именно `item-query`...
-Тогда вы можете объявить `псевдоним`, и этот псевдоним будет использоваться для поиска значения параметра запроса:
+Тогда можно объявить `alias`, и этот псевдоним будет использован для поиска значения параметра:
{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## Устаревшие параметры
+## Маркировка параметров как устаревших { #deprecating-parameters }
-Предположим, вы больше не хотите использовать какой-либо параметр.
+Предположим, этот параметр вам больше не нравится.
-Вы решили оставить его, потому что клиенты всё ещё им пользуются. Но вы хотите отобразить это в документации как устаревший функционал.
+Его нужно оставить на какое‑то время, так как клиенты его используют, но вы хотите, чтобы в документации он явно отображался как устаревший.
-Тогда для `Query` укажите параметр `deprecated=True`:
+Тогда передайте параметр `deprecated=True` в `Query`:
{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
-В документации это будет отображено следующим образом:
+В документации это будет показано так:
-## Исключить из OpenAPI
+## Исключить параметры из OpenAPI { #exclude-parameters-from-openapi }
-Чтобы исключить query-параметр из генерируемой OpenAPI схемы (а также из системы автоматической генерации документации), укажите в `Query` параметр `include_in_schema=False`:
+Чтобы исключить query-параметр из генерируемой OpenAPI-схемы (и, следовательно, из систем автоматической документации), укажите у `Query` параметр `include_in_schema=False`:
{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
-## Резюме
+## Кастомная валидация { #custom-validation }
+
+Бывают случаи, когда нужна **кастомная валидация**, которую нельзя выразить параметрами выше.
+
+В таких случаях можно использовать **кастомную функцию-валидатор**, которая применяется после обычной валидации (например, после проверки, что значение — это `str`).
+
+Этого можно добиться, используя `AfterValidator` Pydantic внутри `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** (FastAPI Dependencies), вы познакомитесь с ними позже.
+
+Эти кастомные валидаторы предназначены для проверок, которые можно выполнить, имея **только** те же **данные**, что пришли в запросе.
+
+///
+
+### Понимание этого кода { #understand-that-code }
+
+Важный момент — это использовать **`AfterValidator` с функцией внутри `Annotated`**. Смело пропускайте эту часть. 🤸
+
+---
+
+Но если вам любопытен именно этот пример и всё ещё интересно, вот немного подробностей.
+
+#### Строка и `value.startswith()` { #string-with-value-startswith }
+
+Заметили? Метод строки `value.startswith()` может принимать кортеж — тогда будет проверено каждое значение из кортежа:
+
+{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
+
+#### Случайный элемент { #a-random-item }
+
+С помощью `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] *}
+
+## Резюме { #recap }
+
+Вы можете объявлять дополнительные проверки и метаданные для параметров.
+
+Общие метаданные и настройки:
* `alias`
* `title`
* `description`
* `deprecated`
-* `include_in_schema`
-Специфичные правила валидации для строк:
+Проверки, специфичные для строк:
* `min_length`
* `max_length`
-* `regex`
+* `pattern`
+
+Кастомные проверки с использованием `AfterValidator`.
-В рассмотренных примерах показано объявление правил валидации для строковых значений `str`.
+В этих примерах вы видели, как объявлять проверки для значений типа `str`.
-В следующих главах вы увидете, как объявлять правила валидации для других типов (например, чисел).
+Смотрите следующие главы, чтобы узнать, как объявлять проверки для других типов, например чисел.
diff --git a/docs/ru/docs/tutorial/query-params.md b/docs/ru/docs/tutorial/query-params.md
index 547d9831d..be1c0e46e 100644
--- a/docs/ru/docs/tutorial/query-params.md
+++ b/docs/ru/docs/tutorial/query-params.md
@@ -1,8 +1,8 @@
-# Query-параметры
+# Query-параметры { #query-parameters }
-Когда вы объявляете параметры функции, которые не являются параметрами пути, они автоматически интерпретируются как "query"-параметры.
+Когда вы объявляете параметры функции, которые не являются параметрами пути, они автоматически интерпретируются как "query"-параметры.
-{* ../../docs_src/query_params/tutorial001.py hl[9] *}
+{* ../../docs_src/query_params/tutorial001_py39.py hl[9] *}
Query-параметры представляют из себя набор пар ключ-значение, которые идут после знака `?` в URL-адресе, разделенные символами `&`.
@@ -19,7 +19,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
Будучи частью URL-адреса, они "по умолчанию" являются строками.
-Но когда вы объявляете их с использованием аннотаций (в примере выше, как `int`), они конвертируются в указанный тип данных и проходят проверку на соответствие ему.
+Но когда вы объявляете их с использованием типов Python (в примере выше, как `int`), они конвертируются в указанный тип данных и проходят проверку на соответствие ему.
Все те же правила, которые применяются к path-параметрам, также применяются и query-параметрам:
@@ -28,7 +28,7 @@ http://127.0.0.1:8000/items/?skip=0&limit=10
* Проверка на соответствие данных (Валидация)
* Автоматическая документация
-## Значения по умолчанию
+## Значения по умолчанию { #defaults }
Поскольку query-параметры не являются фиксированной частью пути, они могут быть не обязательными и иметь значения по умолчанию.
@@ -57,7 +57,7 @@ http://127.0.0.1:8000/items/?skip=20
* `skip=20`: потому что вы установили это в URL-адресе
* `limit=10`: т.к это было значение по умолчанию
-## Необязательные параметры
+## Необязательные параметры { #optional-parameters }
Аналогично, вы можете объявлять необязательные query-параметры, установив их значение по умолчанию, равное `None`:
@@ -71,7 +71,7 @@ http://127.0.0.1:8000/items/?skip=20
///
-## Преобразование типа параметра запроса
+## Преобразование типа параметра запроса { #query-parameter-type-conversion }
Вы также можете объявлять параметры с типом `bool`, которые будут преобразованы соответственно:
@@ -109,10 +109,9 @@ http://127.0.0.1:8000/items/foo?short=yes
или в любом другом варианте написания (в верхнем регистре, с заглавной буквой, и т.п), внутри вашей функции параметр `short` будет иметь значение `True` типа данных `bool` . В противном случае - `False`.
+## Смешивание query-параметров и path-параметров { #multiple-path-and-query-parameters }
-## Смешивание query-параметров и path-параметров
-
-Вы можете объявлять несколько query-параметров и path-параметров одновременно,**FastAPI** сам разберётся, что чем является.
+Вы можете объявлять несколько query-параметров и path-параметров одновременно, **FastAPI** сам разберётся, что чем является.
И вы не обязаны объявлять их в каком-либо определенном порядке.
@@ -120,15 +119,15 @@ http://127.0.0.1:8000/items/foo?short=yes
{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## Обязательные query-параметры
+## Обязательные query-параметры { #required-query-parameters }
-Когда вы объявляете значение по умолчанию для параметра, который не является path-параметром (в этом разделе, мы пока что познакомились только с path-параметрами), то это значение не является обязательным.
+Когда вы объявляете значение по умолчанию для параметра, который не является path-параметром (в этом разделе, мы пока что познакомились только с path-параметрами), то он не является обязательным.
Если вы не хотите задавать конкретное значение, но хотите сделать параметр необязательным, вы можете установить значение по умолчанию равным `None`.
Но если вы хотите сделать query-параметр обязательным, вы можете просто не указывать значение по умолчанию:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
Здесь параметр запроса `needy` является обязательным параметром с типом данных `str`.
@@ -142,16 +141,17 @@ http://127.0.0.1:8000/items/foo-item
```JSON
{
- "detail": [
- {
- "loc": [
- "query",
- "needy"
- ],
- "msg": "field required",
- "type": "value_error.missing"
- }
- ]
+ "detail": [
+ {
+ "type": "missing",
+ "loc": [
+ "query",
+ "needy"
+ ],
+ "msg": "Field required",
+ "input": null
+ }
+ ]
}
```
@@ -170,7 +170,7 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
}
```
-Конечно, вы можете определить некоторые параметры как обязательные, некоторые - со значением по умполчанию, а некоторые - полностью необязательные:
+Конечно, вы можете определить некоторые параметры как обязательные, некоторые — со значением по умолчанию, а некоторые — полностью необязательные:
{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
@@ -182,6 +182,6 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
/// tip | Подсказка
-Вы можете использовать класс `Enum` также, как ранее применяли его с [Path-параметрами](path-params.md#_7){.internal-link target=_blank}.
+Вы можете использовать класс `Enum` также, как ранее применяли его с [Path-параметрами](path-params.md#predefined-values){.internal-link target=_blank}.
///
diff --git a/docs/ru/docs/tutorial/request-files.md b/docs/ru/docs/tutorial/request-files.md
index 2cfa4e1dc..9cfbd53df 100644
--- a/docs/ru/docs/tutorial/request-files.md
+++ b/docs/ru/docs/tutorial/request-files.md
@@ -1,4 +1,4 @@
-# Загрузка файлов
+# Загрузка файлов { #request-files }
Используя класс `File`, мы можем позволить клиентам загружать файлы.
@@ -6,19 +6,23 @@
Чтобы получать загруженные файлы, сначала установите `python-multipart`.
-Например: `pip install python-multipart`.
+Убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его, а затем установили пакет, например:
-Это связано с тем, что загружаемые файлы передаются как данные формы.
+```console
+$ pip install python-multipart
+```
+
+Это связано с тем, что загружаемые файлы передаются как "данные формы".
///
-## Импорт `File`
+## Импорт `File` { #import-file }
Импортируйте `File` и `UploadFile` из модуля `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## Определите параметры `File`
+## Определите параметры `File` { #define-file-parameters }
Создайте параметры `File` так же, как вы это делаете для `Body` или `Form`:
@@ -46,7 +50,7 @@
Однако возможны случаи, когда использование `UploadFile` может оказаться полезным.
-## Загрузка файла с помощью `UploadFile`
+## Параметры файла с `UploadFile` { #file-parameters-with-uploadfile }
Определите параметр файла с типом `UploadFile`:
@@ -62,7 +66,7 @@
* Он реализует file-like `async` интерфейс.
* Он предоставляет реальный объект Python `SpooledTemporaryFile` который вы можете передать непосредственно другим библиотекам, которые ожидают файл в качестве объекта.
-### `UploadFile`
+### `UploadFile` { #uploadfile }
`UploadFile` имеет следующие атрибуты:
@@ -70,12 +74,12 @@
* `content_type`: Строка `str` с типом содержимого (MIME type / media type) (например, `image/jpeg`).
* `file`: `SpooledTemporaryFile` (a file-like объект). Это фактический файл Python, который можно передавать непосредственно другим функциям или библиотекам, ожидающим файл в качестве объекта.
-`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний SpooledTemporaryFile).
+`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний `SpooledTemporaryFile`).
* `write(data)`: Записать данные `data` (`str` или `bytes`) в файл.
* `read(size)`: Прочитать количество `size` (`int`) байт/символов из файла.
* `seek(offset)`: Перейти к байту на позиции `offset` (`int`) в файле.
- * Наример, `await myfile.seek(0)` перейдет к началу файла.
+ * Например, `await myfile.seek(0)` перейдет к началу файла.
* Это особенно удобно, если вы один раз выполнили команду `await myfile.read()`, а затем вам нужно прочитать содержимое файла еще раз.
* `close()`: Закрыть файл.
@@ -93,6 +97,7 @@ contents = await myfile.read()
contents = myfile.file.read()
```
+
/// note | Технические детали `async`
При использовании методов `async` **FastAPI** запускает файловые методы в пуле потоков и ожидает их.
@@ -105,7 +110,7 @@ contents = myfile.file.read()
///
-## Про данные формы ("Form Data")
+## Что такое «данные формы» { #what-is-form-data }
Способ, которым HTML-формы (``) отправляют данные на сервер, обычно использует "специальную" кодировку для этих данных, отличную от JSON.
@@ -117,7 +122,7 @@ contents = myfile.file.read()
Но когда форма включает файлы, она кодируется как multipart/form-data. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела.
-Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке MDN web docs for POST.
+Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке MDN web docs for POST.
///
@@ -129,19 +134,19 @@ contents = myfile.file.read()
///
-## Необязательная загрузка файлов
+## Необязательная загрузка файлов { #optional-file-upload }
Вы можете сделать загрузку файла необязательной, используя стандартные аннотации типов и установив значение по умолчанию `None`:
{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
-## `UploadFile` с дополнительными метаданными
+## `UploadFile` с дополнительными метаданными { #uploadfile-with-additional-metadata }
Вы также можете использовать `File()` вместе с `UploadFile`, например, для установки дополнительных метаданных:
{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
-## Загрузка нескольких файлов
+## Загрузка нескольких файлов { #multiple-file-uploads }
Можно одновременно загружать несколько файлов.
@@ -153,7 +158,7 @@ contents = myfile.file.read()
Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`.
-/// note | Technical Details
+/// note | Технические детали
Можно также использовать `from starlette.responses import HTMLResponse`.
@@ -161,12 +166,12 @@ contents = myfile.file.read()
///
-### Загрузка нескольких файлов с дополнительными метаданными
+### Загрузка нескольких файлов с дополнительными метаданными { #multiple-file-uploads-with-additional-metadata }
Так же, как и раньше, вы можете использовать `File()` для задания дополнительных параметров, даже для `UploadFile`:
{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
-## Резюме
+## Резюме { #recap }
Используйте `File`, `bytes` и `UploadFile` для работы с файлами, которые будут загружаться и передаваться в виде данных формы.
diff --git a/docs/ru/docs/tutorial/request-form-models.md b/docs/ru/docs/tutorial/request-form-models.md
index 1034ed27f..f8c58356c 100644
--- a/docs/ru/docs/tutorial/request-form-models.md
+++ b/docs/ru/docs/tutorial/request-form-models.md
@@ -1,6 +1,6 @@
-# Модели форм
+# Модели форм { #form-models }
-Вы можете использовать **Pydantic-модели** для объявления **полей форм** в FastAPI.
+Вы можете использовать **Pydantic-модели** для объявления **полей формы** в FastAPI.
/// info | Дополнительная информация
@@ -16,11 +16,11 @@ $ pip install python-multipart
/// note | Заметка
-Этот функционал доступен с версии `0.113.0`. 🤓
+Этот функционал доступен начиная с версии FastAPI `0.113.0`. 🤓
///
-## Pydantic-модель для формы
+## Pydantic-модели для форм { #pydantic-models-for-forms }
Вам просто нужно объявить **Pydantic-модель** с полями, которые вы хотите получить как **поля формы**, а затем объявить параметр как `Form`:
@@ -28,21 +28,21 @@ $ pip install python-multipart
**FastAPI** **извлечёт** данные для **каждого поля** из **данных формы** в запросе и выдаст вам объявленную Pydantic-модель.
-## Проверка сгенерированной документации
+## Проверьте документацию { #check-the-docs }
-Вы можете посмотреть поля формы в графическом интерфейсе Документации по пути `/docs`:
+Вы можете проверить это в интерфейсе документации по адресу `/docs`:
-И также обе модели будут использованы в интерактивной документации API:
+И обе модели будут использоваться в интерактивной документации API:
-## Другие аннотации типов
+## Другие аннотации возвращаемых типов { #other-return-type-annotations }
-Бывают случаи, когда вы возвращаете что-то, что не является валидным типом для Pydantic и вы указываете аннотацию ответа функции только для того, чтобы работала поддержка различных инструментов (редактор кода, mypy и др.).
+Бывают случаи, когда вы возвращаете что-то, что не является валидным полем Pydantic, и аннотируете это в функции только ради поддержки инструментов (редактор кода, mypy и т.д.).
-### Возвращаем Response
+### Возврат Response напрямую { #return-a-response-directly }
-Самый частый сценарий использования - это [возвращать Response напрямую, как описано в расширенной документации](../advanced/response-directly.md){.internal-link target=_blank}.
+Самый распространённый случай — [возвращать Response напрямую, как описано далее в разделах документации для продвинутых](../advanced/response-directly.md){.internal-link target=_blank}.
-{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *}
-Это поддерживается FastAPI по-умолчанию, т.к. аннотация проставлена в классе (или подклассе) `Response`.
+Этот простой случай обрабатывается FastAPI автоматически, потому что аннотация возвращаемого типа — это класс (или подкласс) `Response`.
-И ваши помощники разработки также будут счастливы, т.к. оба класса `RedirectResponse` и `JSONResponse` являются подклассами `Response`. Таким образом мы получаем корректную аннотацию типа.
+И инструменты тоже будут довольны, потому что и `RedirectResponse`, и `JSONResponse` являются подклассами `Response`, так что аннотация типа корректна.
-### Подкласс Response в аннотации типа
+### Аннотировать подкласс Response { #annotate-a-response-subclass }
-Вы также можете указать подкласс `Response` в аннотации типа:
+Вы также можете использовать подкласс `Response` в аннотации типа:
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *}
-Это сработает, потому что `RedirectResponse` является подклассом `Response` и FastAPI автоматически обработает этот простейший случай.
+Это тоже сработает, так как `RedirectResponse` — подкласс `Response`, и FastAPI автоматически обработает этот простой случай.
-### Некорректные аннотации типов
+### Некорректные аннотации возвращаемых типов { #invalid-return-type-annotations }
-Но когда вы возвращаете какой-либо другой произвольный объект, который не является допустимым типом Pydantic (например, объект из базы данных), и вы аннотируете его подобным образом для функции, FastAPI попытается создать из этого типа модель Pydantic и потерпит неудачу.
+Но когда вы возвращаете произвольный объект, не являющийся валидным типом Pydantic (например, объект базы данных), и аннотируете его таким образом в функции, FastAPI попытается создать модель ответа Pydantic из этой аннотации типа и потерпит неудачу.
-То же самое произошло бы, если бы у вас было что-то вроде Union различных типов и один или несколько из них не являлись бы допустимыми типами для Pydantic. Например, такой вариант приведет к ошибке 💥:
+То же произойдёт, если у вас будет что-то вроде union разных типов, где один или несколько не являются валидными типами Pydantic, например, это приведёт к ошибке 💥:
{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
-...такой код вызовет ошибку, потому что в аннотации указан неподдерживаемый Pydantic тип. А также этот тип не является классом или подклассом `Response`.
+...это не сработает, потому что аннотация типа не является типом Pydantic и это не единственный класс `Response` или его подкласс, а объединение (`union`) из `Response` и `dict`.
-### Возможно ли отключить генерацию модели ответа?
+### Отключить модель ответа { #disable-response-model }
-Продолжим рассматривать предыдущий пример. Допустим, что вы хотите отказаться от автоматической валидации ответа, документации, фильтрации и т.д.
+Продолжая пример выше, вы можете не хотеть использовать стандартные валидацию данных, документирование, фильтрацию и т.п., выполняемые FastAPI.
-Но в то же время, хотите сохранить аннотацию возвращаемого типа для функции, чтобы обеспечить работу помощников и анализаторов типов (например, mypy).
+Но при этом вы можете хотеть сохранить аннотацию возвращаемого типа в функции, чтобы пользоваться поддержкой инструментов вроде редакторов кода и инструментов проверки типов (например, mypy).
-В таком случае, вы можете отключить генерацию модели ответа, указав `response_model=None`:
+В этом случае вы можете отключить генерацию модели ответа, установив `response_model=None`:
{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
-Тогда FastAPI не станет генерировать модель ответа и вы сможете сохранить такую аннотацию типа, которая вам требуется, никак не влияя на работу FastAPI. 🤓
+Так FastAPI пропустит генерацию модели ответа, и вы сможете использовать любые аннотации возвращаемых типов, которые вам нужны, без влияния на ваше приложение FastAPI. 🤓
-## Параметры модели ответа
+## Параметры кодирования модели ответа { #response-model-encoding-parameters }
-Модель ответа может иметь значения по умолчанию, например:
+У вашей модели ответа могут быть значения по умолчанию, например:
{* ../../docs_src/response_model/tutorial004_py310.py hl[9,11:12] *}
-* `description: Union[str, None] = None` (или `str | None = None` в Python 3.10), где `None` является значением по умолчанию.
-* `tax: float = 10.5`, где `10.5` является значением по умолчанию.
-* `tags: List[str] = []`, где пустой список `[]` является значением по умолчанию.
+* `description: Union[str, None] = None` (или `str | None = None` в Python 3.10) имеет значение по умолчанию `None`.
+* `tax: float = 10.5` имеет значение по умолчанию `10.5`.
+* `tags: List[str] = []` имеет значение по умолчанию пустого списка: `[]`.
-но вы, возможно, хотели бы исключить их из ответа, если данные поля не были заданы явно.
+но вы можете захотеть опустить их в результате, если они фактически не были сохранены.
-Например, у вас есть модель с множеством необязательных полей в NoSQL базе данных, но вы не хотите отправлять в качестве ответа очень длинный JSON с множеством значений по умолчанию.
+Например, если у вас есть модели с множеством необязательных атрибутов в NoSQL-базе данных, но вы не хотите отправлять очень длинные JSON-ответы, заполненные значениями по умолчанию.
-### Используйте параметр `response_model_exclude_unset`
+### Используйте параметр `response_model_exclude_unset` { #use-the-response-model-exclude-unset-parameter }
-Установите для *декоратора операции пути* параметр `response_model_exclude_unset=True`:
+Вы можете установить у *декоратора операции пути* параметр `response_model_exclude_unset=True`:
{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
-и тогда значения по умолчанию не будут включены в ответ. В нем будут только те поля, значения которых фактически были установлены.
+и эти значения по умолчанию не будут включены в ответ — только те значения, которые действительно были установлены.
-Итак, если вы отправите запрос на данную *операцию пути* для элемента, с ID = `Foo` - ответ (с исключенными значениями по-умолчанию) будет таким:
+Итак, если вы отправите запрос к этой *операции пути* для элемента с ID `foo`, ответ (без значений по умолчанию) будет таким:
```JSON
{
@@ -242,24 +252,18 @@ FastAPI совместно с Pydantic выполнит некоторую ма
/// info | Информация
-"Под капотом" FastAPI использует метод `.dict()` у объектов моделей Pydantic с параметром `exclude_unset`, чтобы достичь такого эффекта.
-
-///
-
-/// info | Информация
-
Вы также можете использовать:
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
-как описано в документации Pydantic для параметров `exclude_defaults` и `exclude_none`.
+как описано в документации Pydantic для `exclude_defaults` и `exclude_none`.
///
-#### Если значение поля отличается от значения по-умолчанию
+#### Данные со значениями для полей, имеющих значения по умолчанию { #data-with-values-for-fields-with-defaults }
-Если для некоторых полей модели, имеющих значения по-умолчанию, значения были явно установлены - как для элемента с ID = `Bar`, ответ будет таким:
+Но если в ваших данных есть значения для полей модели, для которых указаны значения по умолчанию, как у элемента с ID `bar`:
```Python hl_lines="3 5"
{
@@ -270,11 +274,11 @@ FastAPI совместно с Pydantic выполнит некоторую ма
}
```
-они не будут исключены из ответа.
+они будут включены в ответ.
-#### Если значение поля совпадает с его значением по умолчанию
+#### Данные с такими же значениями, как значения по умолчанию { #data-with-the-same-values-as-the-defaults }
-Если данные содержат те же значения, которые являются для этих полей по умолчанию, но были установлены явно - как для элемента с ID = `baz`, ответ будет таким:
+Если данные имеют те же значения, что и значения по умолчанию, как у элемента с ID `baz`:
```Python hl_lines="3 5-6"
{
@@ -286,54 +290,54 @@ FastAPI совместно с Pydantic выполнит некоторую ма
}
```
-FastAPI достаточно умен (на самом деле, это заслуга Pydantic), чтобы понять, что, хотя `description`, `tax` и `tags` хранят такие же данные, какие должны быть по умолчанию - для них эти значения были установлены явно (а не получены из значений по умолчанию).
+FastAPI достаточно умен (на самом деле, это Pydantic), чтобы понять, что хотя `description`, `tax` и `tags` совпадают со значениями по умолчанию, они были установлены явно (а не взяты из значений по умолчанию).
-И поэтому, они также будут включены в JSON ответа.
+Поэтому они тоже будут включены в JSON-ответ.
-/// tip | Подсказка
+/// tip | Совет
-Значением по умолчанию может быть что угодно, не только `None`.
+Обратите внимание, что значения по умолчанию могут быть любыми, не только `None`.
-Им может быть и список (`[]`), значение 10.5 типа `float`, и т.п.
+Это может быть список (`[]`), число с плавающей точкой `10.5` и т.д.
///
-### `response_model_include` и `response_model_exclude`
+### `response_model_include` и `response_model_exclude` { #response-model-include-and-response-model-exclude }
-Вы также можете использовать параметры *декоратора операции пути*, такие, как `response_model_include` и `response_model_exclude`.
+Вы также можете использовать параметры *декоратора операции пути* `response_model_include` и `response_model_exclude`.
-Они принимают аргументы типа `set`, состоящий из строк (`str`) с названиями атрибутов, которые либо требуется включить в ответ (при этом исключив все остальные), либо наоборот исключить (оставив в ответе все остальные поля).
+Они принимают `set` из `str` с именами атрибутов, которые нужно включить (исключив остальные) или исключить (оставив остальные).
-Это можно использовать как быстрый способ исключить данные из ответа, не создавая отдельную модель Pydantic.
+Это можно использовать как быстрый способ, если у вас только одна Pydantic-модель и вы хотите убрать часть данных из ответа.
-/// tip | Подсказка
+/// tip | Совет
-Но по-прежнему рекомендуется следовать изложенным выше советам и использовать несколько моделей вместо данных параметров.
+Но всё же рекомендуется использовать подходы выше — несколько классов — вместо этих параметров.
-Потому как JSON схема OpenAPI, генерируемая вашим приложением (а также документация) все еще будет содержать все поля, даже если вы использовали `response_model_include` или `response_model_exclude` и исключили некоторые атрибуты.
+Потому что JSON Schema, генерируемая в OpenAPI вашего приложения (и документации), всё равно будет соответствовать полной модели, даже если вы используете `response_model_include` или `response_model_exclude`, чтобы опустить некоторые атрибуты.
-То же самое применимо к параметру `response_model_by_alias`.
+То же относится к `response_model_by_alias`, который работает аналогично.
///
{* ../../docs_src/response_model/tutorial005_py310.py hl[29,35] *}
-/// tip | Подсказка
+/// tip | Совет
-При помощи кода `{"name","description"}` создается объект множества (`set`) с двумя строковыми значениями.
+Синтаксис `{"name", "description"}` создаёт `set` с этими двумя значениями.
-Того же самого можно достичь используя `set(["name", "description"])`.
+Это эквивалентно `set(["name", "description"])`.
///
-#### Что если использовать `list` вместо `set`?
+#### Использование `list` вместо `set` { #using-lists-instead-of-sets }
-Если вы забыли про `set` и использовали структуру `list` или `tuple`, FastAPI автоматически преобразует этот объект в `set`, чтобы обеспечить корректную работу:
+Если вы забыли использовать `set` и применили `list` или `tuple` вместо него, FastAPI всё равно преобразует это в `set`, и всё будет работать корректно:
{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
-## Резюме
+## Резюме { #recap }
-Используйте параметр `response_model` у *декоратора операции пути* для того, чтобы задать модель ответа и в большей степени для того, чтобы быть уверенным, что приватная информация будет отфильтрована.
+Используйте параметр `response_model` у *декоратора операции пути*, чтобы задавать модели ответа, и особенно — чтобы приватные данные отфильтровывались.
-А также используйте `response_model_exclude_unset`, чтобы возвращать только те значения, которые были заданы явно.
+Используйте `response_model_exclude_unset`, чтобы возвращать только те значения, которые были установлены явно.
diff --git a/docs/ru/docs/tutorial/response-status-code.md b/docs/ru/docs/tutorial/response-status-code.md
index b46f656f3..30f642b64 100644
--- a/docs/ru/docs/tutorial/response-status-code.md
+++ b/docs/ru/docs/tutorial/response-status-code.md
@@ -1,6 +1,6 @@
-# HTTP коды статуса ответа
+# Статус-код ответа { #response-status-code }
-Вы можете задать HTTP код статуса ответа с помощью параметра `status_code` подобно тому, как вы определяете схему ответа в любой из *операций пути*:
+Подобно тому, как вы можете задать модель/схему ответа, вы можете объявить HTTP статус-код, используемый для ответа, с помощью параметра `status_code` в любой из *операций пути*:
* `@app.get()`
* `@app.post()`
@@ -8,15 +8,15 @@
* `@app.delete()`
* и других.
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
/// note | Примечание
-Обратите внимание, что `status_code` является атрибутом метода-декоратора (`get`, `post` и т.д.), а не *функции-обработчика пути* в отличие от всех остальных параметров и тела запроса.
+Обратите внимание, что `status_code` — это параметр метода-декоратора (`get`, `post` и т.д.), а не вашей *функции-обработчика пути*, в отличие от всех остальных параметров и тела запроса.
///
-Параметр `status_code` принимает число, обозначающее HTTP код статуса ответа.
+Параметр `status_code` принимает число, обозначающее HTTP статус-код.
/// info | Информация
@@ -27,7 +27,7 @@
Это позволит:
* Возвращать указанный код статуса в ответе.
-* Документировать его как код статуса ответа в OpenAPI схеме (а значит, и в пользовательском интерфейсе):
+* Документировать его как код статуса ответа в OpenAPI схеме (а значит, и в пользовательских интерфейсах):
@@ -39,11 +39,11 @@ FastAPI знает об этом и создаст документацию Open
///
-## Об HTTP кодах статуса ответа
+## Об HTTP статус-кодах { #about-http-status-codes }
/// note | Примечание
-Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу.
+Если вы уже знаете, что представляют собой HTTP статус-коды, можете перейти к следующему разделу.
///
@@ -51,30 +51,30 @@ FastAPI знает об этом и создаст документацию Open
У кодов статуса есть названия, чтобы упростить их распознавание, но важны именно числовые значения.
-Кратко о значениях кодов:
+Кратко:
-* `1XX` – статус-коды информационного типа. Они редко используются разработчиками напрямую. Ответы с этими кодами не могут иметь тела.
-* **`2XX`** – статус-коды, сообщающие об успешной обработке запроса. Они используются чаще всего.
+* `100 - 199` – статус-коды информационного типа. Они редко используются разработчиками напрямую. Ответы с этими кодами не могут иметь тела.
+* **`200 - 299`** – статус-коды, сообщающие об успешной обработке запроса. Они используются чаще всего.
* `200` – это код статуса ответа по умолчанию, который означает, что все прошло "OK".
* Другим примером может быть статус `201`, "Created". Он обычно используется после создания новой записи в базе данных.
- * Особый случай – `204`, "No Content". Этот статус ответа используется, когда нет содержимого для возврата клиенту, и поэтому ответ не должен иметь тела.
-* **`3XX`** – статус-коды, сообщающие о перенаправлениях. Ответы с этими кодами статуса могут иметь или не иметь тело, за исключением ответов со статусом `304`, "Not Modified", у которых не должно быть тела.
-* **`4XX`** – статус-коды, сообщающие о клиентской ошибке. Это ещё одна наиболее часто используемая категория.
+ * Особый случай – `204`, "No Content". Этот статус ответа используется, когда нет содержимого для возврата клиенту, и поэтому ответ не должен иметь тела.
+* **`300 - 399`** – статус-коды, сообщающие о перенаправлениях. Ответы с этими кодами статуса могут иметь или не иметь тело, за исключением ответов со статусом `304`, "Not Modified", у которых не должно быть тела.
+* **`400 - 499`** – статус-коды, сообщающие о клиентской ошибке. Это ещё одна наиболее часто используемая категория.
* Пример – код `404` для статуса "Not Found".
* Для общих ошибок со стороны клиента можно просто использовать код `400`.
-* `5XX` – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из 5XX кодов.
+* `500 - 599` – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из этих кодов статуса.
/// tip | Подсказка
-Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с документацией MDN об HTTP кодах статуса ответа.
+Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с MDN документацией об HTTP статус-кодах.
///
-## Краткие обозначения для запоминания названий кодов
+## Краткие обозначения для запоминания названий кодов { #shortcut-to-remember-the-names }
Рассмотрим предыдущий пример еще раз:
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
`201` – это код статуса "Создано".
@@ -82,9 +82,9 @@ FastAPI знает об этом и создаст документацию Open
Для удобства вы можете использовать переменные из `fastapi.status`.
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *}
-Они содержат те же числовые значения, но позволяют использовать подсказки редактора для выбора кода статуса:
+Они содержат те же числовые значения, но позволяют использовать автозавершение редактора кода для выбора кода статуса:
@@ -96,6 +96,6 @@ FastAPI знает об этом и создаст документацию Open
///
-## Изменение кода статуса по умолчанию
+## Изменение кода статуса по умолчанию { #changing-the-default }
-Позже, в [Руководстве для продвинутых пользователей](../advanced/response-change-status-code.md){.internal-link target=_blank}, вы узнаете, как возвращать HTTP коды статуса, отличные от используемого здесь кода статуса по умолчанию.
+Позже, в [Руководстве для продвинутых пользователей](../advanced/response-change-status-code.md){.internal-link target=_blank}, вы узнаете, как возвращать HTTP статус-код, отличный от значения по умолчанию, которое вы объявляете здесь.
diff --git a/docs/ru/docs/tutorial/schema-extra-example.md b/docs/ru/docs/tutorial/schema-extra-example.md
index f17b24349..e4a97c880 100644
--- a/docs/ru/docs/tutorial/schema-extra-example.md
+++ b/docs/ru/docs/tutorial/schema-extra-example.md
@@ -1,42 +1,48 @@
-# Объявление примера запроса данных
+# Объявление примеров данных запроса { #declare-request-example-data }
Вы можете объявлять примеры данных, которые ваше приложение может получать.
-Вот несколько способов, как это можно сделать.
+Вот несколько способов, как это сделать.
-## Pydantic `schema_extra`
+## Дополнительные данные JSON Schema в моделях Pydantic { #extra-json-schema-data-in-pydantic-models }
-Вы можете объявить ключ `example` для модели Pydantic, используя класс `Config` и переменную `schema_extra`, как описано в Pydantic документации: Настройка схемы:
+Вы можете объявить `examples` для модели Pydantic, которые будут добавлены в сгенерированную JSON Schema.
-{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:21] *}
+{* ../../docs_src/schema_extra_example/tutorial001_py310.py hl[13:24] *}
-Эта дополнительная информация будет включена в **JSON Schema** выходных данных для этой модели, и она будет использоваться в документации к API.
+Эта дополнительная информация будет добавлена как есть в выходную **JSON Schema** этой модели и будет использоваться в документации API.
+
+Вы можете использовать атрибут `model_config`, который принимает `dict`, как описано в Документации Pydantic: Конфигурация.
+
+Вы можете задать `"json_schema_extra"` с `dict`, содержащим любые дополнительные данные, которые вы хотите видеть в сгенерированной JSON Schema, включая `examples`.
/// tip | Подсказка
-Вы можете использовать тот же метод для расширения JSON-схемы и добавления своей собственной дополнительной информации.
+Вы можете использовать тот же приём, чтобы расширить JSON Schema и добавить свою собственную дополнительную информацию.
-Например, вы можете использовать это для добавления дополнительной информации для пользовательского интерфейса в вашем веб-приложении и т.д.
+Например, вы можете использовать это, чтобы добавить метаданные для фронтенд‑пользовательского интерфейса и т.д.
///
-## Дополнительные аргументы поля `Field`
+/// info | Информация
-При использовании `Field()` с моделями Pydantic, вы также можете объявлять дополнительную информацию для **JSON Schema**, передавая любые другие произвольные аргументы в функцию.
+OpenAPI 3.1.0 (используется начиная с FastAPI 0.99.0) добавил поддержку `examples`, который является частью стандарта **JSON Schema**.
-Вы можете использовать это, чтобы добавить аргумент `example` для каждого поля:
+До этого поддерживалось только ключевое слово `example` с одним примером. Оно всё ещё поддерживается в OpenAPI 3.1.0, но помечено как устаревшее и не является частью стандарта JSON Schema. Поэтому рекомендуется мигрировать `example` на `examples`. 🤓
-{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
+Подробнее — в конце этой страницы.
-/// warning | Внимание
+///
-Имейте в виду, что эти дополнительные переданные аргументы не добавляют никакой валидации, только дополнительную информацию для документации.
+## Дополнительные аргументы `Field` { #field-additional-arguments }
-///
+При использовании `Field()` с моделями Pydantic вы также можете объявлять дополнительные `examples`:
+
+{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
-## Использование `example` и `examples` в OpenAPI
+## `examples` в JSON Schema — OpenAPI { #examples-in-json-schema-openapi }
-При использовании любой из этих функций:
+При использовании любой из функций:
* `Path()`
* `Query()`
@@ -46,65 +52,151 @@
* `Form()`
* `File()`
-вы также можете добавить аргумент, содержащий `example` или группу `examples` с дополнительной информацией, которая будет добавлена в **OpenAPI**.
+вы также можете объявить набор `examples` с дополнительной информацией, которая будет добавлена в их **JSON Schema** внутри **OpenAPI**.
-### Параметр `Body` с аргументом `example`
+### `Body` с `examples` { #body-with-examples }
-Здесь мы передаём аргумент `example`, как пример данных ожидаемых в параметре `Body()`:
+Здесь мы передаём `examples`, содержащий один пример данных, ожидаемых в `Body()`:
-{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:27] *}
+{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
-### Аргумент "example" в UI документации
+### Пример в UI документации { #example-in-the-docs-ui }
-С любым из вышеуказанных методов это будет выглядеть так в `/docs`:
+С любым из перечисленных выше методов это будет выглядеть так в `/docs`:
-### `Body` с аргументом `examples`
+### `Body` с несколькими `examples` { #body-with-multiple-examples }
+
+Конечно, вы можете передать и несколько `examples`:
+
+{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
+
+Когда вы делаете это, примеры становятся частью внутренней **JSON Schema** для данных тела запроса.
+
+Тем не менее, на момент написания этого Swagger UI, инструмент, отвечающий за отображение UI документации, не поддерживает показ нескольких примеров для данных в **JSON Schema**. Но ниже есть обходной путь.
+
+### Специфические для OpenAPI `examples` { #openapi-specific-examples }
+
+Ещё до того как **JSON Schema** поддержала `examples`, в OpenAPI была поддержка другого поля, также называемого `examples`.
+
+Эти **специфические для OpenAPI** `examples` находятся в другой секции спецификации OpenAPI. Они находятся в **подробностях для каждой операции пути (обработчика пути)**, а не внутри каждого объекта Schema.
+
+И Swagger UI уже какое‑то время поддерживает именно это поле `examples`. Поэтому вы можете использовать его, чтобы **отобразить** разные **примеры в UI документации**.
+
+Структура этого специфичного для OpenAPI поля `examples` — это `dict` с **несколькими примерами** (вместо `list`), каждый с дополнительной информацией, которая также будет добавлена в **OpenAPI**.
+
+Это не помещается внутрь каждого объекта Schema в OpenAPI, это находится снаружи, непосредственно на уровне самой *операции пути*.
+
+### Использование параметра `openapi_examples` { #using-the-openapi-examples-parameter }
+
+Вы можете объявлять специфические для OpenAPI `examples` в FastAPI с помощью параметра `openapi_examples` для:
+
+* `Path()`
+* `Query()`
+* `Header()`
+* `Cookie()`
+* `Body()`
+* `Form()`
+* `File()`
-В качестве альтернативы одному аргументу `example`, вы можете передавать `examples` используя тип данных `dict` с **несколькими примерами**, каждый из которых содержит дополнительную информацию, которая также будет добавлена в **OpenAPI**.
+Ключи `dict` идентифицируют каждый пример, а каждое значение — это ещё один `dict`.
-Ключи `dict` указывают на каждый пример, а значения для каждого из них - на еще один тип `dict` с дополнительной информацией.
+Каждый конкретный пример `dict` в `examples` может содержать:
-Каждый конкретный пример типа `dict` в аргументе `examples` может содержать:
+* `summary`: Краткое описание примера.
+* `description`: Подробное описание, которое может содержать текст в Markdown.
+* `value`: Это фактический пример, который отображается, например, `dict`.
+* `externalValue`: альтернатива `value`, URL, указывающий на пример. Хотя это может поддерживаться не так многими инструментами, как `value`.
-* `summary`: Краткое описание для примера.
-* `description`: Полное описание, которое может содержать текст в формате Markdown.
-* `value`: Это конкретный пример, который отображается, например, в виде типа `dict`.
-* `externalValue`: альтернатива параметру `value`, URL-адрес, указывающий на пример. Хотя это может не поддерживаться таким же количеством инструментов разработки и тестирования API, как параметр `value`.
+Использовать это можно так:
-{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:49] *}
+{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
-### Аргумент "examples" в UI документации
+### OpenAPI-примеры в UI документации { #openapi-examples-in-the-docs-ui }
-С аргументом `examples`, добавленным в `Body()`, страница документации `/docs` будет выглядеть так:
+С `openapi_examples`, добавленным в `Body()`, страница `/docs` будет выглядеть так:
-## Технические Детали
+## Технические детали { #technical-details }
+
+/// tip | Подсказка
+
+Если вы уже используете **FastAPI** версии **0.99.0 или выше**, вы, вероятно, можете **пропустить** эти подробности.
+
+Они более актуальны для старых версий, до того как стала доступна OpenAPI 3.1.0.
+
+Считайте это кратким **уроком истории** про OpenAPI и JSON Schema. 🤓
+
+///
/// warning | Внимание
-Эти технические детали относятся к стандартам **JSON Schema** и **OpenAPI**.
+Далее идут очень технические подробности о стандартах **JSON Schema** и **OpenAPI**.
-Если предложенные выше идеи уже работают для вас, возможно этого будет достаточно и эти детали вам не потребуются, можете спокойно их пропустить.
+Если идеи выше уже работают для вас, этого может быть достаточно, и, вероятно, вам не нужны эти детали — смело пропускайте их.
///
-Когда вы добавляете пример внутрь модели Pydantic, используя `schema_extra` или `Field(example="something")`, этот пример добавляется в **JSON Schema** для данной модели Pydantic.
+До OpenAPI 3.1.0 OpenAPI использовала более старую и модифицированную версию **JSON Schema**.
+
+В JSON Schema не было `examples`, поэтому OpenAPI добавила собственное поле `example` в свою модифицированную версию.
+
+OpenAPI также добавила поля `example` и `examples` в другие части спецификации:
+
+* `Parameter Object` (в спецификации), которое использовалось в FastAPI:
+ * `Path()`
+ * `Query()`
+ * `Header()`
+ * `Cookie()`
+* `Request Body Object`, в поле `content`, в `Media Type Object` (в спецификации), которое использовалось в FastAPI:
+ * `Body()`
+ * `File()`
+ * `Form()`
+
+/// info | Информация
+
+Этот старый специфичный для OpenAPI параметр `examples` теперь называется `openapi_examples`, начиная с FastAPI `0.103.0`.
+
+///
+
+### Поле `examples` в JSON Schema { #json-schemas-examples-field }
+
+Позже в новой версии спецификации JSON Schema было добавлено поле `examples`.
+
+А затем новый OpenAPI 3.1.0 был основан на последней версии (JSON Schema 2020-12), которая включала это новое поле `examples`.
+
+И теперь это новое поле `examples` имеет приоритет над старым одиночным (и кастомным) полем `example`, которое теперь устарело.
+
+Это новое поле `examples` в JSON Schema — это **просто `list`** примеров, а не dict с дополнительными метаданными, как в других местах OpenAPI (описанных выше).
+
+/// info | Информация
+
+Даже после того как OpenAPI 3.1.0 была выпущена с этой новой, более простой интеграцией с JSON Schema, какое‑то время Swagger UI, инструмент, предоставляющий автоматическую документацию, не поддерживал OpenAPI 3.1.0 (поддержка появилась начиная с версии 5.0.0 🎉).
+
+Из‑за этого версии FastAPI до 0.99.0 всё ещё использовали версии OpenAPI ниже 3.1.0.
+
+///
+
+### `examples` в Pydantic и FastAPI { #pydantic-and-fastapi-examples }
+
+Когда вы добавляете `examples` внутри модели Pydantic, используя `schema_extra` или `Field(examples=["something"])`, этот пример добавляется в **JSON Schema** для этой модели Pydantic.
И эта **JSON Schema** модели Pydantic включается в **OpenAPI** вашего API, а затем используется в UI документации.
-Поля `example` как такового не существует в стандартах **JSON Schema**. В последних версиях JSON-схемы определено поле `examples`, но OpenAPI 3.0.3 основан на более старой версии JSON-схемы, которая не имела поля `examples`.
+В версиях FastAPI до 0.99.0 (0.99.0 и выше используют новый OpenAPI 3.1.0), когда вы использовали `example` или `examples` с любыми другими утилитами (`Query()`, `Body()`, и т.д.), эти примеры не добавлялись в JSON Schema, описывающую эти данные (даже в собственную версию JSON Schema OpenAPI), они добавлялись непосредственно в объявление *операции пути* в OpenAPI (вне частей OpenAPI, использующих JSON Schema).
+
+Но теперь, когда FastAPI 0.99.0 и выше используют OpenAPI 3.1.0, который использует JSON Schema 2020-12, а также Swagger UI 5.0.0 и выше, всё стало более последовательным, и примеры включаются в JSON Schema.
-Таким образом, OpenAPI 3.0.3 определяет своё собственное поле `example` для модифицированной версии **JSON Schema**, которую он использует чтобы достичь той же цели (однако это именно поле `example`, а не `examples`), и именно это используется API в UI документации (с интеграцией Swagger UI).
+### Swagger UI и специфичные для OpenAPI `examples` { #swagger-ui-and-openapi-specific-examples }
-Итак, хотя поле `example` не является частью JSON-схемы, оно является частью настраиваемой версии JSON-схемы в OpenAPI, и именно это поле будет использоваться в UI документации.
+Теперь, поскольку Swagger UI не поддерживал несколько примеров JSON Schema (по состоянию на 2023-08-26), у пользователей не было способа показать несколько примеров в документации.
-Однако, когда вы используете поле `example` или `examples` с любой другой функцией (`Query()`, `Body()`, и т.д.), эти примеры не добавляются в JSON-схему, которая описывает эти данные (даже в собственную версию JSON-схемы OpenAPI), они добавляются непосредственно в объявление *операции пути* в OpenAPI (вне частей OpenAPI, которые используют JSON-схему).
+Чтобы решить это, FastAPI `0.103.0` **добавил поддержку** объявления того же старого, **специфичного для OpenAPI**, поля `examples` с новым параметром `openapi_examples`. 🤓
-Для функций `Path()`, `Query()`, `Header()`, и `Cookie()`, аргументы `example` или `examples` добавляются в определение OpenAPI, к объекту `Parameter Object` (в спецификации).
+### Итог { #summary }
-И для функций `Body()`, `File()` и `Form()` аргументы `example` или `examples` аналогично добавляются в определение OpenAPI, к объекту `Request Body Object`, в поле `content` в объекте `Media Type Object` (в спецификации).
+Раньше я говорил, что не очень люблю историю... а теперь вот рассказываю «уроки технической истории». 😅
-С другой стороны, существует более новая версия OpenAPI: **3.1.0**, недавно выпущенная. Она основана на последней версии JSON-схемы и большинство модификаций из OpenAPI JSON-схемы удалены в обмен на новые возможности из последней версии JSON-схемы, так что все эти мелкие отличия устранены. Тем не менее, Swagger UI в настоящее время не поддерживает OpenAPI 3.1.0, поэтому пока лучше продолжать использовать вышеупомянутые методы.
+Коротко: **обновитесь до FastAPI 0.99.0 или выше** — так всё будет значительно **проще, последовательнее и интуитивнее**, и вам не придётся знать все эти исторические подробности. 😎
diff --git a/docs/ru/docs/tutorial/security/first-steps.md b/docs/ru/docs/tutorial/security/first-steps.md
index 375c2d7f6..983e85e66 100644
--- a/docs/ru/docs/tutorial/security/first-steps.md
+++ b/docs/ru/docs/tutorial/security/first-steps.md
@@ -1,52 +1,58 @@
-# Безопасность - первые шаги
+# Безопасность — первые шаги { #security-first-steps }
-Представим, что у вас есть свой **бэкенд** API на некотором домене.
+Представим, что у вас есть **бэкенд** API на некотором домене.
И у вас есть **фронтенд** на другом домене или на другом пути того же домена (или в мобильном приложении).
-И вы хотите иметь возможность аутентификации фронтенда с бэкендом, используя **имя пользователя** и **пароль**.
+И вы хотите, чтобы фронтенд мог аутентифицироваться на бэкенде, используя **имя пользователя** и **пароль**.
-Мы можем использовать **OAuth2** для создания такой системы с помощью **FastAPI**.
+Мы можем использовать **OAuth2**, чтобы построить это с **FastAPI**.
-Но давайте избавим вас от необходимости читать всю длинную спецификацию, чтобы найти те небольшие кусочки информации, которые вам нужны.
+Но давайте сэкономим вам время на чтение всей длинной спецификации в поисках тех небольших фрагментов информации, которые вам нужны.
-Для работы с безопасностью воспользуемся средствами, предоставленными **FastAPI**.
+Воспользуемся инструментами, предоставленными **FastAPI**, чтобы работать с безопасностью.
-## Как это выглядит
+## Как это выглядит { #how-it-looks }
-Давайте сначала просто воспользуемся кодом и посмотрим, как он работает, а затем детально разберём, что происходит.
+Сначала просто воспользуемся кодом и посмотрим, как он работает, а затем вернемся и разберемся, что происходит.
-## Создание `main.py`
+## Создание `main.py` { #create-main-py }
Скопируйте пример в файл `main.py`:
{* ../../docs_src/security/tutorial001_an_py39.py *}
-## Запуск
+## Запуск { #run-it }
/// info | Дополнительная информация
-Вначале, установите библиотеку `python-multipart`.
+Пакет `python-multipart` автоматически устанавливается вместе с **FastAPI**, если вы запускаете команду `pip install "fastapi[standard]"`.
-А именно: `pip install python-multipart`.
+Однако, если вы используете команду `pip install fastapi`, пакет `python-multipart` по умолчанию не включается.
-Это связано с тем, что **OAuth2** использует "данные формы" для передачи `имени пользователя` и `пароля`.
+Чтобы установить его вручную, убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активировали его и затем установили пакет:
+
+```console
+$ pip install python-multipart
+```
+
+Это связано с тем, что **OAuth2** использует «данные формы» для отправки `username` и `password`.
///
-Запустите ваш сервер:
+Запустите пример командой:
-/// note | Технические детали
+/// note | Примечание
-Неважно, что вы введете в форму, она пока не будет работать. Но мы к этому еще придем.
+Неважно, что вы введете в форму — пока это не будет работать. Но мы скоро до этого дойдем.
///
-Конечно, это не фронтенд для конечных пользователей, но это отличный автоматический инструмент для интерактивного документирования всех ваших API.
+Конечно, это не фронтенд для конечных пользователей, но это отличный автоматический инструмент для интерактивного документирования всего вашего API.
-Он может использоваться командой фронтенда (которой можете быть и вы сами).
+Им может пользоваться команда фронтенда (которой можете быть и вы сами).
-Он может быть использован сторонними приложениями и системами.
+Им могут пользоваться сторонние приложения и системы.
-Кроме того, его можно использовать самостоятельно для отладки, проверки и тестирования одного и того же приложения.
+И им также можете пользоваться вы сами, чтобы отлаживать, проверять и тестировать то же самое приложение.
-## Аутентификация по паролю
+## «`password` flow» (аутентификация по паролю) { #the-password-flow }
-Теперь давайте вернемся немного назад и разберемся, что же это такое.
+Теперь давайте немного вернемся и разберемся, что это все такое.
-Аутентификация по паролю является одним из способов, определенных в OAuth2, для обеспечения безопасности и аутентификации.
+«`password` flow» — это один из способов («flows»), определенных в OAuth2, для обеспечения безопасности и аутентификации.
-OAuth2 был разработан для того, чтобы бэкэнд или API были независимы от сервера, который аутентифицирует пользователя.
+OAuth2 был спроектирован так, чтобы бэкенд или API были независимы от сервера, который аутентифицирует пользователя.
-Но в нашем случае одно и то же приложение **FastAPI** будет работать с API и аутентификацией.
+Но в нашем случае одно и то же приложение **FastAPI** будет работать и с API, и с аутентификацией.
-Итак, рассмотрим его с этой упрощенной точки зрения:
+Итак, рассмотрим это с упрощенной точки зрения:
-* Пользователь вводит на фронтенде `имя пользователя` и `пароль` и нажимает `Enter`.
-* Фронтенд (работающий в браузере пользователя) отправляет эти `имя пользователя` и `пароль` на определенный URL в нашем API (объявленный с помощью параметра `tokenUrl="token"`).
-* API проверяет эти `имя пользователя` и `пароль` и выдает в ответ "токен" (мы еще не реализовали ничего из этого).
- * "Токен" - это просто строка с некоторым содержимым, которое мы можем использовать позже для верификации пользователя.
- * Обычно срок действия токена истекает через некоторое время.
- * Таким образом, пользователю придется снова войти в систему в какой-то момент времени.
- * И если токен будет украден, то риск будет меньше, так как он не похож на постоянный ключ, который будет работать вечно (в большинстве случаев).
-* Фронтенд временно хранит этот токен в каком-то месте.
-* Пользователь щелкает мышью на фронтенде, чтобы перейти в другой раздел на фронтенде.
-* Фронтенду необходимо получить дополнительные данные из API.
- * Но для этого необходима аутентификация для конкретной конечной точки.
- * Поэтому для аутентификации в нашем API он посылает заголовок `Authorization` со значением `Bearer` плюс сам токен.
- * Если токен содержит `foobar`, то содержание заголовка `Authorization` будет таким: `Bearer foobar`.
+* Пользователь вводит на фронтенде `username` и `password` и нажимает `Enter`.
+* Фронтенд (работающий в браузере пользователя) отправляет эти `username` и `password` на конкретный URL в нашем API (объявленный с `tokenUrl="token"`).
+* API проверяет этот `username` и `password` и отвечает «токеном» (мы еще ничего из этого не реализовали).
+ * «Токен» — это просто строка с некоторым содержимым, которое мы сможем позже использовать для проверки этого пользователя.
+ * Обычно у токена установлен срок действия: он истекает через некоторое время.
+ * Поэтому пользователю придется снова войти в систему в какой‑то момент.
+ * И если токен украдут, риск меньше: это не постоянный ключ, который будет работать вечно (в большинстве случаев).
+* Фронтенд временно где‑то хранит этот токен.
+* Пользователь кликает во фронтенде, чтобы перейти в другой раздел веб‑приложения.
+* Фронтенду нужно получить дополнительные данные из API.
+ * Но для этого для конкретной конечной точки нужна аутентификация.
+ * Поэтому, чтобы аутентифицироваться в нашем API, он отправляет HTTP-заголовок `Authorization` со значением `Bearer ` плюс сам токен.
+ * Если токен содержит `foobar`, то содержимое заголовка `Authorization` будет: `Bearer foobar`.
-## Класс `OAuth2PasswordBearer` в **FastAPI**
+## Класс `OAuth2PasswordBearer` в **FastAPI** { #fastapis-oauth2passwordbearer }
**FastAPI** предоставляет несколько средств на разных уровнях абстракции для реализации этих функций безопасности.
-В данном примере мы будем использовать **OAuth2**, с аутентификацией по паролю, используя токен **Bearer**. Для этого мы используем класс `OAuth2PasswordBearer`.
+В этом примере мы будем использовать **OAuth2**, с потоком **Password**, используя токен **Bearer**. Для этого мы используем класс `OAuth2PasswordBearer`.
/// info | Дополнительная информация
-Токен "bearer" - не единственный вариант, но для нашего случая он является наилучшим.
+Токен «bearer» — не единственный вариант.
+
+Но для нашего случая он — лучший.
-И это может быть лучшим вариантом для большинства случаев использования, если только вы не являетесь экспертом в области OAuth2 и точно знаете, почему вам лучше подходит какой-то другой вариант.
+И он может быть лучшим для большинства случаев использования, если только вы не являетесь экспертом по OAuth2 и точно знаете, почему другой вариант лучше подходит под ваши нужды.
-В этом случае **FastAPI** также предоставляет инструменты для его реализации.
+В этом случае **FastAPI** также предоставляет инструменты, чтобы его реализовать.
///
-При создании экземпляра класса `OAuth2PasswordBearer` мы передаем в него параметр `tokenUrl`. Этот параметр содержит URL, который клиент (фронтенд, работающий в браузере пользователя) будет использовать для отправки `имени пользователя` и `пароля` с целью получения токена.
+При создании экземпляра класса `OAuth2PasswordBearer` мы передаем параметр `tokenUrl`. Этот параметр содержит URL, который клиент (фронтенд, работающий в браузере пользователя) будет использовать для отправки `username` и `password`, чтобы получить токен.
{* ../../docs_src/security/tutorial001_an_py39.py hl[8] *}
@@ -130,27 +138,27 @@ OAuth2 был разработан для того, чтобы бэкэнд ил
Здесь `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.
+Этот параметр не создает конечную точку / *операцию пути*, а объявляет, что URL `/token` — это тот, который клиент должен использовать для получения токена. Эта информация используется в OpenAPI, а затем в интерактивных системах документации по API.
-Вскоре мы создадим и саму операцию пути.
+Скоро мы также создадим и саму операцию пути.
/// info | Дополнительная информация
-Если вы очень строгий "питонист", то вам может не понравиться стиль названия параметра `tokenUrl` вместо `token_url`.
+Если вы очень строгий «питонист», вам может не понравиться стиль имени параметра `tokenUrl` вместо `token_url`.
-Это связано с тем, что тут используется то же имя, что и в спецификации OpenAPI. Таким образом, если вам необходимо более подробно изучить какую-либо из этих схем безопасности, вы можете просто использовать копирование/вставку, чтобы найти дополнительную информацию о ней.
+Это потому, что используется то же имя, что и в спецификации OpenAPI. Так, если вам нужно разобраться подробнее в какой‑то из этих схем безопасности, вы можете просто скопировать и вставить это имя, чтобы найти больше информации.
///
-Переменная `oauth2_scheme` является экземпляром `OAuth2PasswordBearer`, но она также является "вызываемой".
+Переменная `oauth2_scheme` — это экземпляр `OAuth2PasswordBearer`, но она также «вызываемая».
-Ее можно вызвать следующим образом:
+Ее можно вызвать так:
```Python
oauth2_scheme(some, parameters)
@@ -158,38 +166,38 @@ oauth2_scheme(some, parameters)
Поэтому ее можно использовать вместе с `Depends`.
-### Использование
+### Использование { #use-it }
-Теперь вы можете передать ваш `oauth2_scheme` в зависимость с помощью `Depends`.
+Теперь вы можете передать `oauth2_scheme` как зависимость с `Depends`.
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
-Эта зависимость будет предоставлять `строку`, которая присваивается параметру `token` в *функции операции пути*.
+Эта зависимость предоставит `str`, который будет присвоен параметру `token` *функции-обработчика пути*.
-**FastAPI** будет знать, что он может использовать эту зависимость для определения "схемы безопасности" в схеме OpenAPI (и автоматической документации по API).
+**FastAPI** будет знать, что может использовать эту зависимость для определения «схемы безопасности» в схеме OpenAPI (и в автоматической документации по API).
/// 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.
///
-## Что он делает
+## Что он делает { #what-it-does }
-Он будет искать в запросе заголовок `Authorization` и проверять, содержит ли он значение `Bearer` с некоторым токеном, и возвращать токен в виде `строки`.
+Он будет искать в запросе заголовок `Authorization`, проверять, что его значение — это `Bearer ` плюс некоторый токен, и вернет токен как `str`.
-Если он не видит заголовка `Authorization` или значение не имеет токена `Bearer`, то в ответ будет выдана ошибка с кодом состояния 401 (`UNAUTHORIZED`).
+Если заголовок `Authorization` отсутствует или его значение не содержит токен `Bearer `, он сразу ответит ошибкой со статус-кодом 401 (`UNAUTHORIZED`).
-Для возврата ошибки даже не нужно проверять, существует ли токен. Вы можете быть уверены, что если ваша функция была выполнена, то в этом токене есть `строка`.
+Вам даже не нужно проверять наличие токена, чтобы вернуть ошибку. Вы можете быть уверены: если ваша функция была выполнена, в этом токене будет `str`.
-Проверить это можно уже сейчас в интерактивной документации:
+Это уже можно попробовать в интерактивной документации:
-Мы пока не проверяем валидность токена, но для начала неплохо.
+Мы пока не проверяем валидность токена, но для начала это уже неплохо.
-## Резюме
+## Резюме { #recap }
-Таким образом, всего за 3-4 дополнительные строки вы получаете некую примитивную форму защиты.
+Таким образом, всего за 3–4 дополнительные строки у вас уже есть некая примитивная форма защиты.
diff --git a/docs/ru/docs/tutorial/security/get-current-user.md b/docs/ru/docs/tutorial/security/get-current-user.md
index 05eb290d7..c6bc07cc1 100644
--- a/docs/ru/docs/tutorial/security/get-current-user.md
+++ b/docs/ru/docs/tutorial/security/get-current-user.md
@@ -1,99 +1,105 @@
-# Данные текущего пользователя
+# Получить текущего пользователя { #get-current-user }
-В предыдущей главе система безопасности (основанная на системе внедрения зависимостей) передавала *функции, обрабатывающей эндпоинт,* `токен` в виде `строки`:
+В предыдущей главе система безопасности (основанная на системе внедрения зависимостей) передавала *функции-обработчику пути* `token` типа `str`:
{* ../../docs_src/security/tutorial001_an_py39.py hl[12] *}
-Это пока что не слишком нам полезно. Давайте изменим код так, чтобы он возвращал нам данные пользователя, отправившего запрос.
+Но это всё ещё не слишком полезно.
-## Создание модели пользователя
+Сделаем так, чтобы она возвращала текущего пользователя.
+
+## Создать модель пользователя { #create-a-user-model }
Сначала создадим Pydantic-модель пользователя.
-Точно так же, как мы использовали Pydantic для объявления тел запросов, мы можем использовать его где угодно:
+Точно так же, как мы используем Pydantic для объявления тел запросов, мы можем использовать его где угодно:
{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
-## Создание зависимости `get_current_user`
+## Создать зависимость `get_current_user` { #create-a-get-current-user-dependency }
Давайте создадим зависимость `get_current_user`.
Помните, что у зависимостей могут быть подзависимости?
-`get_current_user` как раз будет иметь подзависимость `oauth2_scheme`, которую мы создали ранее.
+`get_current_user` будет иметь зависимость от того же `oauth2_scheme`, который мы создали ранее.
-Аналогично тому, как мы делали это ранее в *обработчике эндпоинта* наша новая зависимость `get_current_user` будет получать `token` в виде `строки` от подзависимости `oauth2_scheme`:
+Аналогично тому, как мы делали ранее прямо в *операции пути*, новая зависимость `get_current_user` получит `token` типа `str` от подзависимости `oauth2_scheme`:
{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
-## Получение данных пользователя
+## Получить пользователя { #get-the-user }
-`get_current_user` будет использовать созданную нами (ненастоящую) служебную функцию, которая принимает токен в виде `строки` и возвращает нашу Pydantic-модель `User`:
+`get_current_user` будет использовать созданную нами (ненастоящую) служебную функцию, которая принимает токен типа `str` и возвращает нашу Pydantic-модель `User`:
{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
-## Внедрение зависимости текущего пользователя
+## Внедрить текущего пользователя { #inject-the-current-user }
-Теперь мы можем использовать тот же `Depends` с нашей зависимостью `get_current_user` в *функции обрабатывающей эндпоинт*:
+Теперь мы можем использовать тот же `Depends` с нашей `get_current_user` в *операции пути*:
{* ../../docs_src/security/tutorial002_an_py310.py hl[31] *}
-Обратите внимание, что мы объявляем тип переменной `current_user` как Pydantic-модель `User`.
+Обратите внимание, что мы объявляем тип `current_user` как Pydantic-модель `User`.
-Это поможет выполнить внутри функции все проверки автозаполнения и типа.
+Это поможет внутри функции с автозавершением и проверками типов.
/// tip | Подсказка
-Возможно, вы помните, что тело запроса также объявляется с помощью Pydantic-моделей.
-В этом месте у **FastAPI** не возникнет проблем, потому что вы используете `Depends`.
+Возможно, вы помните, что тела запросов также объявляются с помощью Pydantic-моделей.
+
+Здесь **FastAPI** не запутается, потому что вы используете `Depends`.
+
///
/// check | Заметка
-То, как устроена эта система зависимостей, позволяет нам иметь различные зависимости, которые возвращают модель `User`.
-Мы не ограничены наличием только одной зависимости, которая может возвращать данные такого типа.
+То, как устроена эта система зависимостей, позволяет иметь разные зависимости, которые возвращают модель `User`.
+
+Мы не ограничены наличием только одной зависимости, которая может возвращать такой тип данных.
+
///
-## Другие модели
+## Другие модели { #other-models }
-Теперь вы можете получать информацию о текущем пользователе непосредственно в *функции обрабатывающей эндпоинт* и работать с механизмами безопасности на уровне **Внедрения Зависимостей**, используя `Depends`.
+Теперь вы можете получать текущего пользователя напрямую в *функциях-обработчиках пути* и работать с механизмами безопасности на уровне **внедрения зависимостей**, используя `Depends`.
-Причем для обеспечения требований безопасности можно использовать любую модель или данные (в данном случае - Pydantic-модель `User`).
+И вы можете использовать любую модель или данные для требований безопасности (в данном случае Pydantic-модель `User`).
-Но вы не ограничены использованием какой-то конкретной моделью данных, классом или типом.
+Но вы не ограничены использованием какой-то конкретной модели данных, класса или типа.
-Вы хотите использовать в модели `id` и `email`, а `username` вам не нужен? Ну разумеется. Воспользуйтесь тем же инструментарием.
+Хотите, чтобы в модели были `id` и `email`, но не было `username`? Пожалуйста. Можно использовать те же инструменты.
-Вам нужны только `строки`? Или только `словари`? Или непосредственно экземпляр модели класса базы данных? Все это работает точно также.
+Хотите просто `str`? Или просто `dict`? Или напрямую экземпляр класса модели базы данных? Всё работает одинаково.
-У вас нет пользователей, которые входят в ваше приложение, а только роботы, боты или другие системы, у которых есть только токен доступа? Опять же, все работает одинаково.
+У вас вообще нет пользователей, которые входят в приложение, а есть роботы, боты или другие системы, у которых есть только токен доступа? Снова — всё работает так же.
-Просто используйте любую модель, любой класс, любую базу данных, которые нужны для вашего приложения. Система внедрения зависимостей **FastAPI** поможет вам в этом.
+Просто используйте любую модель, любой класс, любую базу данных, которые нужны вашему приложению. Система внедрения зависимостей **FastAPI** поможет вам в этом.
-## Размер кода
+## Размер кода { #code-size }
-Этот пример может показаться многословным. Следует иметь в виду, что в одном файле мы смешиваем безопасность, модели данных, служебные функции и *эндпоинты*.
+Этот пример может показаться многословным. Имейте в виду, что в одном файле мы смешиваем безопасность, модели данных, служебные функции и *операции пути*.
-Но вот ключевой момент:
+Но вот ключевой момент.
-Все, что касается безопасности и внедрения зависимостей, пишется один раз.
+Всё, что касается безопасности и внедрения зависимостей, пишется один раз.
-И вы можете сделать его настолько сложным, насколько захотите. И все это будет написано только один раз, в одном месте, со всей своей гибкостью.
+И вы можете сделать это настолько сложным, насколько захотите. И всё равно это будет написано только один раз, в одном месте. Со всей гибкостью.
-И у вас могут быть тысячи конечных точек (*эндпоинтов*), использующих одну и ту же систему безопасности.
+При этом у вас могут быть тысячи эндпоинтов (*операций пути*), использующих одну и ту же систему безопасности.
И все они (или любая их часть по вашему желанию) могут воспользоваться преимуществами повторного использования этих зависимостей или любых других зависимостей, которые вы создадите.
-И все эти тысячи *эндпоинтов* могут составлять всего 3 строки:
+И все эти тысячи *операций пути* могут состоять всего из 3 строк:
{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
-## Резюме
+## Резюме { #recap }
-Теперь вы можете получать данные о текущем пользователе непосредственно в своей *функции обработчике эндпоинта*.
+Теперь вы можете получать текущего пользователя прямо в своей *функции-обработчике пути*.
-Мы уже на полпути к этому.
+Мы уже на полпути.
-Осталось лишь добавить *эндпоинт* для отправки пользователем/клиентом своих `имени пользователя` и `пароля`.
+Нужно лишь добавить *операцию пути*, чтобы пользователь/клиент мог отправить `username` и `password`.
-Это будет рассмотрено в следующем разделе.
+Это будет дальше.
diff --git a/docs/ru/docs/tutorial/security/index.md b/docs/ru/docs/tutorial/security/index.md
index 8fb4bf24f..ebac013b6 100644
--- a/docs/ru/docs/tutorial/security/index.md
+++ b/docs/ru/docs/tutorial/security/index.md
@@ -1,4 +1,4 @@
-# Настройка авторизации
+# Настройка авторизации { #security }
Существует множество способов обеспечения безопасности, аутентификации и авторизации.
@@ -10,11 +10,11 @@
Но сначала давайте рассмотрим некоторые небольшие концепции.
-## Куда-то торопишься?
+## Куда-то торопишься? { #in-a-hurry }
Если вам не нужна информация о каких-либо из следующих терминов и вам просто нужно добавить защиту с аутентификацией на основе логина и пароля *прямо сейчас*, переходите к следующим главам.
-## OAuth2
+## OAuth2 { #oauth2 }
OAuth2 - это протокол, который определяет несколько способов обработки аутентификации и авторизации.
@@ -24,7 +24,7 @@ OAuth2 включает в себя способы аутентификации
Это то, что используют под собой все кнопки "вход с помощью Facebook, Google, X (Twitter), GitHub" на страницах авторизации.
-### OAuth 1
+### OAuth 1 { #oauth-1 }
Ранее использовался протокол OAuth 1, который сильно отличается от OAuth2 и является более сложным, поскольку он включал прямые описания того, как шифровать сообщение.
@@ -34,11 +34,11 @@ OAuth2 не указывает, как шифровать сообщение, о
/// tip | Подсказка
-В разделе **Развертывание** вы увидите [как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.](https://fastapi.tiangolo.com/ru/deployment/https/)
+В разделе **Развертывание** вы увидите как настроить протокол HTTPS бесплатно, используя Traefik и Let's Encrypt.
///
-## OpenID Connect
+## OpenID Connect { #openid-connect }
OpenID Connect - это еще один протокол, основанный на **OAuth2**.
@@ -48,7 +48,7 @@ OpenID Connect - это еще один протокол, основанный
Но вход в Facebook не поддерживает OpenID Connect. У него есть собственная вариация OAuth2.
-### OpenID (не "OpenID Connect")
+### OpenID (не "OpenID Connect") { #openid-not-openid-connect }
Также ранее использовался стандарт "OpenID", который пытался решить ту же проблему, что и **OpenID Connect**, но не был основан на OAuth2.
@@ -56,7 +56,7 @@ OpenID Connect - это еще один протокол, основанный
В настоящее время не очень популярен и не используется.
-## OpenAPI
+## OpenAPI { #openapi }
OpenAPI (ранее известный как Swagger) - это открытая спецификация для создания API (в настоящее время является частью Linux Foundation).
@@ -97,7 +97,7 @@ OpenAPI может использовать следующие схемы авт
///
-## Преимущества **FastAPI**
+## Преимущества **FastAPI** { #fastapi-utilities }
Fast API предоставляет несколько инструментов для каждой из этих схем безопасности в модуле `fastapi.security`, которые упрощают использование этих механизмов безопасности.
diff --git a/docs/ru/docs/tutorial/security/oauth2-jwt.md b/docs/ru/docs/tutorial/security/oauth2-jwt.md
index 57f973d2c..803491f53 100644
--- a/docs/ru/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/ru/docs/tutorial/security/oauth2-jwt.md
@@ -1,12 +1,12 @@
-# OAuth2 с паролем (и хешированием), Bearer с JWT-токенами
+# OAuth2 с паролем (и хешированием), Bearer с JWT-токенами { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
-Теперь, когда у нас определен процесс обеспечения безопасности, давайте сделаем приложение действительно безопасным, используя токены JWT и безопасное хеширование паролей.
+Теперь, когда у нас определен процесс обеспечения безопасности, давайте сделаем приложение действительно безопасным, используя токены JWT и безопасное хеширование паролей.
Этот код можно реально использовать в своем приложении, сохранять хэши паролей в базе данных и т.д.
Мы продолжим разбираться, начиная с того места, на котором остановились в предыдущей главе.
-## Про JWT
+## Про JWT { #about-jwt }
JWT означает "JSON Web Tokens".
@@ -26,7 +26,7 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4
Если вы хотите поиграть с JWT-токенами и посмотреть, как они работают, посмотрите https://jwt.io.
-## Установка `PyJWT`
+## Установка `PyJWT` { #install-pyjwt }
Нам необходимо установить `pyjwt` для генерации и проверки JWT-токенов на языке Python.
@@ -45,10 +45,10 @@ $ pip install pyjwt
/// info | Дополнительная информация
Если вы планируете использовать алгоритмы цифровой подписи, такие как RSA или ECDSA, вам следует установить зависимость библиотеки криптографии `pyjwt[crypto]`.
-Подробнее об этом можно прочитать в документации по установке PyJWT.
+Подробнее об этом можно прочитать в документации по установке PyJWT.
///
-## Хеширование паролей
+## Хеширование паролей { #password-hashing }
"Хеширование" означает преобразование некоторого содержимого (в данном случае пароля) в последовательность байтов (просто строку), которая выглядит как тарабарщина.
@@ -56,26 +56,26 @@ $ pip install pyjwt
Но преобразовать тарабарщину обратно в пароль невозможно.
-### Для чего нужно хеширование паролей
+### Для чего нужно хеширование паролей { #why-use-password-hashing }
Если ваша база данных будет украдена, то вор не получит пароли пользователей в открытом виде, а только их хэши.
Таким образом, вор не сможет использовать этот пароль в другой системе (поскольку многие пользователи везде используют один и тот же пароль, это было бы опасно).
-## Установка `passlib`
+## Установка `pwdlib` { #install-pwdlib }
-PassLib - это отличный пакет Python для работы с хэшами паролей.
+pwdlib — это отличный пакет Python для работы с хэшами паролей.
Он поддерживает множество безопасных алгоритмов хеширования и утилит для работы с ними.
-Рекомендуемый алгоритм - "Bcrypt".
+Рекомендуемый алгоритм — "Argon2".
-Убедитесь, что вы создали и активировали виртуальное окружение, и затем установите PassLib вместе с Bcrypt:
+Убедитесь, что вы создали [виртуальное окружение](../../virtual-environments.md){.internal-link target=_blank}, активируйте его, и затем установите pwdlib вместе с Argon2:
/// note | Техническая информация
-Обратите внимание на заголовок `Authorization`, значение которого начинается с `Bearer`.
+Обратите внимание на HTTP-заголовок `Authorization`, значение которого начинается с `Bearer `.
///
-## Продвинутое использование `scopes`
+## Продвинутое использование `scopes` { #advanced-usage-with-scopes }
В OAuth2 существует понятие "диапазоны" ("`scopes`").
@@ -236,9 +236,9 @@ Password: `secret`
Затем вы можете передать этот токен непосредственно пользователю или третьей стороне для взаимодействия с вашим API с определенным набором ограничений.
-О том, как их использовать и как они интегрированы в **FastAPI**, читайте далее в **Руководстве пользователя**.
+О том, как их использовать и как они интегрированы в **FastAPI**, читайте далее в **Расширенном руководстве пользователя**.
-## Резюме
+## Резюме { #recap }
С учетом того, что вы видели до сих пор, вы можете создать безопасное приложение **FastAPI**, используя такие стандарты, как OAuth2 и JWT.
@@ -252,10 +252,10 @@ Password: `secret`
Он предоставляет вам полную свободу действий, позволяя выбирать то, что лучше всего подходит для вашего проекта.
-Вы можете напрямую использовать многие хорошо поддерживаемые и широко распространенные пакеты, такие как `passlib` и `PyJWT`, поскольку **FastAPI** не требует сложных механизмов для интеграции внешних пакетов.
+Вы можете напрямую использовать многие хорошо поддерживаемые и широко распространенные пакеты, такие как `pwdlib` и `PyJWT`, поскольку **FastAPI** не требует сложных механизмов для интеграции внешних пакетов.
Напротив, он предоставляет инструменты, позволяющие максимально упростить этот процесс без ущерба для гибкости, надежности и безопасности.
При этом вы можете использовать и реализовывать безопасные стандартные протоколы, такие как OAuth2, относительно простым способом.
-В **Руководстве пользователя** вы можете узнать больше о том, как использовать "диапазоны" ("`scopes`") OAuth2 для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 с диапазонами - это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, X (Twitter) и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей.
+В **Расширенном руководстве пользователя** вы можете узнать больше о том, как использовать "диапазоны" ("`scopes`") OAuth2 для создания более точно настроенной системы разрешений в соответствии с теми же стандартами. OAuth2 с диапазонами — это механизм, используемый многими крупными провайдерами сервиса аутентификации, такими как Facebook, Google, GitHub, Microsoft, X (Twitter) и др., для авторизации сторонних приложений на взаимодействие с их API от имени их пользователей.
diff --git a/docs/ru/docs/tutorial/security/simple-oauth2.md b/docs/ru/docs/tutorial/security/simple-oauth2.md
index 9732265cc..36ff32c8e 100644
--- a/docs/ru/docs/tutorial/security/simple-oauth2.md
+++ b/docs/ru/docs/tutorial/security/simple-oauth2.md
@@ -1,59 +1,58 @@
-# Простая авторизация по протоколу OAuth2 с токеном типа Bearer
+# Простая авторизация OAuth2 с паролем и «Bearer» { #simple-oauth2-with-password-and-bearer }
-Теперь, отталкиваясь от предыдущей главы, добавим недостающие части, чтобы получить безопасную систему.
+Теперь, отталкиваясь от предыдущей главы, добавим недостающие части, чтобы получить полный поток безопасности.
-## Получение `имени пользователя` и `пароля`
+## Получение `username` и `password` { #get-the-username-and-password }
-Для получения `имени пользователя` и `пароля` мы будем использовать утилиты безопасности **FastAPI**.
+Для получения `username` и `password` мы будем использовать утилиты безопасности **FastAPI**.
-Протокол OAuth2 определяет, что при использовании "аутентификации по паролю" (которую мы и используем) клиент/пользователь должен передавать поля `username` и `password` в полях формы.
+OAuth2 определяет, что при использовании "password flow" (аутентификация по паролю - именно его мы используем) клиент/пользователь должен передавать поля `username` и `password` в полях формы.
В спецификации сказано, что поля должны быть названы именно так. Поэтому `user-name` или `email` работать не будут.
-Но не волнуйтесь, вы можете показать его конечным пользователям во фронтенде в том виде, в котором хотите.
+Но не волнуйтесь, вы можете показать это конечным пользователям во фронтенде в том виде, в котором хотите.
А ваши модели баз данных могут использовать любые другие имена.
-Но при авторизации согласно спецификации, требуется использовать именно эти имена, что даст нам возможность воспользоваться встроенной системой документации API.
+Но для логин-операции пути нам нужно использовать именно эти имена, чтобы быть совместимыми со спецификацией (и иметь возможность, например, использовать встроенную систему документации API).
В спецификации также указано, что `username` и `password` должны передаваться в виде данных формы (так что никакого JSON здесь нет).
-### Oбласть видимости (scope)
+### `scope` { #scope }
-В спецификации также говорится, что клиент может передать еще одно поле формы "`scope`".
+В спецификации также говорится, что клиент может передать еще одно поле формы — `scope`.
-Имя поля формы - `scope` (в единственном числе), но на самом деле это длинная строка, состоящая из отдельных областей видимости (scopes), разделенных пробелами.
+Имя поля формы — `scope` (в единственном числе), но на самом деле это длинная строка, состоящая из отдельных "scopes", разделенных пробелами.
-Каждая "область видимости" (scope) - это просто строка (без пробелов).
+Каждый "scope" — это просто строка (без пробелов).
Обычно они используются для указания уровней доступа, например:
-* `users:read` или `users:write` являются распространенными примерами.
+* `users:read` или `users:write` — распространенные примеры.
* `instagram_basic` используется Facebook / Instagram.
-* `https://www.googleapis.com/auth/drive` используется компанией Google.
+* `https://www.googleapis.com/auth/drive` используется Google.
-/// info | Дополнительнаяя информация
-В OAuth2 "scope" - это просто строка, которая уточняет уровень доступа.
+/// info | Дополнительная информация
+В OAuth2 "scope" — это просто строка, которая указывает требуемое конкретное разрешение.
-Не имеет значения, содержит ли он другие символы, например `:`, или является ли он URL.
+Не имеет значения, содержит ли она другие символы, например `:`, или является ли это URL.
-Эти детали зависят от конкретной реализации.
+Эти детали зависят от реализации.
Для OAuth2 это просто строки.
///
-## Код получения `имени пользователя` и `пароля`
-
-Для решения задачи давайте воспользуемся утилитами, предоставляемыми **FastAPI**.
+## Код для получения `username` и `password` { #code-to-get-the-username-and-password }
-### `OAuth2PasswordRequestForm`
+Теперь воспользуемся утилитами, предоставляемыми **FastAPI**, чтобы обработать это.
-Сначала импортируйте `OAuth2PasswordRequestForm` и затем используйте ее как зависимость с `Depends` в *эндпоинте* `/token`:
+### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }
+Сначала импортируйте `OAuth2PasswordRequestForm` и затем используйте её как зависимость с `Depends` в операции пути для `/token`:
{* ../../docs_src/security/tutorial003_an_py310.py hl[4,78] *}
-`OAuth2PasswordRequestForm` - это класс для использования в качестве зависимости для *функции обрабатывающей эндпоинт*, который определяет тело формы со следующими полями:
+`OAuth2PasswordRequestForm` — это зависимость-класс, которая объявляет тело формы со следующими полями:
* `username`.
* `password`.
@@ -61,51 +60,51 @@
* Необязательное поле `grant_type`.
/// tip | Подсказка
-По спецификации OAuth2 поле `grant_type` является обязательным и содержит фиксированное значение `password`, но `OAuth2PasswordRequestForm` не обеспечивает этого.
+По спецификации OAuth2 поле `grant_type` обязательно и содержит фиксированное значение `password`, но `OAuth2PasswordRequestForm` это не проверяет строго.
-Если вам необходимо использовать `grant_type`, воспользуйтесь `OAuth2PasswordRequestFormStrict` вместо `OAuth2PasswordRequestForm`.
+Если вам нужно это строгое требование, используйте `OAuth2PasswordRequestFormStrict` вместо `OAuth2PasswordRequestForm`.
///
-* Необязательное поле `client_id` (в нашем примере он не нужен).
-* Необязательное поле `client_secret` (в нашем примере он не нужен).
+* Необязательное поле `client_id` (в нашем примере оно не нужно).
+* Необязательное поле `client_secret` (в нашем примере оно не нужно).
/// info | Дополнительная информация
-Форма `OAuth2PasswordRequestForm` не является специальным классом для **FastAPI**, как `OAuth2PasswordBearer`.
+`OAuth2PasswordRequestForm` — это не специальный класс для **FastAPI**, как `OAuth2PasswordBearer`.
-`OAuth2PasswordBearer` указывает **FastAPI**, что это схема безопасности. Следовательно, она будет добавлена в OpenAPI.
+`OAuth2PasswordBearer` сообщает **FastAPI**, что это схема безопасности. Поэтому она добавляется в OpenAPI соответствующим образом.
-Но `OAuth2PasswordRequestForm` - это всего лишь класс зависимости, который вы могли бы написать самостоятельно или вы могли бы объявить параметры `Form` напрямую.
+А `OAuth2PasswordRequestForm` — это просто зависимость-класс, которую вы могли бы написать сами, или вы могли бы объявить параметры `Form` напрямую.
-Но, поскольку это распространённый вариант использования, он предоставляется **FastAPI** напрямую, просто чтобы облегчить задачу.
+Но так как это распространённый вариант использования, он предоставлен **FastAPI** напрямую, чтобы упростить задачу.
///
-### Использование данных формы
+### Использование данных формы { #use-the-form-data }
/// tip | Подсказка
-В экземпляре зависимого класса `OAuth2PasswordRequestForm` атрибут `scope`, состоящий из одной длинной строки, разделенной пробелами, заменен на атрибут `scopes`, состоящий из списка отдельных строк, каждая из которых соответствует определенному уровню доступа.
+У экземпляра зависимости `OAuth2PasswordRequestForm` не будет атрибута `scope` с длинной строкой, разделенной пробелами. Вместо этого будет атрибут `scopes` со списком отдельных строк — по одной для каждого переданного scope.
-В данном примере мы не используем `scopes`, но если вам это необходимо, то такая функциональность имеется.
+В данном примере мы не используем `scopes`, но если вам это необходимо, функциональность есть.
///
Теперь получим данные о пользователе из (ненастоящей) базы данных, используя `username` из поля формы.
-Если такого пользователя нет, то мы возвращаем ошибку "неверное имя пользователя или пароль".
+Если такого пользователя нет, то мы возвращаем ошибку "Incorrect username or password" (неверное имя пользователя или пароль).
-Для ошибки мы используем исключение `HTTPException`:
+Для ошибки используем исключение `HTTPException`:
{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
-### Проверка пароля
+### Проверка пароля { #check-the-password }
На данный момент у нас есть данные о пользователе из нашей базы данных, но мы еще не проверили пароль.
-Давайте сначала поместим эти данные в модель Pydantic `UserInDB`.
+Давайте сначала поместим эти данные в Pydantic-модель `UserInDB`.
-Ни в коем случае нельзя сохранять пароли в открытом виде, поэтому мы будем использовать (пока что ненастоящую) систему хеширования паролей.
+Никогда нельзя сохранять пароли в открытом виде, поэтому мы будем использовать (пока что ненастоящую) систему хеширования паролей.
Если пароли не совпадают, мы возвращаем ту же ошибку.
-#### Хеширование паролей
+#### Хеширование паролей { #password-hashing }
"Хеширование" означает: преобразование некоторого содержимого (в данном случае пароля) в последовательность байтов (просто строку), которая выглядит как тарабарщина.
@@ -113,19 +112,19 @@
Но преобразовать тарабарщину обратно в пароль невозможно.
-##### Зачем использовать хеширование паролей
+##### Зачем использовать хеширование паролей { #why-use-password-hashing }
-Если ваша база данных будет украдена, то у вора не будет паролей пользователей в открытом виде, только хэши.
+Если вашу базу данных украдут, у злоумышленника не будет паролей пользователей в открытом виде, только хэши.
-Таким образом, вор не сможет использовать эти же пароли в другой системе (поскольку многие пользователи используют одни и те же пароли повсеместно, это было бы опасно).
+Таким образом, он не сможет попробовать использовать эти же пароли в другой системе (поскольку многие пользователи используют один и тот же пароль повсеместно, это было бы опасно).
{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-#### Про `**user_dict`
+#### Про `**user_dict` { #about-user-dict }
`UserInDB(**user_dict)` означает:
-*Передавать ключи и значения `user_dict` непосредственно в качестве аргументов ключ-значение, что эквивалентно:*
+*Передать ключи и значения `user_dict` непосредственно как аргументы ключ-значение, эквивалентно:*
```Python
UserInDB(
@@ -138,23 +137,23 @@ UserInDB(
```
/// info | Дополнительная информация
-Более полное объяснение `**user_dict` можно найти в [документации к **Дополнительным моделям**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+Более полное объяснение `**user_dict` можно найти в [документации к **Дополнительным моделям**](../extra-models.md#about-user-in-dict){.internal-link target=_blank}.
///
-## Возврат токена
+## Возврат токена { #return-the-token }
-Ответ эндпоинта `token` должен представлять собой объект в формате JSON.
+Ответ операции пути `/token` должен быть объектом JSON.
-Он должен иметь `token_type`. В нашем случае, поскольку мы используем токены типа "Bearer", тип токена должен быть "`bearer`".
+В нём должен быть `token_type`. В нашем случае, поскольку мы используем токены типа "Bearer", тип токена должен быть `bearer`.
-И в нем должна быть строка `access_token`, содержащая наш токен доступа.
+И в нём должен быть `access_token` — строка, содержащая наш токен доступа.
-В этом простом примере мы нарушим все правила безопасности, и будем считать, что имя пользователя (username) полностью соответствует токену (token)
+В этом простом примере мы намеренно поступим небезопасно и вернём тот же `username` в качестве токена.
/// tip | Подсказка
-В следующей главе мы рассмотрим реальную защищенную реализацию с хешированием паролей и токенами JWT.
+В следующей главе вы увидите реальную защищённую реализацию с хешированием паролей и токенами JWT.
-Но пока давайте остановимся на необходимых нам деталях.
+Но пока давайте сосредоточимся на необходимых нам деталях.
///
{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}
@@ -162,50 +161,50 @@ UserInDB(
/// tip | Подсказка
Согласно спецификации, вы должны возвращать JSON с `access_token` и `token_type`, как в данном примере.
-Это то, что вы должны сделать сами в своем коде и убедиться, что вы используете эти JSON-ключи.
+Это то, что вы должны сделать сами в своём коде и убедиться, что вы используете именно эти JSON-ключи.
-Это практически единственное, что нужно не забывать делать самостоятельно, чтобы следовать требованиям спецификации.
+Это практически единственное, о чём нужно не забыть, чтобы соответствовать спецификациям.
-Все остальное за вас сделает **FastAPI**.
+Остальное за вас сделает **FastAPI**.
///
-## Обновление зависимостей
+## Обновление зависимостей { #update-the-dependencies }
Теперь мы обновим наши зависимости.
-Мы хотим получить значение `current_user` *только* если этот пользователь активен.
+Мы хотим получить `current_user` только если этот пользователь активен.
-Поэтому мы создаем дополнительную зависимость `get_current_active_user`, которая, в свою очередь, использует в качестве зависимости `get_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-заголовок `WWW-Authenticate` со значением `Bearer`, который мы здесь возвращаем, также является частью спецификации.
-Ответ сервера с HTTP-кодом 401 "UNAUTHORIZED" должен также возвращать заголовок `WWW-Authenticate`.
+Любой HTTP статус-код 401 "UNAUTHORIZED" должен также возвращать заголовок `WWW-Authenticate`.
В случае с bearer-токенами (наш случай) значение этого заголовка должно быть `Bearer`.
-На самом деле этот дополнительный заголовок можно пропустить и все будет работать.
+Фактически, этот дополнительный заголовок можно опустить, и всё будет работать.
-Но он приведён здесь для соответствия спецификации.
+Но он приведён здесь для соответствия спецификациям.
-Кроме того, могут существовать инструменты, которые ожидают его и могут использовать, и это может быть полезно для вас или ваших пользователей сейчас или в будущем.
+Кроме того, могут существовать инструменты, которые ожидают его и могут использовать, и это может быть полезно для вас или ваших пользователей — сейчас или в будущем.
В этом и заключается преимущество стандартов...
///
-## Посмотим как это работает
+## Посмотрим, как это работает { #see-it-in-action }
-Откроем интерактивную документацию: http://127.0.0.1:8000/docs.
+Откройте интерактивную документацию: http://127.0.0.1:8000/docs.
-### Аутентификация
+### Аутентификация { #authenticate }
-Нажмите кнопку "Авторизация".
+Нажмите кнопку "Authorize".
Используйте учётные данные:
@@ -215,13 +214,15 @@ UserInDB(
-После авторизации в системе вы увидите следующее:
+После аутентификации вы увидите следующее:
-### Получение собственных пользовательских данных
+### Получение собственных пользовательских данных { #get-your-own-user-data }
+
+Теперь используйте операцию `GET` с путём `/users/me`.
-Теперь, используя операцию `GET` с путем `/users/me`, вы получите данные пользователя, например:
+Вы получите свои пользовательские данные, например:
```JSON
{
@@ -235,7 +236,7 @@ UserInDB(
-Если щелкнуть на значке замка и выйти из системы, а затем попытаться выполнить ту же операцию ещё раз, то будет выдана ошибка HTTP 401:
+Если щёлкнуть на значке замка и выйти из системы, а затем попытаться выполнить ту же операцию ещё раз, будет выдана ошибка HTTP 401:
```JSON
{
@@ -243,17 +244,17 @@ UserInDB(
}
```
-### Неактивный пользователь
+### Неактивный пользователь { #inactive-user }
-Теперь попробуйте пройти аутентификацию с неактивным пользователем:
+Теперь попробуйте с неактивным пользователем, аутентифицируйтесь с:
Пользователь: `alice`
Пароль: `secret2`
-И попробуйте использовать операцию `GET` с путем `/users/me`.
+И попробуйте использовать операцию `GET` с путём `/users/me`.
-Вы получите ошибку "Inactive user", как тут:
+Вы получите ошибку "Inactive user", как здесь:
```JSON
{
@@ -261,12 +262,12 @@ UserInDB(
}
```
-## Резюме
+## Резюме { #recap }
-Теперь у вас есть инструменты для реализации полноценной системы безопасности на основе `имени пользователя` и `пароля` для вашего API.
+Теперь у вас есть инструменты для реализации полноценной системы безопасности на основе `username` и `password` для вашего API.
-Используя эти средства, можно сделать систему безопасности совместимой с любой базой данных, с любым пользователем или моделью данных.
+Используя эти средства, можно сделать систему безопасности совместимой с любой базой данных и с любой пользовательской или моделью данных.
- Единственным недостатком нашей системы является то, что она всё ещё не защищена.
+Единственная деталь, которой не хватает, — система пока ещё не "защищена" по-настоящему.
-В следующей главе вы увидите, как использовать библиотеку безопасного хеширования паролей и токены JWT.
+В следующей главе вы увидите, как использовать библиотеку безопасного хеширования паролей и токены JWT.
diff --git a/docs/ru/docs/tutorial/sql-databases.md b/docs/ru/docs/tutorial/sql-databases.md
index b127e44d5..1d0346533 100644
--- a/docs/ru/docs/tutorial/sql-databases.md
+++ b/docs/ru/docs/tutorial/sql-databases.md
@@ -1,18 +1,18 @@
-# SQL (реляционные) базы данных
+# SQL (реляционные) базы данных { #sql-relational-databases }
-**FastAPI** не требует использования реляционной базы данных. Вы можете воспользоваться любой базой данных, которой хотите.
+**FastAPI** не требует использовать SQL (реляционную) базу данных. Но вы можете использовать любую базу данных, которую хотите.
-В этом разделе мы продемонстрируем, как работать с SQLModel.
+Здесь мы рассмотрим пример с использованием SQLModel.
-Библиотека **SQLModel** построена на основе SQLAlchemy и Pydantic. Она была разработана автором **FastAPI** специально для приложений на основе FastAPI, которые используют **реляционные базы данных**.
+**SQLModel** построен поверх SQLAlchemy и Pydantic. Его создал тот же автор, что и **FastAPI**, чтобы он идеально подходил для приложений FastAPI, которым нужны **SQL базы данных**.
/// tip | Подсказка
-Вы можете воспользоваться любой библиотекой для работы с реляционными (SQL) или нереляционными (NoSQL) базами данных. (Их ещё называют **ORM** библиотеками). FastAPI не принуждает вас к использованию чего-либо конкретного. 😎
+Вы можете использовать любую другую библиотеку для работы с SQL или NoSQL базами данных (иногда их называют "ORMs"), FastAPI ничего не навязывает. 😎
///
-В основе SQLModel лежит SQLAlchemy, поэтому вы спокойно можете использовать любую базу данных, поддерживаемую SQLAlchemy (и, соответственно, поддерживаемую SQLModel), например:
+Так как SQLModel основан на SQLAlchemy, вы можете легко использовать **любую поддерживаемую** SQLAlchemy базу данных (а значит, и поддерживаемую SQLModel), например:
* PostgreSQL
* MySQL
@@ -20,21 +20,21 @@
* Oracle
* Microsoft SQL Server, и т.д.
-В данном примере мы будем использовать базу данных **SQLite**, т.к. она состоит из единственного файла и поддерживается встроенными библиотеками Python. Таким образом, вы сможете скопировать данный пример и запустить его как он есть.
+В этом примере мы будем использовать **SQLite**, потому что она использует один файл и имеет встроенную поддержку в Python. Так что вы можете скопировать этот пример и запустить его как есть.
-В дальнейшем, для продакшн-версии вашего приложения, возможно, вам стоит использовать серверную базу данных, например, **PostgreSQL**.
+Позже, для продакшн-приложения, возможно, вы захотите использовать серверную базу данных, например **PostgreSQL**.
/// tip | Подсказка
-Существует официальный генератор проектов на **FastAPI** и **PostgreSQL**, который также включает frontend и дополнительные инструменты https://github.com/fastapi/full-stack-fastapi-template
+Существует официальный генератор проектов на **FastAPI** и **PostgreSQL**, включающий frontend и другие инструменты: https://github.com/fastapi/full-stack-fastapi-template
///
-Это очень простое и короткое руководство, поэтому, если вы хотите узнать о базах данных в целом, об SQL, разобраться с более продвинутым функционалом, то воспользуйтесь документацией SQLModel.
+Это очень простое и короткое руководство. Если вы хотите узнать больше о базах данных в целом, об SQL или о более продвинутых возможностях, обратитесь к документации SQLModel.
-## Установка `SQLModel`
+## Установка `SQLModel` { #install-sqlmodel }
-Создайте виртуальное окружение [virtual environment](../virtual-environments.md){.internal-link target=_blank}, активируйте его и установите `sqlmodel`:
+Сначала убедитесь, что вы создали [виртуальное окружение](../virtual-environments.md){.internal-link target=_blank}, активировали его и затем установили `sqlmodel`:
uvicorn - oluşturduğumuz uygulamayı servis edecek web sunucusu görevini üstlenir.
+* uvicorn - oluşturduğumuz uygulamayı servis edecek web sunucusu görevini üstlenir.
* orjson - `ORJSONResponse` kullanacaksanız gereklidir.
* ujson - `UJSONResponse` kullanacaksanız gerekli.
diff --git a/docs/tr/docs/tutorial/first-steps.md b/docs/tr/docs/tutorial/first-steps.md
index 2d2949b50..9a8ef762d 100644
--- a/docs/tr/docs/tutorial/first-steps.md
+++ b/docs/tr/docs/tutorial/first-steps.md
@@ -139,7 +139,7 @@ Ayrıca, API'ınızla iletişim kuracak önyüz, mobil veya IoT uygulamaları gi
`FastAPI` doğrudan `Starlette`'i miras alan bir sınıftır.
-Starlette'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz.
+Starlette'in tüm işlevselliğini `FastAPI` ile de kullanabilirsiniz.
///
diff --git a/docs/tr/docs/tutorial/static-files.md b/docs/tr/docs/tutorial/static-files.md
index db30f13bc..4542aca77 100644
--- a/docs/tr/docs/tutorial/static-files.md
+++ b/docs/tr/docs/tutorial/static-files.md
@@ -37,4 +37,4 @@ Bu parametrelerin hepsi "`static`"den farklı olabilir, bunları kendi uygulaman
## Daha Fazla Bilgi
-Daha fazla detay ve seçenek için Starlette'in Statik Dosyalar hakkındaki dokümantasyonunu incelleyin.
+Daha fazla detay ve seçenek için Starlette'in Statik Dosyalar hakkındaki dokümantasyonunu incelleyin.
diff --git a/docs/tr/llm-prompt.md b/docs/tr/llm-prompt.md
new file mode 100644
index 000000000..2ba922ec5
--- /dev/null
+++ b/docs/tr/llm-prompt.md
@@ -0,0 +1,68 @@
+### Target language
+
+Translate to Turkish (Türkçe).
+
+Language code: tr.
+
+### Core principle
+
+Don't translate word-by-word. Rewrite naturally in Turkish as if writing the doc from scratch. Preserve meaning, but prioritize fluency over literal accuracy.
+
+### Grammar and tone
+
+- Use instructional Turkish, consistent with existing Turkish docs.
+- Use imperative/guide language (e.g. "açalım", "gidin", "kopyalayalım", "bir bakalım").
+- Avoid filler words and overly long sentences.
+- Ensure sentences make sense in Turkish context — adjust structure, conjunctions, and verb forms as needed for natural flow (e.g. use "Ancak" instead of "Ve" when connecting contrasting sentences, use "-maktadır/-mektedir" for formal statements).
+
+### Headings
+
+- Follow existing Turkish heading style (Title Case where used; no trailing period).
+
+### Quotes
+
+- Keep quote style consistent with existing Turkish docs (typically ASCII quotes in text).
+- Never modify quotes inside inline code, code blocks, URLs, or file paths.
+
+### Ellipsis
+
+- Keep ellipsis style (`...`) consistent with existing Turkish docs.
+- Never modify `...` in code, URLs, or CLI examples.
+
+### Consistency
+
+- Use the same translation for the same term throughout the document.
+- If you translate a concept one way, keep it consistent across all occurrences.
+
+### Links and references
+
+- Never modify link syntax like `{.internal-link target=_blank}`.
+- Keep markdown link structure intact: `[text](url){.internal-link}`.
+
+### Preferred translations / glossary
+
+Do not translate technical terms like path, route, request, response, query, body, cookie, and header, keep them as is.
+
+- Suffixing is very important, when adding Turkish suffixes to the English words, do that based on the pronunciation of the word and with an apostrophe.
+
+- Suffixes also changes based on what word comes next in Turkish too, here is an example:
+
+"Server'a gelen request'leri intercept... " or this could have been "request'e", "request'i" etc.
+
+- Some words are tricky like "path'e" can't be used like "path'a" but it could have been "path'i" "path'leri" etc.
+
+- You can use a more instructional style, that is consistent with the document, you can add the Turkish version of the term in parenthesis if it is not something very obvious, or an advanced concept, but do not over do it, do it only the first time it is mentioned, but keep the English term as the primary word.
+
+### `///` admonitions
+
+- Keep the admonition keyword in English (do not translate `note`, `tip`, etc.).
+- If a title is present, prefer these canonical titles:
+
+- `/// note | Not`
+- `/// note | Teknik Detaylar`
+- `/// tip | İpucu`
+- `/// warning | Uyarı`
+- `/// info | Bilgi`
+- `/// check | Ek bilgi`
+
+Prefer `İpucu` over `Ipucu`.
diff --git a/docs/uk/docs/alternatives.md b/docs/uk/docs/alternatives.md
index 1acbe237a..786df45c5 100644
--- a/docs/uk/docs/alternatives.md
+++ b/docs/uk/docs/alternatives.md
@@ -415,7 +415,7 @@ Pydantic — це бібліотека для визначення переві
///
-### Starlette
+### Starlette
Starlette — це легкий фреймворк/набір інструментів ASGI, який ідеально підходить для створення високопродуктивних asyncio сервісів.
@@ -460,7 +460,7 @@ ASGI — це новий «стандарт», який розробляєтьс
///
-### Uvicorn
+### Uvicorn
Uvicorn — це блискавичний сервер ASGI, побудований на uvloop і httptools.
diff --git a/docs/uk/docs/fastapi-cli.md b/docs/uk/docs/fastapi-cli.md
index 6bbbbc326..f18b10471 100644
--- a/docs/uk/docs/fastapi-cli.md
+++ b/docs/uk/docs/fastapi-cli.md
@@ -60,7 +60,7 @@ FastAPI CLI приймає шлях до Вашої Python програми (н
Натомість, для запуску у продакшн використовуйте `fastapi run`. 🚀
-Всередині **FastAPI CLI** використовує Uvicorn, високопродуктивний, production-ready, ASGI cервер. 😎
+Всередині **FastAPI CLI** використовує Uvicorn, високопродуктивний, production-ready, ASGI cервер. 😎
## `fastapi dev`
diff --git a/docs/uk/docs/features.md b/docs/uk/docs/features.md
index 7d679d8ee..aa0ef7c79 100644
--- a/docs/uk/docs/features.md
+++ b/docs/uk/docs/features.md
@@ -147,7 +147,7 @@ FastAPI має розумні налаштування **за замовчува
## Можливості Starlette
-**FastAPI** повністю сумісний із (та побудований на основі) Starlette. Тому будь-який додатковий код Starlette, який ви маєте, також працюватиме.
+**FastAPI** повністю сумісний із (та побудований на основі) Starlette. Тому будь-який додатковий код Starlette, який ви маєте, також працюватиме.
**FastAPI** фактично є підкласом **Starlette**. Тому, якщо ви вже знайомі зі Starlette або використовуєте його, більшість функціональності працюватиме так само.
diff --git a/docs/uk/docs/index.md b/docs/uk/docs/index.md
index 7e919e257..526409c5c 100644
--- a/docs/uk/docs/index.md
+++ b/docs/uk/docs/index.md
@@ -1,8 +1,14 @@
+# FastAPI { #fastapi }
+
+
+
-
+
- Готовий до продакшину, високопродуктивний, простий у вивченні та швидкий для написання коду фреймворк + Фреймворк FastAPI: висока продуктивність, легко вивчати, швидко писати код, готовий до продакшину
@@ -21,46 +27,51 @@
---
-**Документація**: https://fastapi.tiangolo.com
+**Документація**: https://fastapi.tiangolo.com
-**Програмний код**: https://github.com/fastapi/fastapi
+**Вихідний код**: https://github.com/fastapi/fastapi
---
-FastAPI - це сучасний, швидкий (високопродуктивний), вебфреймворк для створення API за допомогою Python,в основі якого лежить стандартна анотація типів Python.
+FastAPI — це сучасний, швидкий (високопродуктивний) вебфреймворк для створення API за допомогою Python, що базується на стандартних підказках типів Python.
Ключові особливості:
-* **Швидкий**: Дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших фреймворків](#performance).
-
-* **Швидке написання коду**: Пришвидшує розробку функціоналу приблизно на 200%-300%. *
-* **Менше помилок**: Зменшить кількість помилок спричинених людиною (розробником) на 40%. *
-* **Інтуїтивний**: Чудова підтримка редакторами коду. Доповнення всюди. Зменште час на налагодження.
-* **Простий**: Спроектований, для легкого використання та навчання. Знадобиться менше часу на читання документації.
-* **Короткий**: Зведе до мінімуму дублювання коду. Кожен оголошений параметр може виконувати кілька функцій.
-* **Надійний**: Ви матимете стабільний код готовий до продакшину з автоматичною інтерактивною документацією.
-* **Стандартизований**: Оснований та повністю сумісний з відкритими стандартами для API: OpenAPI (попередньо відомий як Swagger) та JSON Schema.
+* **Швидкий**: дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших Python-фреймворків](#performance).
+* **Швидке написання коду**: пришвидшує розробку функціоналу приблизно на 200%–300%. *
+* **Менше помилок**: зменшує приблизно на 40% кількість помилок, спричинених людиною (розробником). *
+* **Інтуїтивний**: чудова підтримка редакторами коду. Автодоповнення всюди. Менше часу на налагодження.
+* **Простий**: спроєктований так, щоб бути простим у використанні та вивченні. Менше часу на читання документації.
+* **Короткий**: мінімізує дублювання коду. Кілька можливостей з кожного оголошення параметра. Менше помилок.
+* **Надійний**: ви отримуєте код, готовий до продакшину. З автоматичною інтерактивною документацією.
+* **Заснований на стандартах**: базується на (і повністю сумісний з) відкритими стандартами для API: OpenAPI (раніше відомий як Swagger) та JSON Schema.
-* оцінка на основі тестів внутрішньої команди розробників, створення продуктових застосунків.
+* оцінка на основі тестів, проведених внутрішньою командою розробників, що створює продакшн-застосунки.
-## Спонсори
+## Спонсори { #sponsors }
-{% if sponsors %}
+### Ключовий спонсор { #keystone-sponsor }
+
+{% for sponsor in sponsors.keystone -%}
+
+{% endfor -%}
+
+### Золоті та срібні спонсори { #gold-and-silver-sponsors }
+
{% for sponsor in sponsors.gold -%}
{% endfor -%}
{%- for sponsor in sponsors.silver -%}
{% endfor %}
-{% endif %}
-Other sponsors
+Інші спонсори
-## Враження
+## Враження { #opinions }
"_[...] 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._"
@@ -88,7 +99,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._"
-
+
-* Starlette для web частини.
-* Pydantic для частини даних.
+## **Typer**, FastAPI для CLI { #typer-the-fastapi-of-clis }
-## Вставновлення
+
-uvicorn main:app --reload...fastapi dev main.py...email-validator - для валідації електронної пошти.
-* pydantic-settings - для управління налаштуваннями.
-* pydantic-extra-types - для додаткових типів, що можуть бути використані з Pydantic.
+Використовується Starlette:
+
+* httpx - потрібно, якщо ви хочете використовувати `TestClient`.
+* jinja2 - потрібно, якщо ви хочете використовувати конфігурацію шаблонів за замовчуванням.
+* python-multipart - потрібно, якщо ви хочете підтримувати «parsing» форм за допомогою `request.form()`.
-Starlette використовує:
+Використовується FastAPI:
-* httpx - Необхідно, якщо Ви хочете використовувати `TestClient`.
-* jinja2 - Необхідно, якщо Ви хочете використовувати шаблони як конфігурацію за замовчуванням.
-* python-multipart - Необхідно, якщо Ви хочете підтримувати "розбір" форми за допомогою `request.form()`.
-* itsdangerous - Необхідно для підтримки `SessionMiddleware`.
-* pyyaml - Необхідно для підтримки Starlette `SchemaGenerator` (ймовірно, вам це не потрібно з FastAPI).
+* uvicorn - для сервера, який завантажує та обслуговує ваш застосунок. Це включає `uvicorn[standard]`, до якого входять деякі залежності (наприклад, `uvloop`), потрібні для високопродуктивної роботи сервера.
+* `fastapi-cli[standard]` - щоб надати команду `fastapi`.
+ * Це включає `fastapi-cloud-cli`, який дозволяє розгортати ваш застосунок FastAPI у FastAPI Cloud.
-FastAPI / Starlette використовують:
+### Без залежностей `standard` { #without-standard-dependencies }
+
+Якщо ви не хочете включати необовʼязкові залежності `standard`, ви можете встановити через `pip install fastapi` замість `pip install "fastapi[standard]"`.
+
+### Без `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
+
+Якщо ви хочете встановити FastAPI зі стандартними залежностями, але без `fastapi-cloud-cli`, ви можете встановити через `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
+
+### Додаткові необовʼязкові залежності { #additional-optional-dependencies }
+
+Є ще деякі додаткові залежності, які ви можете захотіти встановити.
+
+Додаткові необовʼязкові залежності Pydantic:
+
+* pydantic-settings - для керування налаштуваннями.
+* pydantic-extra-types - для додаткових типів, що можуть бути використані з Pydantic.
-* uvicorn - для сервера, який завантажує та обслуговує вашу програму.
-* orjson - Необхідно, якщо Ви хочете використовувати `ORJSONResponse`.
-* ujson - Необхідно, якщо Ви хочете використовувати `UJSONResponse`.
+Додаткові необовʼязкові залежності FastAPI:
-Ви можете встановити все це за допомогою `pip install fastapi[all]`.
+* orjson - потрібно, якщо ви хочете використовувати `ORJSONResponse`.
+* ujson - потрібно, якщо ви хочете використовувати `UJSONResponse`.
-## Ліцензія
+## Ліцензія { #license }
Цей проєкт ліцензовано згідно з умовами ліцензії MIT.
diff --git a/docs/uk/docs/learn/index.md b/docs/uk/docs/learn/index.md
index 7f9f21e57..6e28d414a 100644
--- a/docs/uk/docs/learn/index.md
+++ b/docs/uk/docs/learn/index.md
@@ -1,5 +1,5 @@
-# Навчання
+# Навчання { #learn }
-У цьому розділі надані вступні та навчальні матеріали для вивчення FastAPI.
+У цьому розділі надані вступні розділи та навчальні матеріали для вивчення **FastAPI**.
Це можна розглядати як **книгу**, **курс**, або **офіційний** та рекомендований спосіб освоїти FastAPI. 😎
diff --git a/docs/uk/docs/python-types.md b/docs/uk/docs/python-types.md
index 676bafb15..a82d13a28 100644
--- a/docs/uk/docs/python-types.md
+++ b/docs/uk/docs/python-types.md
@@ -1,29 +1,28 @@
-# Вступ до типів Python
+# Вступ до типів Python { #python-types-intro }
-Python підтримує додаткові "підказки типу" ("type hints") (також звані "анотаціями типу" ("type annotations")).
+Python підтримує додаткові «підказки типів» (також звані «анотаціями типів»).
-Ці **"type hints"** є спеціальним синтаксисом, що дозволяє оголошувати тип змінної.
+Ці **«підказки типів»** або анотації — це спеціальний синтаксис, що дозволяє оголошувати тип змінної.
-За допомогою оголошення типів для ваших змінних, редактори та інструменти можуть надати вам кращу підтримку.
+За допомогою оголошення типів для ваших змінних редактори та інструменти можуть надати вам кращу підтримку.
-Це просто **швидкий посібник / нагадування** про анотації типів у Python. Він покриває лише мінімум, необхідний щоб використовувати їх з **FastAPI**... що насправді дуже мало.
+Це лише **швидкий туторіал / нагадування** про підказки типів у Python. Він покриває лише мінімум, необхідний щоб використовувати їх з **FastAPI**... що насправді дуже мало.
-**FastAPI** повністю базується на цих анотаціях типів, вони дають йому багато переваг.
+**FastAPI** повністю базується на цих підказках типів, вони дають йому багато переваг і користі.
Але навіть якщо ви ніколи не використаєте **FastAPI**, вам буде корисно дізнатись трохи про них.
-/// note
+/// note | Примітка
-Якщо ви експерт у Python і ви вже знаєте усе про анотації типів - перейдіть до наступного розділу.
+Якщо ви експерт у Python і ви вже знаєте все про підказки типів, перейдіть до наступного розділу.
///
-## Мотивація
+## Мотивація { #motivation }
Давайте почнемо з простого прикладу:
-{* ../../docs_src/python_types/tutorial001.py *}
-
+{* ../../docs_src/python_types/tutorial001_py39.py *}
Виклик цієї програми виводить:
@@ -34,13 +33,12 @@ John Doe
Функція виконує наступне:
* Бере `first_name` та `last_name`.
-* Конвертує кожну літеру кожного слова у верхній регістр за допомогою `title()`.
-* Конкатенує їх разом із пробілом по середині.
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
+* Перетворює першу літеру кожного з них у верхній регістр за допомогою `title()`.
+* Конкатенує їх разом із пробілом по середині.
+{* ../../docs_src/python_types/tutorial001_py39.py hl[2] *}
-### Редагуйте це
+### Редагуйте це { #edit-it }
Це дуже проста програма.
@@ -48,11 +46,11 @@ John Doe
У певний момент ви розпочали б визначення функції, у вас були б готові параметри...
-Але тоді вам потрібно викликати "той метод, який переводить першу літеру у верхній регістр".
+Але тоді вам потрібно викликати «той метод, який перетворює першу літеру у верхній регістр».
Це буде `upper`? Чи `uppercase`? `first_uppercase`? `capitalize`?
-Тоді ви спробуєте давнього друга програміста - автозаповнення редактора коду.
+Тоді ви спробуєте давнього друга програміста — автозаповнення редактора коду.
Ви надрукуєте перший параметр функції, `first_name`, тоді крапку (`.`), а тоді натиснете `Ctrl+Space`, щоб запустити автозаповнення.
@@ -60,7 +58,7 @@ John Doe
-### Додайте типи
+### Додайте типи { #add-types }
Давайте змінимо один рядок з попередньої версії.
@@ -78,10 +76,9 @@ John Doe
Ось і все.
-Це "type hints":
-
-{* ../../docs_src/python_types/tutorial002.py hl[1] *}
+Це «підказки типів»:
+{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *}
Це не те саме, що оголошення значень за замовчуванням, як це було б з:
@@ -91,43 +88,41 @@ John Doe
Це зовсім інше.
-Ми використовуємо двокрапку (`:`), не дорівнює (`=`).
+Ми використовуємо двокрапку (`:`), не знак дорівнює (`=`).
-І додавання анотації типу зазвичай не змінює того, що сталось би без них.
+І додавання підказок типів зазвичай не змінює того, що відбувається, порівняно з тим, що відбувалося б без них.
-Але тепер, уявіть що ви посеред процесу створення функції, але з анотаціями типів.
+Але тепер уявіть, що ви знову посеред процесу створення функції, але з підказками типів.
-В цей же момент, ви спробуєте викликати автозаповнення з допомогою `Ctrl+Space` і побачите:
+У той самий момент ви спробуєте викликати автозаповнення за допомогою `Ctrl+Space` і побачите:
-Разом з цим, ви можете прокручувати, переглядати опції, допоки ви не знайдете одну, що звучить схоже:
+Разом з цим ви можете прокручувати, переглядаючи опції, допоки не знайдете ту, що «щось вам підказує»:
-## Більше мотивації
-
-Перевірте цю функцію, вона вже має анотацію типу:
+## Більше мотивації { #more-motivation }
-{* ../../docs_src/python_types/tutorial003.py hl[1] *}
+Перевірте цю функцію, вона вже має підказки типів:
+{* ../../docs_src/python_types/tutorial003_py39.py hl[1] *}
Оскільки редактор знає типи змінних, ви не тільки отримаєте автозаповнення, ви також отримаєте перевірку помилок:
-Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у строку з допомогою `str(age)`:
+Тепер ви знаєте, щоб виправити це, вам потрібно перетворити `age` у рядок за допомогою `str(age)`:
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
+{* ../../docs_src/python_types/tutorial004_py39.py hl[2] *}
+## Оголошення типів { #declaring-types }
-## Оголошення типів
-
-Щойно ви побачили основне місце для оголошення анотацій типу. Як параметри функції.
+Щойно ви побачили основне місце для оголошення підказок типів. Як параметри функції.
Це також основне місце, де ви б їх використовували у **FastAPI**.
-### Прості типи
+### Прості типи { #simple-types }
Ви можете оголошувати усі стандартні типи у Python, не тільки `str`.
@@ -138,78 +133,51 @@ John Doe
* `bool`
* `bytes`
-{* ../../docs_src/python_types/tutorial005.py hl[1] *}
-
+{* ../../docs_src/python_types/tutorial005_py39.py hl[1] *}
-### Generic-типи з параметрами типів
+### Generic-типи з параметрами типів { #generic-types-with-type-parameters }
Існують деякі структури даних, які можуть містити інші значення, наприклад `dict`, `list`, `set` та `tuple`. І внутрішні значення також можуть мати свій тип.
-Ці типи, які мають внутрішні типи, називаються "**generic**" типами. І оголосити їх можна навіть із внутрішніми типами.
+Ці типи, які мають внутрішні типи, називаються «**generic**» типами. І оголосити їх можна навіть із внутрішніми типами.
-Щоб оголосити ці типи та внутрішні типи, ви можете використовувати стандартний модуль Python `typing`. Він існує спеціально для підтримки анотацій типів.
+Щоб оголосити ці типи та внутрішні типи, ви можете використовувати стандартний модуль Python `typing`. Він існує спеціально для підтримки цих підказок типів.
-#### Новіші версії Python
+#### Новіші версії Python { #newer-versions-of-python }
Синтаксис із використанням `typing` **сумісний** з усіма версіями, від Python 3.6 до останніх, включаючи Python 3.9, Python 3.10 тощо.
-У міру розвитку Python **новіші версії** мають покращену підтримку анотацій типів і в багатьох випадках вам навіть не потрібно буде імпортувати та використовувати модуль `typing` для оголошення анотацій типу.
-
-Якщо ви можете вибрати новішу версію Python для свого проекту, ви зможете скористатися цією додатковою простотою. Дивіться кілька прикладів нижче.
-
-#### List (список)
-
-Наприклад, давайте визначимо змінну, яка буде `list` із `str`.
-
-//// tab | Python 3.8 і вище
-
-З модуля `typing`, імпортуємо `List` (з великої літери `L`):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
+У міру розвитку Python **новіші версії** мають покращену підтримку цих анотацій типів і в багатьох випадках вам навіть не потрібно буде імпортувати та використовувати модуль `typing` для оголошення анотацій типів.
-Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
+Якщо ви можете вибрати новішу версію Python для свого проекту, ви зможете скористатися цією додатковою простотою.
-Як тип вкажемо `List`, який ви імпортували з `typing`.
+У всій документації є приклади, сумісні з кожною версією Python (коли є різниця).
-Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
+Наприклад, «**Python 3.6+**» означає, що це сумісно з Python 3.6 або вище (включно з 3.7, 3.8, 3.9, 3.10 тощо). А «**Python 3.9+**» означає, що це сумісно з Python 3.9 або вище (включаючи 3.10 тощо).
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
+Якщо ви можете використовувати **останні версії Python**, використовуйте приклади для останньої версії — вони матимуть **найкращий і найпростіший синтаксис**, наприклад, «**Python 3.10+**».
-////
+#### List { #list }
-//// tab | Python 3.9 і вище
+Наприклад, давайте визначимо змінну, яка буде `list` із `str`.
-Оголосимо змінну з тим самим синтаксисом двокрапки (`:`).
+Оголосіть змінну з тим самим синтаксисом двокрапки (`:`).
-Як тип вкажемо `list`.
+Як тип вкажіть `list`.
Оскільки список є типом, який містить деякі внутрішні типи, ви поміщаєте їх у квадратні дужки:
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial006_py39.py hl[1] *}
-/// info
+/// info | Інформація
-Ці внутрішні типи в квадратних дужках називаються "параметрами типу".
+Ці внутрішні типи в квадратних дужках називаються «параметрами типу».
-У цьому випадку, `str` це параметр типу переданий у `List` (або `list` у Python 3.9 і вище).
+У цьому випадку `str` — це параметр типу, переданий у `list`.
///
-Це означає: "змінна `items` це `list`, і кожен з елементів у цьому списку - `str`".
-
-/// tip
-
-Якщо ви використовуєте Python 3.9 і вище, вам не потрібно імпортувати `List` з `typing`, ви можете використовувати натомість тип `list`.
-
-///
+Це означає: «змінна `items` — це `list`, і кожен з елементів у цьому списку — `str`».
Зробивши це, ваш редактор може надати підтримку навіть під час обробки елементів зі списку:
@@ -221,95 +189,67 @@ John Doe
І все ж редактор знає, що це `str`, і надає підтримку для цього.
-#### Tuple and Set (кортеж та набір)
+#### Tuple and Set { #tuple-and-set }
Ви повинні зробити те ж саме, щоб оголосити `tuple` і `set`:
-//// tab | Python 3.8 і вище
-
-```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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial007_py39.py hl[1] *}
Це означає:
-* Змінна `items_t` це `tuple` з 3 елементами, `int`, ще `int`, та `str`.
-* Змінна `items_s` це `set`, і кожен його елемент типу `bytes`.
+* Змінна `items_t` — це `tuple` з 3 елементами: `int`, ще `int`, та `str`.
+* Змінна `items_s` — це `set`, і кожен його елемент має тип `bytes`.
-#### Dict (словник)
+#### Dict { #dict }
Щоб оголосити `dict`, вам потрібно передати 2 параметри типу, розділені комами.
-Перший параметр типу для ключа у `dict`.
+Перший параметр типу для ключів у `dict`.
-Другий параметр типу для значення у `dict`:
+Другий параметр типу для значень у `dict`:
-//// tab | Python 3.8 і вище
-
-```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!}
-```
-
-////
+{* ../../docs_src/python_types/tutorial008_py39.py hl[1] *}
Це означає:
-* Змінна `prices` це `dict`:
- * Ключі цього `dict` типу `str` (наприклад, назва кожного елементу).
- * Значення цього `dict` типу `float` (наприклад, ціна кожного елементу).
+* Змінна `prices` — це `dict`:
+ * Ключі цього `dict` мають тип `str` (скажімо, назва кожного елементу).
+ * Значення цього `dict` мають тип `float` (скажімо, ціна кожного елементу).
-#### Union (об'єднання)
+#### Union { #union }
-Ви можете оголосити, що змінна може бути будь-яким із **кількох типів**, наприклад, `int` або `str`.
+Ви можете оголосити, що змінна може бути будь-яким із **кількох типів**, наприклад `int` або `str`.
У Python 3.6 і вище (включаючи Python 3.10) ви можете використовувати тип `Union` з `typing` і вставляти в квадратні дужки можливі типи, які можна прийняти.
-У Python 3.10 також є **альтернативний синтаксис**, у якому ви можете розділити можливі типи за допомогою вертикальної смуги (`|`).
+У Python 3.10 також є **новий синтаксис**, у якому ви можете розділити можливі типи за допомогою вертикальної смуги (`|`).
-//// tab | Python 3.8 і вище
+//// tab | Python 3.10+
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial008b.py!}
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial008b_py310.py!}
```
////
-//// tab | Python 3.10 і вище
+//// tab | Python 3.9+
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial008b_py310.py!}
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial008b_py39.py!}
```
////
В обох випадках це означає, що `item` може бути `int` або `str`.
-#### Possibly `None` (Optional)
+#### Можливо `None` { #possibly-none }
Ви можете оголосити, що значення може мати тип, наприклад `str`, але також може бути `None`.
У Python 3.6 і вище (включаючи Python 3.10) ви можете оголосити його, імпортувавши та використовуючи `Optional` з модуля `typing`.
```Python hl_lines="1 4"
-{!../../docs_src/python_types/tutorial009.py!}
+{!../../docs_src/python_types/tutorial009_py39.py!}
```
Використання `Optional[str]` замість просто `str` дозволить редактору допомогти вам виявити помилки, коли ви могли б вважати, що значенням завжди є `str`, хоча насправді воно також може бути `None`.
@@ -318,103 +258,128 @@ John Doe
Це також означає, що в Python 3.10 ви можете використовувати `Something | None`:
-//// tab | Python 3.8 і вище
+//// tab | Python 3.10+
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009.py!}
+```Python hl_lines="1"
+{!> ../../docs_src/python_types/tutorial009_py310.py!}
```
////
-//// tab | Python 3.8 і вище - альтернатива
+//// tab | Python 3.9+
```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial009b.py!}
+{!> ../../docs_src/python_types/tutorial009_py39.py!}
```
////
-//// tab | Python 3.10 і вище
+//// tab | Python 3.9+ alternative
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial009_py310.py!}
+```Python hl_lines="1 4"
+{!> ../../docs_src/python_types/tutorial009b_py39.py!}
```
////
-#### Generic типи
+#### Використання `Union` або `Optional` { #using-union-or-optional }
-Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад:
+Якщо ви використовуєте версію Python нижче 3.10, ось порада з моєї дуже **суб’єктивної** точки зору:
-//// tab | Python 3.8 і вище
+* 🚨 Уникайте використання `Optional[SomeType]`
+* Натомість ✨ **використовуйте `Union[SomeType, None]`** ✨.
-* `List`
-* `Tuple`
-* `Set`
-* `Dict`
-* `Union`
-* `Optional`
-* ...та інші.
+Обидва варіанти еквівалентні й «під капотом» це одне й те саме, але я рекомендую `Union` замість `Optional`, тому що слово «**optional**» може створювати враження, ніби значення є необов’язковим, хоча насправді це означає «воно може бути `None`», навіть якщо воно не є необов’язковим і все одно є обов’язковим.
-////
+Я вважаю, що `Union[SomeType, None]` більш явно показує, що саме мається на увазі.
+
+Це лише про слова й назви. Але ці слова можуть впливати на те, як ви та ваша команда думаєте про код.
-//// tab | Python 3.9 і вище
+Як приклад, розгляньмо цю функцію:
-Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
+{* ../../docs_src/python_types/tutorial009c_py39.py hl[1,4] *}
+
+Параметр `name` визначено як `Optional[str]`, але він **не є необов’язковим**, ви не можете викликати функцію без параметра:
+
+```Python
+say_hi() # Ой, ні, це викликає помилку! 😱
+```
+
+Параметр `name` **все ще є обов’язковим** (не *optional*), тому що він не має значення за замовчуванням. Водночас `name` приймає `None` як значення:
+
+```Python
+say_hi(name=None) # Це працює, None є валідним 🎉
+```
+
+Добра новина: щойно ви перейдете на Python 3.10, вам не доведеться про це хвилюватися, адже ви зможете просто використовувати `|` для визначення об’єднань типів:
+
+{* ../../docs_src/python_types/tutorial009c_py310.py hl[1,4] *}
+
+І тоді вам не доведеться хвилюватися про назви на кшталт `Optional` і `Union`. 😎
+
+#### Generic типи { #generic-types }
+
+Ці типи, які приймають параметри типу у квадратних дужках, називаються **Generic types** or **Generics**, наприклад:
+
+//// tab | Python 3.10+
+
+Ви можете використовувати ті самі вбудовані типи як generic (з квадратними дужками та типами всередині):
* `list`
* `tuple`
* `set`
* `dict`
-І те саме, що й у Python 3.8, із модуля `typing`:
+І так само, як і в попередніх версіях Python, з модуля `typing`:
* `Union`
* `Optional`
* ...та інші.
+У Python 3.10 як альтернативу використанню generic `Union` та `Optional` ви можете використовувати вертикальну смугу (`|`) для оголошення об’єднань типів — це значно краще й простіше.
+
////
-//// tab | Python 3.10 і вище
+//// tab | Python 3.9+
-Ви можете використовувати ті самі вбудовані типи, як generic (з квадратними дужками та типами всередині):
+Ви можете використовувати ті самі вбудовані типи як generic (з квадратними дужками та типами всередині):
* `list`
* `tuple`
* `set`
* `dict`
-І те саме, що й у Python 3.8, із модуля `typing`:
+І generic з модуля `typing`:
* `Union`
-* `Optional` (так само як у Python 3.8)
+* `Optional`
* ...та інші.
-У Python 3.10, як альтернатива використанню `Union` та `Optional`, ви можете використовувати вертикальну смугу (`|`) щоб оголосити об'єднання типів.
-
////
-### Класи як типи
+### Класи як типи { #classes-as-types }
Ви також можете оголосити клас як тип змінної.
Скажімо, у вас є клас `Person` з імʼям:
-{* ../../docs_src/python_types/tutorial010.py hl[1:3] *}
-
+{* ../../docs_src/python_types/tutorial010_py39.py hl[1:3] *}
Потім ви можете оголосити змінну типу `Person`:
-{* ../../docs_src/python_types/tutorial010.py hl[6] *}
-
+{* ../../docs_src/python_types/tutorial010_py39.py hl[6] *}
І знову ж таки, ви отримуєте всю підтримку редактора:
-## Pydantic моделі
+Зверніть увагу, що це означає: «`one_person` — це **екземпляр** класу `Person`».
-Pydantic це бібліотека Python для валідації даних.
+Це не означає: «`one_person` — це **клас** з назвою `Person`».
+
+## Pydantic моделі { #pydantic-models }
+
+Pydantic — це бібліотека Python для валідації даних.
Ви оголошуєте «форму» даних як класи з атрибутами.
@@ -424,47 +389,57 @@ John Doe
І ви отримуєте всю підтримку редактора з цим отриманим об’єктом.
-Приклад з документації Pydantic:
+Приклад з офіційної документації Pydantic:
-//// tab | Python 3.8 і вище
+{* ../../docs_src/python_types/tutorial011_py310.py *}
-```Python
-{!> ../../docs_src/python_types/tutorial011.py!}
-```
+/// info | Інформація
-////
+Щоб дізнатись більше про Pydantic, перегляньте його документацію.
-//// tab | Python 3.9 і вище
+///
-```Python
-{!> ../../docs_src/python_types/tutorial011_py39.py!}
-```
+**FastAPI** повністю базується на Pydantic.
-////
+Ви побачите набагато більше цього всього на практиці в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
-//// tab | Python 3.10 і вище
+/// tip | Порада
-```Python
-{!> ../../docs_src/python_types/tutorial011_py310.py!}
-```
+Pydantic має спеціальну поведінку, коли ви використовуєте `Optional` або `Union[Something, None]` без значення за замовчуванням; детальніше про це можна прочитати в документації Pydantic про Required Optional fields.
-////
+///
-/// info
+## Підказки типів з анотаціями метаданих { #type-hints-with-metadata-annotations }
-Щоб дізнатись більше про Pydantic, перегляньте його документацію.
+У Python також є можливість додавати **додаткові метадані** до цих підказок типів за допомогою `Annotated`.
-///
+Починаючи з Python 3.9, `Annotated` є частиною стандартної бібліотеки, тож ви можете імпортувати його з `typing`.
-**FastAPI** повністю базується на Pydantic.
+{* ../../docs_src/python_types/tutorial013_py39.py hl[1,4] *}
-Ви побачите набагато більше цього всього на практиці в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
+Сам Python нічого не робить із цим `Annotated`. А для редакторів та інших інструментів тип усе ще є `str`.
+
+Але ви можете використати це місце в `Annotated`, щоб надати **FastAPI** додаткові метадані про те, як ви хочете, щоб ваш застосунок поводився.
+
+Важливо пам’ятати, що **перший *параметр типу***, який ви передаєте в `Annotated`, — це **фактичний тип**. Решта — це лише метадані для інших інструментів.
+
+Наразі вам просто потрібно знати, що `Annotated` існує і що це стандартний Python. 😎
+
+Пізніше ви побачите, наскільки **потужним** це може бути.
+
+/// tip | Порада
+
+Той факт, що це **стандартний Python**, означає, що ви й надалі отримуватимете **найкращий можливий досвід розробки** у вашому редакторі, з інструментами, які ви використовуєте для аналізу та рефакторингу коду тощо. ✨
+
+А також те, що ваш код буде дуже сумісним із багатьма іншими інструментами та бібліотеками Python. 🚀
+
+///
-## Анотації типів у **FastAPI**
+## Анотації типів у **FastAPI** { #type-hints-in-fastapi }
-**FastAPI** використовує ці підказки для виконання кількох речей.
+**FastAPI** використовує ці підказки типів для виконання кількох речей.
-З **FastAPI** ви оголошуєте параметри з підказками типу, і отримуєте:
+З **FastAPI** ви оголошуєте параметри з підказками типів, і отримуєте:
* **Підтримку редактора**.
* **Перевірку типів**.
@@ -473,17 +448,17 @@ John Doe
* **Визначення вимог**: з параметрів шляху запиту, параметрів запиту, заголовків, тіл, залежностей тощо.
* **Перетворення даних**: із запиту в необхідний тип.
-* **Перевірка даних**: що надходять від кожного запиту:
+* **Перевірки даних**: що надходять від кожного запиту:
* Генерування **автоматичних помилок**, що повертаються клієнту, коли дані недійсні.
* **Документування** API за допомогою OpenAPI:
* який потім використовується для автоматичної інтерактивної документації користувальницьких інтерфейсів.
-Все це може здатися абстрактним. Не хвилюйтеся. Ви побачите все це в дії в [Туторіал - Посібник користувача](tutorial/index.md){.internal-link target=_blank}.
+Все це може здатися абстрактним. Не хвилюйтеся. Ви побачите все це в дії в [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}.
Важливо те, що за допомогою стандартних типів Python в одному місці (замість того, щоб додавати більше класів, декораторів тощо), **FastAPI** зробить багато роботи за вас.
-/// info
+/// info | Інформація
-Якщо ви вже пройшли весь навчальний посібник і повернулися, щоб дізнатися більше про типи, ось хороший ресурс "шпаргалка" від `mypy`.
+Якщо ви вже пройшли весь туторіал і повернулися, щоб дізнатися більше про типи, ось хороший ресурс: «шпаргалка» від `mypy`.
///
diff --git a/docs/uk/docs/tutorial/background-tasks.md b/docs/uk/docs/tutorial/background-tasks.md
index 912ba8c2a..6d7804195 100644
--- a/docs/uk/docs/tutorial/background-tasks.md
+++ b/docs/uk/docs/tutorial/background-tasks.md
@@ -1,28 +1,27 @@
-# Фонові задачі
+# Фонові задачі { #background-tasks }
Ви можете створювати фонові задачі, які будуть виконуватися *після* повернення відповіді.
Це корисно для операцій, які потрібно виконати після обробки запиту, але клієнту не обов’язково чекати завершення цієї операції перед отриманням відповіді.
-Приклади використання:
+Це включає, наприклад:
* Надсилання email-сповіщень після виконання певної дії:
- * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email відправити у фоні.
+ * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email-сповіщення надіслати у фоні.
* Обробка даних:
- * Наприклад, якщо отримано файл, який потрібно обробити довготривалим процесом, можна повернути відповідь "Accepted" ("Прийнято", HTTP 202) і виконати обробку файлу у фоні.
+ * Наприклад, якщо ви отримали файл, який потрібно обробити довготривалим процесом, можна повернути відповідь «Accepted» (HTTP 202) і виконати обробку файлу у фоні.
-## Використання `BackgroundTasks`
+## Використання `BackgroundTasks` { #using-backgroundtasks }
-Спочатку імпортуйте `BackgroundTasks` і додайте його як параметр у Вашу *функцію операції шляху* (path operation function) до `BackgroundTasks`:
+Спочатку імпортуйте `BackgroundTasks` і оголосіть параметр у вашій *функції операції шляху* з анотацією типу `BackgroundTasks`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[1,13] *}
-**FastAPI** автоматично створить об'єкт `BackgroundTasks` і передасть його у цей параметр.
+**FastAPI** створить для вас об’єкт типу `BackgroundTasks` і передасть його як цей параметр.
+## Створення функції задачі { #create-a-task-function }
-## Створення функції задачі
-
-Створіть функцію, яка буде виконувати фонову задачу.
+Створіть функцію, яка буде виконуватися як фонова задача.
Це звичайна функція, яка може отримувати параметри.
@@ -32,54 +31,54 @@
І оскільки операція запису не використовує `async` та `await`, ми визначаємо функцію як звичайну `def`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[6:9] *}
-## Додавання фонової задачі
+## Додавання фонової задачі { #add-the-background-task }
-Усередині Вашої *функції обробки шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`:
+Усередині вашої *функції операції шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`:
-{* ../../docs_src/background_tasks/tutorial001.py hl[14] *}
+{* ../../docs_src/background_tasks/tutorial001_py39.py hl[14] *}
`.add_task()` приймає аргументи:
-* Функція задача, яка буде виконуватися у фоновому режимі (`write_notification`). Зверніть увагу, що передається обʼєкт без дужок.
-* Будь-яка послідовність аргументів, які потрібно передати у функцію завдання у відповідному порядку (`email`).
-* Будь-які іменовані аргументи, які потрібно передати у функцію задачу (`message="some notification"`).
+* Функцію задачі, яка буде виконуватися у фоновому режимі (`write_notification`).
+* Будь-яку послідовність аргументів, які потрібно передати у функцію задачі у відповідному порядку (`email`).
+* Будь-які іменовані аргументи, які потрібно передати у функцію задачі (`message="some notification"`).
-## Впровадження залежностей
+## Впровадження залежностей { #dependency-injection }
-Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у під залежності тощо.
+Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у підзалежності тощо.
-**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту.
+**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту:
{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *}
У цьому прикладі повідомлення будуть записані у файл `log.txt` *після* того, як відповідь буде надіслана.
-Якщо у запиті був переданий query-параметр, він буде записаний у лог у фоновій задачі.
+Якщо у запиті був переданий query, він буде записаний у лог у фоновій задачі.
-А потім інша фонова задача, яка створюється у *функції операції шляху*, запише повідомлення з використанням path параметра `email`.
+А потім інша фонова задача, згенерована у *функції операції шляху*, запише повідомлення з використанням path параметра `email`.
-## Технічні деталі
+## Технічні деталі { #technical-details }
-Клас `BackgroundTasks` походить безпосередньо з `starlette.background`.
+Клас `BackgroundTasks` походить безпосередньо з `starlette.background`.
-Він імпортується безпосередньо у FastAPI, щоб Ви могли використовувати його з `fastapi` і випадково не імпортували `BackgroundTask` (без s в кінці) з `starlette.background`.
+Він імпортується/включається безпосередньо у FastAPI, щоб ви могли імпортувати його з `fastapi` і випадково не імпортували альтернативний `BackgroundTask` (без `s` в кінці) з `starlette.background`.
Якщо використовувати лише `BackgroundTasks` (а не `BackgroundTask`), то його можна передавати як параметр у *функції операції шляху*, і **FastAPI** подбає про все інше, так само як і про використання об'єкта `Request`.
-Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього Вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його.
+Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його.
-Детальніше можна почитати в офіційній документації Starlette про фонові задачі .
+Детальніше можна почитати в офіційній документації Starlette про Background Tasks.
-## Застереження
+## Застереження { #caveat }
-Якщо Вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery.
+Якщо вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery.
-Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і навіть на кількох серверах.
+Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і особливо — на кількох серверах.
-Якщо ж Вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI** - програми або виконувати невеликі фонові завдання (наприклад, надсилати сповіщення електронною поштою), достатньо просто використовувати `BackgroundTasks`.
+Якщо ж вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI**-програми або виконувати невеликі фонові завдання (наприклад, надсилати email-сповіщення), достатньо просто використовувати `BackgroundTasks`.
-## Підсумок
+## Підсумок { #recap }
-Імпортуйте та використовуйте `BackgroundTasks` як параметр у *функціях операції шляху* та залежностях, щоб додавати фонові задачі.
+Імпортуйте та використовуйте `BackgroundTasks` як параметри у *функціях операції шляху* та залежностях, щоб додавати фонові задачі.
diff --git a/docs/uk/docs/tutorial/body-fields.md b/docs/uk/docs/tutorial/body-fields.md
index 7ddd9d104..70d94f3d6 100644
--- a/docs/uk/docs/tutorial/body-fields.md
+++ b/docs/uk/docs/tutorial/body-fields.md
@@ -1,60 +1,61 @@
-# Тіло - Поля
+# Тіло — Поля { #body-fields }
-Так само як ви можете визначати додаткову валідацію та метадані у параметрах *функції обробки шляху* за допомогою `Query`, `Path` та `Body`, ви можете визначати валідацію та метадані всередині моделей Pydantic за допомогою `Field` від Pydantic.
+Так само як ви можете оголошувати додаткову валідацію та метадані в параметрах *функції операції шляху* за допомогою `Query`, `Path` та `Body`, ви можете оголошувати валідацію та метадані всередині моделей Pydantic, використовуючи `Field` від Pydantic.
-## Імпорт `Field`
+## Імпорт `Field` { #import-field }
Спочатку вам потрібно імпортувати це:
{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}
-/// warning
-Зверніть увагу, що `Field` імпортується прямо з `pydantic`, а не з `fastapi`, як всі інші (`Query`, `Path`, `Body` тощо).
+/// warning | Попередження
+
+Зверніть увагу, що `Field` імпортується безпосередньо з `pydantic`, а не з `fastapi`, як усе інше (`Query`, `Path`, `Body` тощо).
///
-## Оголошення атрибутів моделі
+## Оголошення атрибутів моделі { #declare-model-attributes }
-Ви можете використовувати `Field` з атрибутами моделі:
+Потім ви можете використовувати `Field` з атрибутами моделі:
{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}
-`Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо.
+`Field` працює так само, як `Query`, `Path` і `Body`, має ті самі параметри тощо.
/// note | Технічні деталі
-Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic.
+Насправді `Query`, `Path` та інші, які ви побачите далі, створюють об'єкти підкласів спільного класу `Param`, який сам є підкласом класу `FieldInfo` з Pydantic.
І `Field` від Pydantic також повертає екземпляр `FieldInfo`.
-`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші підкласи, які ви побачите пізніше, що є підкласами класу Body.
+`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші, які ви побачите пізніше, що є підкласами класу `Body`.
-Пам'ятайте, що коли ви імпортуєте 'Query', 'Path' та інше з 'fastapi', вони фактично є функціями, які повертають спеціальні класи.
+Пам'ятайте, що коли ви імпортуєте `Query`, `Path` та інші з `fastapi`, це фактично функції, які повертають спеціальні класи.
///
-/// tip
+/// tip | Порада
-Зверніть увагу, що кожен атрибут моделі із типом, значенням за замовчуванням та `Field` має ту саму структуру, що й параметр *функції обробки шляху*, з `Field` замість `Path`, `Query` і `Body`.
+Зверніть увагу, що кожен атрибут моделі з типом, значенням за замовчуванням і `Field` має ту саму структуру, що й параметр *функції операції шляху*, з `Field` замість `Path`, `Query` і `Body`.
///
-## Додавання додаткової інформації
+## Додавання додаткової інформації { #add-extra-information }
-Ви можете визначити додаткову інформацію у `Field`, `Query`, `Body` тощо. І вона буде включена у згенеровану JSON схему.
+Ви можете оголошувати додаткову інформацію в `Field`, `Query`, `Body` тощо. І вона буде включена до згенерованої JSON Schema.
-Ви дізнаєтеся більше про додавання додаткової інформації пізніше у документації, коли вивчатимете визначення прикладів.
+Ви дізнаєтеся більше про додавання додаткової інформації пізніше в документації, коли вивчатимете, як оголошувати приклади.
-/// warning
+/// warning | Попередження
-Додаткові ключі, передані в `Field`, також будуть присутні у згенерованій схемі OpenAPI для вашого додатка.
-Оскільки ці ключі не обов'язково можуть бути частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад, [OpenAPI валідатор](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою.
+Додаткові ключі, передані в `Field`, також будуть присутні в отриманій схемі OpenAPI для вашого застосунку.
+Оскільки ці ключі не обов'язково є частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад [валідатор OpenAPI](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою.
///
-## Підсумок
+## Підсумок { #recap }
-Ви можете використовувати `Field` з Pydantic для визначення додаткових перевірок та метаданих для атрибутів моделі.
+Ви можете використовувати `Field` від Pydantic, щоб оголошувати додаткову валідацію та метадані для атрибутів моделі.
-Ви також можете використовувати додаткові іменовані аргументи для передачі додаткових метаданих JSON схеми.
+Ви також можете використовувати додаткові keyword arguments, щоб передавати додаткові метадані JSON Schema.
diff --git a/docs/uk/docs/tutorial/body-multiple-params.md b/docs/uk/docs/tutorial/body-multiple-params.md
index e2acf8a70..dc9a768c3 100644
--- a/docs/uk/docs/tutorial/body-multiple-params.md
+++ b/docs/uk/docs/tutorial/body-multiple-params.md
@@ -1,24 +1,24 @@
-# Тіло запиту - Декілька параметрів
+# Тіло - Декілька параметрів { #body-multiple-parameters }
-Тепер, коли ми розглянули використання `Path` та `Query`, розгляньмо більш просунуті способи оголошення тіла запиту в **FastAPI**.
+Тепер, коли ми побачили, як використовувати `Path` і `Query`, розгляньмо більш просунуті варіанти оголошення тіла запиту.
-## Змішування `Path`, `Query` та параметрів тіла запиту
+## Змішування `Path`, `Query` та параметрів тіла { #mix-path-query-and-body-parameters }
-По-перше, звісно, Ви можете вільно змішувати оголошення параметрів `Path`, `Query` та тіла запиту, і **FastAPI** правильно їх обробить.
+По-перше, звісно, ви можете вільно змішувати оголошення параметрів `Path`, `Query` та тіла запиту, і **FastAPI** знатиме, що робити.
-Також Ви можете оголосити параметри тіла як необов’язкові, встановивши для них значення за замовчуванням `None`:
+Також ви можете оголошувати параметри тіла як необов’язкові, встановивши для них значення за замовчуванням `None`:
{* ../../docs_src/body_multiple_params/tutorial001_an_py310.py hl[18:20] *}
/// note | Примітка
-Зверніть увагу, що в цьому випадку параметр `item`, який береться з тіла запиту, є необов'язковим, оскільки має значення за замовчуванням `None`.
+Зверніть увагу, що в цьому випадку параметр `item`, який береться з тіла, є необов'язковим. Оскільки має значення за замовчуванням `None`.
///
-## Декілька параметрів тіла запиту
+## Декілька параметрів тіла { #multiple-body-parameters }
-У попередньому прикладі *операція шляху* очікувала JSON з атрибутами `Item`, наприклад:
+У попередньому прикладі *операції шляху* очікували б JSON-тіло з атрибутами `Item`, наприклад:
```JSON
{
@@ -28,13 +28,15 @@
"tax": 3.2
}
```
-Але Ви також можете оголосити декілька параметрів тіла, наприклад `item` та `user`:
+
+Але ви також можете оголосити декілька параметрів тіла, наприклад `item` та `user`:
{* ../../docs_src/body_multiple_params/tutorial002_py310.py hl[20] *}
-У цьому випадку **FastAPI** розпізнає, що є кілька параметрів тіла (два параметри є моделями Pydantic).
-Тому він використає назви параметрів як ключі (назви полів) у тілі запиту, очікуючи:
+У цьому випадку **FastAPI** помітить, що у функції є більше ніж один параметр тіла (є два параметри, які є моделями Pydantic).
+
+Тож він використає назви параметрів як ключі (назви полів) у тілі та очікуватиме тіло такого вигляду:
```JSON
{
@@ -53,27 +55,28 @@
/// note | Примітка
-Зверніть увагу, що хоча `item` оголошено, так само як і раніше, тепер він очікується в тілі під ключем `item`.
+Зверніть увагу, що хоча `item` оголошено так само, як і раніше, тепер він очікується всередині тіла з ключем `item`.
///
-**FastAPI** автоматично конвертує дані із запиту таким чином, щоб параметр `item` отримав свій вміст, і те ж саме стосується `user`.
+**FastAPI** виконає автоматичне перетворення із запиту, щоб параметр `item` отримав свій конкретний вміст, і те ж саме для `user`.
-Він виконає валідацію складених даних і задокументує їх відповідним чином у схемі OpenAPI та в автоматичній документації.
+Він виконає валідацію складених даних і задокументує це таким чином у схемі OpenAPI та в автоматичній документації.
-## Одиничні значення в тілі запиту
+## Одиничні значення в тілі { #singular-values-in-body }
Так само як є `Query` і `Path` для визначення додаткових даних для параметрів запиту та шляху, **FastAPI** надає еквівалентний `Body`.
-Наприклад, розширюючи попередню модель, Ви можете вирішити додати ще один ключ `importance` в те ж саме тіло запиту разом із `item` і `user`.
+Наприклад, розширивши попередню модель, ви можете вирішити додати ще один ключ `importance` у те саме тіло, окрім `item` і `user`.
-Якщо Ви оголосите його як є, то, оскільки це одиничне значення, **FastAPI** припускатиме, що це параметр запиту (query parameter).
+Якщо оголосити його як є, оскільки це одиничне значення, **FastAPI** припустить, що це параметр запиту.
-Але Ви можете вказати **FastAPI** обробляти його як інший ключ тіла (body key), використовуючи `Body`:
+Але ви можете вказати **FastAPI** обробляти його як інший ключ тіла, використовуючи `Body`:
{* ../../docs_src/body_multiple_params/tutorial003_an_py310.py hl[23] *}
-У цьому випадку **FastAPI** очікуватиме тіло запиту у такому вигляді:
+
+У цьому випадку **FastAPI** очікуватиме тіло такого вигляду:
```JSON
{
@@ -90,19 +93,20 @@
"importance": 5
}
```
-Знову ж таки, **FastAPI** конвертуватиме типи даних, перевірятиме їх, створюватиме документацію тощо.
-## Декілька body та query параметрів
+Знову ж таки, він перетворюватиме типи даних, перевірятиме, документуватиме тощо.
-Звісно, Ви можете оголошувати додаткові query параметри запиту, коли це необхідно, на додаток до будь-яких параметрів тіла запиту.
+## Декілька параметрів тіла та query { #multiple-body-params-and-query }
-Оскільки за замовчуванням окремі значення інтерпретуються як параметри запиту, Вам не потрібно явно додавати `Query`, можна просто використати:
+Звісно, ви також можете оголошувати додаткові query параметри щоразу, коли це потрібно, додатково до будь-яких параметрів тіла.
+
+Оскільки за замовчуванням одиничні значення інтерпретуються як параметри запиту, вам не потрібно явно додавати `Query`, ви можете просто зробити:
```Python
q: Union[str, None] = None
```
-Або в Python 3.10 та вище:
+Або в Python 3.10 і вище:
```Python
q: str | None = None
@@ -115,17 +119,17 @@ q: str | None = None
/// info | Інформація
-`Body` також має ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які Ви побачите пізніше.
+`Body` також має всі ті самі додаткові параметри валідації та метаданих, що й `Query`, `Path` та інші, які ви побачите пізніше.
///
-## Вкладений поодинокий параметр тіла запиту
+## Вбудувати один параметр тіла { #embed-a-single-body-parameter }
-Припустимо, у вас є лише один параметр тіла запиту `item` з моделі Pydantic `Item`.
+Скажімо, у вас є лише один параметр тіла `item` з моделі Pydantic `Item`.
-За замовчуванням **FastAPI** очікуватиме, що тіло запиту міститиме вміст безпосередньо.
+За замовчуванням **FastAPI** очікуватиме його тіло безпосередньо.
-Але якщо Ви хочете, щоб він очікував JSON з ключем `item`, а всередині — вміст моделі (так, як це відбувається при оголошенні додаткових параметрів тіла), Ви можете використати спеціальний параметр `Body` — `embed`:
+Але якщо ви хочете, щоб він очікував JSON з ключем `item`, а всередині нього — вміст моделі, як це відбувається, коли ви оголошуєте додаткові параметри тіла, ви можете використати спеціальний параметр `Body` — `embed`:
```Python
item: Item = Body(embed=True)
@@ -135,7 +139,8 @@ item: Item = Body(embed=True)
{* ../../docs_src/body_multiple_params/tutorial005_an_py310.py hl[17] *}
-У цьому випадку **FastAPI** очікуватиме тіло запиту такого вигляду:
+
+У цьому випадку **FastAPI** очікуватиме тіло такого вигляду:
```JSON hl_lines="2"
{
@@ -159,12 +164,12 @@ item: Item = Body(embed=True)
}
```
-## Підсумок
+## Підсумок { #recap }
-Ви можете додавати кілька параметрів тіла до Вашої *функції операції шляху* (*path operation function*), навіть якщо запит може мати лише одне тіло.
+Ви можете додавати кілька параметрів тіла до вашої *функції операції шляху*, навіть якщо запит може мати лише одне тіло.
-Але **FastAPI** обробить це, надасть Вам потрібні дані у функції, перевірить їх та задокументує коректну схему в *операції шляху*.
+Але **FastAPI** обробить це, надасть вам правильні дані у функції та перевірить і задокументує правильну схему в *операції шляху*.
-Також Ви можете оголошувати окремі значення, які будуть отримані як частина тіла запиту.
+Також ви можете оголошувати одиничні значення, щоб отримувати їх як частину тіла.
-Крім того, Ви можете вказати **FastAPI** вбудовувати тіло в ключ, навіть якщо оголошено лише один параметр.
+І ви можете вказати **FastAPI** вбудовувати тіло в ключ, навіть коли оголошено лише один параметр.
diff --git a/docs/uk/docs/tutorial/body-nested-models.md b/docs/uk/docs/tutorial/body-nested-models.md
index abc33f2eb..6d0669358 100644
--- a/docs/uk/docs/tutorial/body-nested-models.md
+++ b/docs/uk/docs/tutorial/body-nested-models.md
@@ -1,8 +1,8 @@
-# Тіло запиту - Вкладені моделі
+# Тіло - Вкладені моделі { #body-nested-models }
-З **FastAPI** Ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic).
+З **FastAPI** ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic).
-## Поля списку
+## Поля списку { #list-fields }
Ви можете визначити атрибут як підтип. Наприклад, Python-список (`list`):
@@ -10,47 +10,28 @@
Це зробить `tags` списком, хоча не визначається тип елементів списку.
-## Поля списку з параметром типу
+## Поля списку з параметром типу { #list-fields-with-type-parameter }
-Але Python має специфічний спосіб оголошення списків з внутрішніми типами або "параметрами типу":
-### Імпортуємо `List` з модуля typing
+Але Python має специфічний спосіб оголошення списків з внутрішніми типами або «параметрами типу»:
-У Python 3.9 і вище можна використовувати стандартний `list` для оголошення таких типів, як ми побачимо нижче. 💡
+### Оголошення `list` з параметром типу { #declare-a-list-with-a-type-parameter }
-Але в 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 це буде виглядати так:
+Щоб оголосити типи з параметрами типу (внутрішніми типами), такими як `list`, `dict`, `tuple`,
+передайте внутрішні тип(и) як «параметри типу», використовуючи квадратні дужки: `[` and `]`
```Python
my_list: list[str]
```
-У версіях Python до 3.9 це виглядає так:
-
-```Python
-from typing import List
-
-my_list: List[str]
-```
-
Це стандартний синтаксис Python для оголошення типів.
Використовуйте той самий стандартний синтаксис для атрибутів моделей з внутрішніми типами.
-Отже, у нашому прикладі, ми можемо зробити `tags` саме "списком рядків":
+Отже, у нашому прикладі, ми можемо зробити `tags` саме «списком рядків»:
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## Типи множин
+## Типи множин { #set-types }
Але потім ми подумали, що теги не повинні повторюватися, вони, ймовірно, повинні бути унікальними рядками.
@@ -60,29 +41,29 @@ my_list: List[str]
{* ../../docs_src/body_nested_models/tutorial003_py310.py hl[12] *}
-Навіть якщо Ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів.
+Навіть якщо ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів.
-І коли Ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів.
+І коли ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів.
І це буде анотовано/документовано відповідно.
-## Вкладені моделі
+## Вкладені моделі { #nested-models }
Кожен атрибут моделі Pydantic має тип.
Але цей тип сам може бути іншою моделлю Pydantic.
-Отже, Ви можете оголосити глибоко вкладені JSON "об'єкти" з конкретними іменами атрибутів, типами та перевірками.
+Отже, ви можете оголосити глибоко вкладені JSON «об'єкти» з конкретними іменами атрибутів, типами та перевірками.
Усе це, вкладене без обмежень.
-### Визначення підмоделі
+### Визначення підмоделі { #define-a-submodel }
Наприклад, ми можемо визначити модель `Image`:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### Використання підмоделі як типу
+### Використання підмоделі як типу { #use-the-submodel-as-a-type }
А потім ми можемо використовувати її як тип атрибута:
@@ -104,16 +85,16 @@ my_list: List[str]
}
```
-Завдяки такій декларації у **FastAPI** Ви отримуєте:
+Завдяки такій декларації у **FastAPI** ви отримуєте:
* Підтримку в редакторі (автозавершення тощо), навіть для вкладених моделей
* Конвертацію даних
* Валідацію даних
* Автоматичну документацію
-## Спеціальні типи та валідація
+## Спеціальні типи та валідація { #special-types-and-validation }
-Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. Ви можете використовувати складніші типи, які наслідують `str`.
+Окрім звичайних типів, таких як `str`, `int`, `float`, та ін. ви можете використовувати складніші типи, які наслідують `str`.
Щоб побачити всі доступні варіанти, ознайомтеся з оглядом типів у Pydantic. Деякі приклади будуть у наступних розділах.
@@ -123,9 +104,9 @@ my_list: List[str]
Рядок буде перевірено як дійсну URL-адресу і задокументовано в JSON Schema / OpenAPI як URL.
-## Атрибути зі списками підмоделей
+## Атрибути зі списками підмоделей { #attributes-with-lists-of-submodels }
-У Pydantic Ви можете використовувати моделі як підтипи для `list`, `set` тощо:
+У Pydantic ви можете використовувати моделі як підтипи для `list`, `set` тощо:
{* ../../docs_src/body_nested_models/tutorial006_py310.py hl[18] *}
@@ -161,7 +142,7 @@ my_list: List[str]
///
-## Глибоко вкладені моделі
+## Глибоко вкладені моделі { #deeply-nested-models }
Ви можете визначати вкладені моделі довільної глибини:
@@ -173,14 +154,9 @@ my_list: List[str]
///
-## Тіла запитів, що складаються зі списків
+## Тіла запитів, що складаються зі списків { #bodies-of-pure-lists }
-Якщо верхній рівень JSON тіла, яке Ви очікуєте, є JSON `масивом` (у Python — `list`), Ви можете оголосити тип у параметрі функції, як і в моделях Pydantic:
-
-```Python
-images: List[Image]
-```
-або в Python 3.9 і вище:
+Якщо верхній рівень JSON тіла, яке ви очікуєте, є JSON `масивом` (у Python — `list`), ви можете оголосити тип у параметрі функції, як і в моделях Pydantic:
```Python
images: list[Image]
@@ -190,7 +166,7 @@ images: list[Image]
{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## Підтримка в редакторі всюди
+## Підтримка в редакторі всюди { #editor-support-everywhere }
Ви отримаєте підтримку в редакторі всюди.
@@ -200,23 +176,23 @@ images: list[Image]
Ви не змогли б отримати таку підтримку в редакторі, якби працювали напряму зі `dict`, а не з моделями Pydantic.
-Але Вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON.
+Але вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON.
-## Тіла з довільними `dict`
+## Тіла з довільними `dict` { #bodies-of-arbitrary-dicts }
Ви також можете оголосити тіло як `dict` з ключами одного типу та значеннями іншого типу.
-Це корисно, якщо Ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic).
+Це корисно, якщо ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic).
-Це буде корисно, якщо Ви хочете приймати ключі, які заздалегідь невідомі.
+Це буде корисно, якщо ви хочете приймати ключі, які заздалегідь невідомі.
---
-Це також зручно, якщо Ви хочете мати ключі іншого типу (наприклад, `int`).
+Це також зручно, якщо ви хочете мати ключі іншого типу (наприклад, `int`).
Ось що ми розглянемо далі.
-У цьому випадку Ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`:
+У цьому випадку ви можете приймати будь-який `dict`, якщо його ключі — це `int`, а значення — `float`:
{* ../../docs_src/body_nested_models/tutorial009_py39.py hl[7] *}
@@ -228,18 +204,18 @@ images: list[Image]
Це означає, що навіть якщо клієнти вашого API надсилатимуть ключі у вигляді рядків, якщо вони містять цілі числа, Pydantic конвертує їх і проведе валідацію.
-Тобто `dict`, який Ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`.
+Тобто `dict`, який ви отримаєте як `weights`, матиме ключі типу `int` та значення типу `float`.
///
-## Підсумок
+## Підсумок { #recap }
-З **FastAPI** Ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним.
+З **FastAPI** ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним.
А також отримуєте всі переваги:
* Підтримка в редакторі (автодоповнення всюди!)
* Конвертація даних (парсинг/сериалізація)
-* Валідація даних
+* Валідацію даних
* Документація схем
* Автоматичне створення документації
diff --git a/docs/uk/docs/tutorial/body-updates.md b/docs/uk/docs/tutorial/body-updates.md
index e78b5a5bf..2ae68291c 100644
--- a/docs/uk/docs/tutorial/body-updates.md
+++ b/docs/uk/docs/tutorial/body-updates.md
@@ -1,8 +1,8 @@
-# Тіло – Оновлення
+# Тіло — Оновлення { #body-updates }
-## Оновлення з використанням `PUT`
+## Оновлення із заміною за допомогою `PUT` { #update-replacing-with-put }
-Щоб оновити елемент, Ви можете використати HTTP `PUT` операцію.
+Щоб оновити елемент, ви можете використати HTTP `PUT` операцію.
Ви можете використати `jsonable_encoder`, щоб перетворити вхідні дані на такі, які можна зберігати як JSON (наприклад, у NoSQL базі даних). Наприклад, перетворюючи `datetime` у `str`.
@@ -10,7 +10,7 @@
`PUT` використовується для отримання даних, які мають замінити чинні дані.
-### Попередження про заміну
+### Попередження про заміну { #warning-about-replacing }
Це означає, що якщо Ви хочете оновити елемент `bar`, використовуючи `PUT` з тілом:
@@ -26,7 +26,7 @@
І дані будуть збережені з цим "новим" значенням `tax` = `10.5`.
-## Часткові оновлення з `PATCH`
+## Часткові оновлення з `PATCH` { #partial-updates-with-patch }
Ви також можете використовувати операцію HTTP `PATCH` для *часткового* оновлення даних.
@@ -34,53 +34,37 @@
/// note | Примітка
-`PATCH` менш відомий і рідше використовується, ніж `PUT`.
+`PATCH` менш поширений і менш відомий, ніж `PUT`.
І багато команд використовують лише `PUT`, навіть для часткових оновлень.
-Ви **вільні** використовувати їх так, як хочете, **FastAPI** не накладає обмежень.
+Ви **вільні** використовувати їх так, як хочете, **FastAPI** не накладає жодних обмежень.
-Але цей посібник показує Вам більш-менш як їх задумано використовувати.
+Але цей посібник показує вам, більш-менш, як їх задумано використовувати.
///
-### Використання параметра `exclude_unset` у Pydantic
+### Використання параметра `exclude_unset` у Pydantic { #using-pydantics-exclude-unset-parameter }
-Якщо Ви хочете отримати часткові оновлення, дуже зручно використовувати параметр `exclude_unset` у методі `.model_dump()` моделі Pydantic.
+Якщо Ви хочете отримувати часткові оновлення, дуже корисно використовувати параметр `exclude_unset` у `.model_dump()` моделі Pydantic.
Наприклад: `item.model_dump(exclude_unset=True)`.
-/// info | Інформація
+Це згенерує `dict` лише з тими даними, які були встановлені під час створення моделі `item`, виключаючи значення за замовчуванням.
-У Pydantic v1 цей метод називався `.dict()`, він був застарілий (але все ще підтримується) у Pydantic v2, і був перейменований у `.model_dump()`.
-
-Приклади тут використовують `.dict()` для сумісності з Pydantic v1, але Вам слід використовувати `.model_dump()`, якщо можете використовувати Pydantic v2.
-
-///
-
-Це створить `dict` лише з тими даними, які були явно встановлені під час створення моделі `item`, виключаючи значення за замовчуванням.
-
-Тоді Ви можете використовувати це, щоб створити `dict` лише з даними, які були встановлені (надіслані у запиті), пропускаючи значення за замовчуванням:
+Тоді Ви можете використовувати це, щоб згенерувати `dict` лише з даними, які були встановлені (надіслані у запиті), пропускаючи значення за замовчуванням:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
-### Використання параметра `update` у Pydantic
+### Використання параметра `update` у Pydantic { #using-pydantics-update-parameter }
-Тепер Ви можете створити копію наявної моделі за допомогою `.model_copy()`, і передати параметр `update` з `dict` , який містить дані для оновлення.
-
-/// info | Інформація
-
-У Pydantic v1 метод називався `.copy()`, він був застарілий (але все ще підтримується) у Pydantic v2, і був перейменований у `.model_copy()`.
-
-Приклади тут використовують `.copy()` для сумісності з Pydantic v1, але якщо Ви можете використовувати Pydantic v2 — Вам слід використовувати `.model_copy()` замість цього.
-
-///
+Тепер Ви можете створити копію наявної моделі за допомогою `.model_copy()`, і передати параметр `update` з `dict`, який містить дані для оновлення.
Наприклад: `stored_item_model.model_copy(update=update_data)`:
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
-### Підсумок часткових оновлень
+### Підсумок часткових оновлень { #partial-updates-recap }
У підсумку, щоб застосувати часткові оновлення, Ви:
@@ -101,7 +85,7 @@
Насправді Ви можете використовувати цю саму техніку і з операцією HTTP `PUT`.
-Але приклад тут використовує `PATCH`, тому що він був створений саме для таких випадків.
+Але приклад тут використовує `PATCH`, тому що він був створений для таких випадків.
///
@@ -109,7 +93,7 @@
Зверніть увагу, що модель запиту все ще проходить валідацію.
-Тож, якщо Ви хочете отримувати часткові оновлення, які можуть не містити жодного атрибута, Вам потрібно мати модель, де всі атрибути позначені як необов’язкові (зі значеннями за замовчуванням або `None`).
+Тож, якщо Ви хочете отримувати часткові оновлення, які можуть пропускати всі атрибути, Вам потрібно мати модель, де всі атрибути позначені як необов’язкові (зі значеннями за замовчуванням або `None`).
Щоб розрізняти моделі з усіма необов’язковими значеннями для **оновлення** і моделі з обов’язковими значеннями для **створення**, Ви можете скористатись ідеями, описаними у [Додаткові моделі](extra-models.md){.internal-link target=_blank}.
diff --git a/docs/uk/docs/tutorial/body.md b/docs/uk/docs/tutorial/body.md
index 38fed7bb8..ca1f308ab 100644
--- a/docs/uk/docs/tutorial/body.md
+++ b/docs/uk/docs/tutorial/body.md
@@ -1,14 +1,14 @@
-# Тіло запиту
+# Тіло запиту { #request-body }
Коли вам потрібно надіслати дані з клієнта (скажімо, браузера) до вашого API, ви надсилаєте їх як **тіло запиту**.
Тіло **запиту** — це дані, надіслані клієнтом до вашого API. Тіло **відповіді** — це дані, які ваш API надсилає клієнту.
-Ваш API майже завжди має надсилати тіло **відповіді**. Але клієнтам не обов’язково потрібно постійно надсилати тіла **запитів**.
+Ваш API майже завжди має надсилати тіло **відповіді**. Але клієнтам не обов’язково потрібно постійно надсилати тіла **запитів** — інколи вони лише запитують шлях, можливо з деякими параметрами запиту, але не надсилають тіло.
Щоб оголосити тіло **запиту**, ви використовуєте Pydantic моделі з усією їх потужністю та перевагами.
-/// info
+/// info | Інформація
Щоб надіслати дані, ви повинні використовувати один із: `POST` (більш поширений), `PUT`, `DELETE` або `PATCH`.
@@ -18,21 +18,22 @@
///
-## Імпортуйте `BaseModel` від Pydantic
+## Імпортуйте `BaseModel` від Pydantic { #import-pydantics-basemodel }
Спочатку вам потрібно імпортувати `BaseModel` з `pydantic`:
-{* ../../docs_src/body/tutorial001.py hl[4] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## Створіть свою модель даних
+## Створіть свою модель даних { #create-your-data-model }
Потім ви оголошуєте свою модель даних як клас, який успадковується від `BaseModel`.
Використовуйте стандартні типи Python для всіх атрибутів:
-{* ../../docs_src/body/tutorial001.py hl[7:11] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[5:9] *}
-Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте `None`, щоб зробити його необов'язковим.
+
+Так само, як і при оголошенні параметрів запиту, коли атрибут моделі має значення за замовчуванням, він не є обов’язковим. В іншому випадку це потрібно. Використовуйте `None`, щоб зробити його просто необов'язковим.
Наприклад, ця модель вище оголошує JSON "`об'єкт`" (або Python `dict`), як:
@@ -54,15 +55,15 @@
}
```
-## Оголоси її як параметр
+## Оголосіть її як параметр { #declare-it-as-a-parameter }
Щоб додати модель даних до вашої *операції шляху*, оголосіть її так само, як ви оголосили параметри шляху та запиту:
-{* ../../docs_src/body/tutorial001.py hl[18] *}
+{* ../../docs_src/body/tutorial001_py310.py hl[16] *}
...і вкажіть її тип як модель, яку ви створили, `Item`.
-## Результати
+## Результати { #results }
Лише з цим оголошенням типу Python **FastAPI** буде:
@@ -73,9 +74,9 @@
* Надавати отримані дані у параметрі `item`.
* Оскільки ви оголосили його у функції як тип `Item`, ви також матимете всю підтримку редактора (автозаповнення, тощо) для всіх атрибутів та їх типів.
* Генерувати JSON Schema визначення для вашої моделі, ви також можете використовувати їх де завгодно, якщо це має сенс для вашого проекту.
-* Ці схеми будуть частиною згенерованої схеми OpenAPI і використовуватимуться автоматичною документацією інтерфейсу користувача.
+* Ці схеми будуть частиною згенерованої схеми OpenAPI і використовуватимуться автоматичною документацією UIs.
-## Автоматична документація
+## Автоматична документація { #automatic-docs }
Схеми JSON ваших моделей будуть частиною вашої схеми, згенерованої OpenAPI, і будуть показані в інтерактивній API документації:
@@ -85,7 +86,7 @@
-## Підтримка редактора
+## Підтримка редактора { #editor-support }
У вашому редакторі, всередині вашої функції, ви будете отримувати підказки типу та завершення скрізь (це б не сталося, якби ви отримали `dict` замість моделі Pydantic):
@@ -107,7 +108,7 @@
-/// tip
+/// tip | Порада
Якщо ви використовуєте PyCharm як ваш редактор, ви можете використати Pydantic PyCharm Plugin.
@@ -121,42 +122,45 @@
///
-## Використовуйте модель
+## Використовуйте модель { #use-the-model }
Усередині функції ви можете отримати прямий доступ до всіх атрибутів об’єкта моделі:
-{* ../../docs_src/body/tutorial002.py hl[21] *}
+{* ../../docs_src/body/tutorial002_py310.py *}
-## Тіло запиту + параметри шляху
+## Тіло запиту + параметри шляху { #request-body-path-parameters }
Ви можете одночасно оголошувати параметри шляху та тіло запиту.
**FastAPI** розпізнає, що параметри функції, які відповідають параметрам шляху, мають бути **взяті з шляху**, а параметри функції, які оголошуються як моделі Pydantic, **взяті з тіла запиту**.
-{* ../../docs_src/body/tutorial003.py hl[17:18] *}
+{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
+
-## Тіло запиту + шлях + параметри запиту
+## Тіло запиту + шлях + параметри запиту { #request-body-path-query-parameters }
Ви також можете оголосити параметри **тіло**, **шлях** і **запит** одночасно.
**FastAPI** розпізнає кожен з них і візьме дані з потрібного місця.
-{* ../../docs_src/body/tutorial004.py hl[18] *}
+{* ../../docs_src/body/tutorial004_py310.py hl[16] *}
Параметри функції будуть розпізнаватися наступним чином:
* Якщо параметр також оголошено в **шляху**, він використовуватиметься як параметр шляху.
* Якщо параметр має **сингулярний тип** (наприклад, `int`, `float`, `str`, `bool` тощо), він буде інтерпретуватися як параметр **запиту**.
-* Якщо параметр оголошується як тип **Pydantic моделі**, він інтерпретується як **тіло** запиту.
+* Якщо параметр оголошується як тип **Pydantic моделі**, він інтерпретується як **тіло** **запиту**.
+
+/// note | Примітка
-/// note
+FastAPI буде знати, що значення `q` не є обов'язковим через значення за замовчуванням `= None`.
-FastAPI буде знати, що значення "q" не є обов'язковим через значення за замовчуванням "= None".
+`str | None` (Python 3.10+) або `Union` у `Union[str, None]` (Python 3.9+) FastAPI не використовує, щоб визначити, що значення не є обов’язковим — він знатиме, що воно не є обов’язковим, тому що має значення за замовчуванням `= None`.
-`Optional` у `Optional[str]` не використовується FastAPI, але дозволить вашому редактору надати вам кращу підтримку та виявляти помилки.
+Але додавання анотацій типів дозволить вашому редактору надати вам кращу підтримку та виявляти помилки.
///
-## Без Pydantic
+## Без Pydantic { #without-pydantic }
-Якщо ви не хочете використовувати моделі Pydantic, ви також можете використовувати параметри **Body**. Перегляньте документацію для [Тіло – Кілька параметрів: сингулярні значення в тілі](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
+Якщо ви не хочете використовувати моделі Pydantic, ви також можете використовувати параметри **Body**. Перегляньте документацію для [Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
diff --git a/docs/uk/docs/tutorial/cookie-param-models.md b/docs/uk/docs/tutorial/cookie-param-models.md
index f070b6ac8..3c6407716 100644
--- a/docs/uk/docs/tutorial/cookie-param-models.md
+++ b/docs/uk/docs/tutorial/cookie-param-models.md
@@ -1,32 +1,32 @@
-# Моделі для Cookie-параметрів
+# Моделі параметрів Cookie { #cookie-parameter-models }
-Якщо у Вас є група **cookies** параметрів, які пов'язані між собою, Ви можете створити **Pydantic-модель**, щоб оголосити їх. 🍪
+Якщо у Вас є група **cookies**, які пов'язані між собою, Ви можете створити **Pydantic-модель**, щоб оголосити їх. 🍪
Це дозволить Вам повторно **використовувати модель** у **різних місцях**, а також оголосити валідацію та метадані для всіх параметрів одночасно. 😎
-/// note | Нотатки
+/// note | Примітка
-Це підтримується з версії FastAPI `0.115.0`. 🤓
+Це підтримується з версії FastAPI `0.115.0`. 🤓
///
/// tip | Порада
-Ця ж техніка застосовується до `Query`, `Cookie`, та `Header`. 😎
+Ця ж техніка застосовується до `Query`, `Cookie` та `Header`. 😎
///
-## Cookie з Pydantic-моделлю
+## Cookie з Pydantic-моделлю { #cookies-with-a-pydantic-model }
-Оголосіть **cookie-параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть параметр як `Cookie`:
+Оголосіть **cookie**-параметри, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть параметр як `Cookie`:
{* ../../docs_src/cookie_param_models/tutorial001_an_py310.py hl[9:12,16] *}
-**FastAPI** буде **витягувати** дані для **кожного поля** з **cookie** параметрів, отриманих у запиті, і передавати Вам Pydantic-модель, яку Ви визначили.
+**FastAPI** буде **витягувати** дані для **кожного поля** з **cookies**, отриманих у запиті, і передавати Вам Pydantic-модель, яку Ви визначили.
-## Перевірка у документації
+## Перевірка у документації { #check-the-docs }
-Ви можете побачити визначені cookie в інтерфейсі документації за адресою `/docs`:
+Ви можете побачити визначені cookies в інтерфейсі документації за адресою `/docs`:
@@ -34,29 +34,29 @@
/// info | Інформація
-Майте на увазі, що оскільки **браузери обробляють cookie** особливим чином і "за лаштунками", вони **не** дозволяють **JavaScript** легко з ними працювати.
+Майте на увазі, що оскільки **браузери обробляють cookies** особливим чином і «за лаштунками», вони **не** дозволяють **JavaScript** легко з ними працювати.
-Якщо Ви зайдете до **інтерфейсу документації API** за адресою `/docs`, Ви зможете побачити **документацію** для cookie у Ваших **операціях шляху**.
+Якщо Ви зайдете до **інтерфейсу документації API** за адресою `/docs`, Ви зможете побачити **документацію** для cookies у Ваших *операціях шляху*.
-Але навіть якщо Ви заповните дані й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookie не будуть відправлені, і Ви побачите **помилку**, ніби Ви не ввели жодних значень.
+Але навіть якщо Ви заповните дані й натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не будуть відправлені, і Ви побачите **помилку**, ніби Ви не ввели жодних значень.
///
-## Заборона додаткових cookie
+## Заборона додаткових cookie { #forbid-extra-cookies }
-У деяких спеціальних випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** список cookie, які хочете отримувати.
+У деяких спеціальних випадках (ймовірно, не дуже поширених) Ви можете захотіти **обмежити** cookies, які хочете отримувати.
-Ваша API тепер має можливість контролювати власну згоду на cookie. 🤪🍪
+Ваша API тепер має можливість контролювати власну згоду на cookie. 🤪🍪
-Ви можете використовувати налаштування моделі Pydantic, щоб `заборонити` будь-які `додаткові` поля:
+Ви можете використовувати налаштування моделі Pydantic, щоб `forbid` будь-які `extra` поля:
-{* ../../docs_src/cookie_param_models/tutorial002_an_py39.py hl[10] *}
+{* ../../docs_src/cookie_param_models/tutorial002_an_py310.py hl[10] *}
-Якщо клієнт спробує надіслати якісь **додаткові cookie**, він отримає відповідь з **помилкою**.
+Якщо клієнт спробує надіслати якісь **додаткові cookies**, він отримає відповідь з **помилкою**.
-Бідні банери cookie, які так старанно намагаються отримати Вашу згоду, щоб API її відхилила. 🍪
+Бідні банери cookie, які так старанно намагаються отримати Вашу згоду, щоб API її відхилила. 🍪
-Наприклад, якщо клієнт спробує надіслати cookie `santa_tracker` зі значенням `good-list-please`, він отримає відповідь з помилкою, яка повідомить, що cookie `santa_tracker` не дозволено:
+Наприклад, якщо клієнт спробує надіслати cookie `santa_tracker` зі значенням `good-list-please`, він отримає відповідь з помилкою, яка повідомить, що `santa_tracker` cookie не дозволено:
```json
{
@@ -71,6 +71,6 @@
}
```
-## Підсумок
+## Підсумок { #summary }
-Ви можете використовувати **Pydantic-моделі** для оголошення cookie у FastAPI. 😎
+Ви можете використовувати **Pydantic-моделі** для оголошення **cookies** у **FastAPI**. 😎
diff --git a/docs/uk/docs/tutorial/cookie-params.md b/docs/uk/docs/tutorial/cookie-params.md
index b320645cb..8a5b44e8a 100644
--- a/docs/uk/docs/tutorial/cookie-params.md
+++ b/docs/uk/docs/tutorial/cookie-params.md
@@ -1,24 +1,25 @@
-# Параметри Cookie
+# Параметри Cookie { #cookie-parameters }
-Ви можете визначити параметри Cookie таким же чином, як визначаються параметри `Query` і `Path`.
+Ви можете визначати параметри Cookie таким же чином, як визначаються параметри `Query` і `Path`.
-## Імпорт `Cookie`
+## Імпорт `Cookie` { #import-cookie }
Спочатку імпортуйте `Cookie`:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## Визначення параметрів `Cookie`
+## Визначення параметрів `Cookie` { #declare-cookie-parameters }
Потім визначте параметри cookie, використовуючи таку ж конструкцію як для `Path` і `Query`.
-Перше значення це значення за замовчуванням, ви можете також передати всі додаткові параметри валідації чи анотації:
+Ви можете визначити значення за замовчуванням, а також усі додаткові параметри валідації чи анотації:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[9] *}
-/// note | Технічні Деталі
+/// note | Технічні деталі
+
+`Cookie` це "сестра" класів `Path` і `Query`. Вони також наслідуються від одного спільного класу `Param`.
-`Cookie` це "сестра" класів `Path` і `Query`. Вони наслідуються від одного батьківського класу `Param`.
Але пам'ятайте, що коли ви імпортуєте `Query`, `Path`, `Cookie` та інше з `fastapi`, це фактично функції, що повертають спеціальні класи.
///
@@ -29,6 +30,16 @@
///
-## Підсумки
+/// info
+
+Майте на увазі, що оскільки **браузери обробляють cookies** спеціальним чином і за лаштунками, вони **не** дозволяють **JavaScript** легко взаємодіяти з ними.
+
+Якщо ви перейдете до **інтерфейсу документації API** за адресою `/docs`, ви зможете побачити **документацію** для cookies для ваших *операцій шляху*.
+
+Але навіть якщо ви **заповните дані** і натиснете "Execute", оскільки інтерфейс документації працює з **JavaScript**, cookies не буде надіслано, і ви побачите повідомлення про **помилку**, ніби ви не ввели жодних значень.
+
+///
+
+## Підсумки { #recap }
Визначайте cookies за допомогою `Cookie`, використовуючи той же спільний шаблон, що і `Query` та `Path`.
diff --git a/docs/uk/docs/tutorial/cors.md b/docs/uk/docs/tutorial/cors.md
index 95b204d0f..f3ed8a7d9 100644
--- a/docs/uk/docs/tutorial/cors.md
+++ b/docs/uk/docs/tutorial/cors.md
@@ -1,8 +1,8 @@
-# CORS (Обмін ресурсами між різними джерелами)
+# CORS (Обмін ресурсами між різними джерелами) { #cors-cross-origin-resource-sharing }
-CORS або "Обмін ресурсами між різними джерелами" є ситуація, коли фронтенд, що працює в браузері, містить JavaScript-код, який взаємодіє з бекендом, розташованим в іншому "джерелі" (origin).
+CORS або "Cross-Origin Resource Sharing" є ситуація, коли фронтенд, що працює в браузері, містить JavaScript-код, який взаємодіє з бекендом, розташованим в іншому "джерелі" (origin).
-## Джерело (Origin)
+## Джерело (Origin) { #origin }
Джерело визначається комбінацією протоколу (`http`, `https`), домену (`myapp.com`, `localhost`, `localhost.tiangolo.com`), порту (`80`, `443`, `8080`).
@@ -15,7 +15,7 @@
Навіть якщо вони всі містять `localhost`, вони мають різні протоколи або порти, що робить їх окремими "джерелами".
-## Кроки
+## Кроки { #steps }
Припустимо, що Ваш фронтенд працює в браузері на `http://localhost:8080`, а його JavaScript намагається відправити запит до бекенду, який працює на `http://localhost` (Оскільки ми не вказуємо порт, браузер за замовчуванням припускає порт `80`).
@@ -25,15 +25,15 @@
У цьому випадку список має містити `http://localhost:8080`, щоб фронтенд на порту `:8080` працював коректно.
-## Символьне підставляння
+## Символьне підставляння { #wildcards }
Можна також оголосити список як `"*"` ("символьне підставляння"), що означає дозвіл для всіх джерел.
-Однак це дозволить лише певні типи комунікації, виключаючи все, що пов'язане з обліковими даними: Cookies, заголовки авторизації, такі як ті, що використовуються з Bearer токенами тощо.
+Однак це дозволить лише певні типи комунікації, виключаючи все, що пов'язане з обліковими даними: Cookies, заголовки авторизації, такі як ті, що використовуються з Bearer Tokens, тощо.
Тому для коректної роботи краще явно вказувати дозволені джерела.
-## Використання `CORSMiddleware`
+## Використання `CORSMiddleware` { #use-corsmiddleware }
Ви можете налаштувати це у Вашому додатку **FastAPI** за допомогою `CORSMiddleware`.
@@ -44,41 +44,44 @@
Також можна вказати, чи дозволяє Ваш бекенд:
-* Облікові дані (заголовки авторизації, сookies, тощо).
+* Облікові дані (заголовки авторизації, Cookies, тощо).
* Конкретні HTTP-методи (`POST`, `PUT`) або всі за допомогою `"*"`
* Конкретні HTTP-заголовки або всі за допомогою `"*"`.
-{* ../../docs_src/cors/tutorial001.py hl[2,6:11,13:19] *}
+{* ../../docs_src/cors/tutorial001_py39.py hl[2,6:11,13:19] *}
-Параметри за замовчуванням у `CORSMiddleware` є досить обмеженими, тому Вам потрібно явно вказати конкретні джерела, методи або заголовки, щоб браузери могли використовувати їх у контексті запитів між різними доменами.
+Параметри за замовчуванням у реалізації `CORSMiddleware` є досить обмеженими, тому Вам потрібно явно увімкнути конкретні джерела, методи або заголовки, щоб браузерам було дозволено використовувати їх у міждоменному контексті.
Підтримуються такі аргументи:
-* `allow_origins` - Список джерел, яким дозволено здійснювати міждоменні запити. Наприклад `['https://example.org', 'https://www.example.org']`. Ви можете використовувати ['*'], щоб дозволити всі джерела.
+* `allow_origins` - Список джерел, яким дозволено здійснювати міждоменні запити. Наприклад `['https://example.org', 'https://www.example.org']`. Ви можете використовувати `['*']`, щоб дозволити будь-яке джерело.
* `allow_origin_regex` - Рядок регулярного виразу для відповідності джерелам, яким дозволено здійснювати міждоменні запити. Наприклад, `'https://.*\.example\.org'`.
* `allow_methods` - Список HTTP-методів, дозволених для міждоменних запитів. За замовчуванням `['GET']`. Ви можете використовувати `['*']`, щоб дозволити всі стандартні методи.
-* `allow_headers` - Список HTTP-заголовків, які підтримуються для міждоменних запитів. За замовчуванням `[]`. Ви можете використовувати `['*']`, щоб дозволити всі заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` і `Content-Type` завжди дозволені для простих CORS-запитів.
-* `allow_credentials` - Визначає, чи підтримуються файли cookie для міждоменних запитів. За замовчуванням `False`. Також, якщо потрібно дозволити обмін обліковими даними (`allow_credentials = True`), параметр `allow_origins` не може бути встановлений як `['*']`, необхідно вказати конкретні джерела.
+* `allow_headers` - Список HTTP-заголовків запиту, які підтримуються для міждоменних запитів. За замовчуванням `[]`. Ви можете використовувати `['*']`, щоб дозволити всі заголовки. Заголовки `Accept`, `Accept-Language`, `Content-Language` і `Content-Type` завжди дозволені для простих CORS-запитів.
+* `allow_credentials` - Визначає, чи повинні підтримуватися cookies для міждоменних запитів. За замовчуванням `False`.
+
+ Жоден із параметрів `allow_origins`, `allow_methods` і `allow_headers` не можна встановлювати як `['*']`, якщо `allow_credentials` встановлено як `True`. Усі вони мають бути явно вказані.
+
* `expose_headers` - Вказує, які заголовки відповіді повинні бути доступні для браузера. За замовчуванням `[]`.
* `max_age` - Встановлює максимальний час (у секундах) для кешування CORS-відповідей у браузерах. За замовчуванням `600`.
Цей middleware обробляє два типи HTTP-запитів...
-### Попередні CORS-запити (preflight requests)
+### Попередні CORS-запити { #cors-preflight-requests }
Це будь-які `OPTIONS` - запити, що містять заголовки `Origin` та `Access-Control-Request-Method`.
У такому випадку middleware перехопить вхідний запит і відповість відповідними CORS-заголовками, повертаючи або `200`, або `400` для інформаційних цілей.
-### Прості запити
+### Прості запити { #simple-requests }
Будь-які запити із заголовком `Origin`. У цьому випадку middleware пропустить запит як звичайний, але додасть відповідні CORS-заголовки у відповідь.
-## Додаткова інформація
+## Додаткова інформація { #more-info }
-Більше про CORS можна дізнатися в документації Mozilla.
+Більше про CORS можна дізнатися в документації Mozilla про CORS.
/// note | Технічні деталі
diff --git a/docs/uk/docs/tutorial/debugging.md b/docs/uk/docs/tutorial/debugging.md
index b0e5344f8..0db418dcc 100644
--- a/docs/uk/docs/tutorial/debugging.md
+++ b/docs/uk/docs/tutorial/debugging.md
@@ -1,16 +1,16 @@
-# Налагодження (Debugging)
+# Налагодження { #debugging }
-Ви можете під'єднати дебагер у Вашому редакторі коду, наприклад, у Visual Studio Code або PyCharm.
+Ви можете під'єднати дебагер у вашому редакторі коду, наприклад, у Visual Studio Code або PyCharm.
-## Виклик `uvicorn`
+## Виклик `uvicorn` { #call-uvicorn }
-У Вашому FastAPI-додатку імпортуйте та запустіть `uvicorn` безпосередньо:
+У вашому FastAPI-додатку імпортуйте та запустіть `uvicorn` безпосередньо:
-{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
+{* ../../docs_src/debugging/tutorial001_py39.py hl[1,15] *}
-### Про `__name__ == "__main__"`
+### Про `__name__ == "__main__"` { #about-name-main }
-Головна мета використання `__name__ == "__main__"` — це забезпечення виконання певного коду тільки тоді, коли файл запускається безпосередньо:
+Головна мета використання `__name__ == "__main__"` — це забезпечення виконання певного коду лише тоді, коли ваш файл запускається так:
---
-Якщо Ви використовуєте PyCharm, ви можете:
-* Відкрити меню "Run".
-* Вибрати опцію "Debug...".
+Якщо ви використовуєте PyCharm, ви можете:
+
+* Відкрити меню «Run».
+* Вибрати опцію «Debug...».
* Потім з'явиться контекстне меню.
* Вибрати файл для налагодження (у цьому випадку, `main.py`).
-Це запустить сервер з Вашим **FastAPI** кодом, зупиниться на точках зупину тощо.
+Після цього він запустить сервер з вашим кодом **FastAPI**, зупиниться на точках зупину тощо.
Ось як це може виглядати:
diff --git a/docs/uk/docs/tutorial/encoder.md b/docs/uk/docs/tutorial/encoder.md
index f202c7989..1b403d5bb 100644
--- a/docs/uk/docs/tutorial/encoder.md
+++ b/docs/uk/docs/tutorial/encoder.md
@@ -1,32 +1,32 @@
-# JSON Compatible Encoder
+# JSON-сумісний кодувальник { #json-compatible-encoder }
-Існують випадки, коли вам може знадобитися перетворити тип даних (наприклад, модель Pydantic) в щось сумісне з JSON (наприклад, `dict`, `list`, і т. д.).
+Існують випадки, коли вам може знадобитися перетворити тип даних (наприклад, модель Pydantic) на щось сумісне з JSON (наприклад, `dict`, `list` тощо).
Наприклад, якщо вам потрібно зберегти це в базі даних.
-Для цього, **FastAPI** надає `jsonable_encoder()` функцію.
+Для цього **FastAPI** надає функцію `jsonable_encoder()`.
-## Використання `jsonable_encoder`
+## Використання `jsonable_encoder` { #using-the-jsonable-encoder }
Давайте уявимо, що у вас є база даних `fake_db`, яка приймає лише дані, сумісні з JSON.
Наприклад, вона не приймає об'єкти типу `datetime`, оскільки вони не сумісні з JSON.
-Отже, об'єкт типу `datetime` потрібно перетворити в рядок `str`, який містить дані в ISO форматі.
+Отже, об'єкт типу `datetime` потрібно перетворити на `str`, який містить дані в форматі ISO.
-Тим самим способом ця база даних не прийматиме об'єкт типу Pydantic model (об'єкт з атрибутами), а лише `dict`.
+Так само ця база даних не прийматиме модель Pydantic (об'єкт з атрибутами), а лише `dict`.
Ви можете використовувати `jsonable_encoder` для цього.
-Вона приймає об'єкт, такий як Pydantic model, і повертає його версію, сумісну з JSON:
+Вона приймає об'єкт, такий як модель Pydantic, і повертає його версію, сумісну з JSON:
{* ../../docs_src/encoder/tutorial001_py310.py hl[4,21] *}
-У цьому прикладі вона конвертує Pydantic model у `dict`, а `datetime` у `str`.
+У цьому прикладі вона конвертує модель Pydantic у `dict`, а `datetime` у `str`.
-Результат виклику цієї функції - це щось, що можна кодувати з використанням стандарту Python `json.dumps()`.
+Результат виклику цієї функції — це щось, що можна кодувати з використанням стандарту Python `json.dumps()`.
-Вона не повертає велику строку `str`, яка містить дані у форматі JSON (як строка). Вона повертає стандартну структуру даних Python (наприклад `dict`) із значеннями та підзначеннями, які є сумісними з JSON.
+Вона не повертає великий `str`, який містить дані у форматі JSON (як рядок). Вона повертає стандартну структуру даних Python (наприклад, `dict`) зі значеннями та підзначеннями, які є сумісними з JSON.
/// note | Примітка
diff --git a/docs/uk/docs/tutorial/extra-data-types.md b/docs/uk/docs/tutorial/extra-data-types.md
index 5da942b6e..a3545e074 100644
--- a/docs/uk/docs/tutorial/extra-data-types.md
+++ b/docs/uk/docs/tutorial/extra-data-types.md
@@ -1,13 +1,13 @@
-# Додаткові типи даних
+# Додаткові типи даних { #extra-data-types }
-До цього часу, ви використовували загальнопоширені типи даних, такі як:
+До цього часу ви використовували загальнопоширені типи даних, такі як:
* `int`
* `float`
* `str`
* `bool`
-Але можна також використовувати більш складні типи даних.
+Але ви також можете використовувати більш складні типи даних.
І ви все ще матимете ті ж можливості, які були показані до цього:
@@ -17,30 +17,30 @@
* Валідація даних.
* Автоматична анотація та документація.
-## Інші типи даних
+## Інші типи даних { #other-data-types }
Ось додаткові типи даних для використання:
* `UUID`:
- * Стандартний "Універсальний Унікальний Ідентифікатор", який часто використовується як ідентифікатор у багатьох базах даних та системах.
+ * Стандартний "Універсальний унікальний ідентифікатор", який часто використовується як ID у багатьох базах даних та системах.
* У запитах та відповідях буде представлений як `str`.
* `datetime.datetime`:
* Пайтонівський `datetime.datetime`.
- * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `2008-09-15T15:53:00+05:00`.
+ * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `2008-09-15T15:53:00+05:00`.
* `datetime.date`:
* Пайтонівський `datetime.date`.
- * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `2008-09-15`.
+ * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `2008-09-15`.
* `datetime.time`:
* Пайтонівський `datetime.time`.
- * У запитах та відповідях буде представлений як `str` в форматі ISO 8601, як: `14:23:55.003`.
+ * У запитах та відповідях буде представлений як `str` у форматі ISO 8601, як: `14:23:55.003`.
* `datetime.timedelta`:
* Пайтонівський `datetime.timedelta`.
* У запитах та відповідях буде представлений як `float` загальної кількості секунд.
- * Pydantic також дозволяє представляти це як "ISO 8601 time diff encoding", більше інформації дивись у документації.
+ * Pydantic також дозволяє представляти це як "ISO 8601 time diff encoding", дивіться документацію для отримання додаткової інформації.
* `frozenset`:
* У запитах і відповідях це буде оброблено так само, як і `set`:
- * У запитах список буде зчитано, дублікати будуть видалені та він буде перетворений на `set`.
- * У відповідях, `set` буде перетворений на `list`.
+ * У запитах список буде зчитано, дублікати буде видалено, і його буде перетворено на `set`.
+ * У відповідях `set` буде перетворено на `list`.
* Згенерована схема буде вказувати, що значення `set` є унікальними (з використанням JSON Schema's `uniqueItems`).
* `bytes`:
* Стандартний Пайтонівський `bytes`.
@@ -49,11 +49,11 @@
* `Decimal`:
* Стандартний Пайтонівський `Decimal`.
* У запитах і відповідях це буде оброблено так само, як і `float`.
-* Ви можете перевірити всі дійсні типи даних Pydantic тут: типи даних Pydantic.
+* Ви можете перевірити всі дійсні типи даних Pydantic тут: типи даних Pydantic.
-## Приклад
+## Приклад { #example }
-Ось приклад *path operation* з параметрами, використовуючи деякі з вищезазначених типів.
+Ось приклад *операції шляху* з параметрами, використовуючи деякі з вищезазначених типів.
{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}
diff --git a/docs/uk/docs/tutorial/first-steps.md b/docs/uk/docs/tutorial/first-steps.md
index e910c4ccc..5f3750010 100644
--- a/docs/uk/docs/tutorial/first-steps.md
+++ b/docs/uk/docs/tutorial/first-steps.md
@@ -1,126 +1,118 @@
-# Перші кроки
+# Перші кроки { #first-steps }
Найпростіший файл FastAPI може виглядати так:
-{* ../../docs_src/first_steps/tutorial001.py *}
+{* ../../docs_src/first_steps/tutorial001_py39.py *}
Скопіюйте це до файлу `main.py`.
-Запустіть сервер:
+Запустіть live-сервер:
get операцію
-/// info | `@decorator` Додаткова інформація
+/// info | `@decorator` Інформація
-Синтаксис `@something` у Python називається "декоратором".
+Синтаксис `@something` у Python називається «декоратором».
Ви розташовуєте його над функцією. Як гарний декоративний капелюх (мабуть, звідти походить термін).
-"Декоратор" приймає функцію нижче і виконує з нею якусь дію.
+«Декоратор» бере функцію нижче і виконує з нею якусь дію.
У нашому випадку, цей декоратор повідомляє **FastAPI**, що функція нижче відповідає **шляху** `/` і **операції** `get`.
-Це і є "декоратор операції шляху (path operation decorator)".
+Це і є «**декоратор операції шляху**».
///
-Можна також використовувати операції:
+Можна також використовувати інші операції:
* `@app.post()`
* `@app.put()`
@@ -271,58 +302,79 @@ https://example.com/items/foo
/// tip | Порада
-Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд.
+Ви можете використовувати кожну операцію (HTTP-метод) як забажаєте.
-**FastAPI** не нав'язує жодного певного значення для кожного методу.
+**FastAPI** не навʼязує жодного конкретного значення.
-Наведена тут інформація є рекомендацією, а не обов'язковою вимогою.
+Наведена тут інформація подана як настанова, а не вимога.
-Наприклад, під час використання GraphQL зазвичай усі дії виконуються тільки за допомогою `POST` операцій.
+Наприклад, під час використання GraphQL ви зазвичай виконуєте всі дії, використовуючи лише `POST` операції.
///
-### Крок 4: визначте **функцію операції шляху (path operation function)**
+### Крок 4: визначте **функцію операції шляху** { #step-4-define-the-path-operation-function }
-Ось "**функція операції шляху**":
+Ось наша «**функція операції шляху**»:
* **шлях**: це `/`.
* **операція**: це `get`.
-* **функція**: це функція, яка знаходиться нижче "декоратора" (нижче `@app.get("/")`).
+* **функція**: це функція нижче «декоратора» (нижче `@app.get("/")`).
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[7] *}
-Це звичайна функція Python.
+Це функція Python.
-FastAPI викликатиме її щоразу, коли отримає запит до URL із шляхом "/", використовуючи операцію `GET`.
+**FastAPI** викликатиме її щоразу, коли отримає запит до URL «`/`», використовуючи операцію `GET`.
-У даному випадку це асинхронна функція.
+У цьому випадку це `async` функція.
---
Ви також можете визначити її як звичайну функцію замість `async def`:
-{* ../../docs_src/first_steps/tutorial003.py hl[7] *}
+{* ../../docs_src/first_steps/tutorial003_py39.py hl[7] *}
/// note | Примітка
-Якщо не знаєте в чому різниця, подивіться [Конкурентність: *"Поспішаєш?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
+Якщо ви не знаєте різницю, подивіться [Асинхронність: *«Поспішаєте?»*](../async.md#in-a-hurry){.internal-link target=_blank}.
///
-### Крок 5: поверніть результат
+### Крок 5: поверніть вміст { #step-5-return-the-content }
-{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
+{* ../../docs_src/first_steps/tutorial001_py39.py hl[8] *}
-Ви можете повернути `dict`, `list`, а також окремі значення `str`, `int`, ітд.
+Ви можете повернути `dict`, `list`, а також окремі значення `str`, `int` тощо.
Також можна повернути моделі Pydantic (про це ви дізнаєтесь пізніше).
-Існує багато інших об'єктів і моделей, які будуть автоматично конвертовані в JSON (зокрема ORM тощо). Спробуйте використати свої улюблені, велика ймовірність, що вони вже підтримуються.
+Існує багато інших обʼєктів і моделей, які будуть автоматично конвертовані в JSON (зокрема ORM тощо). Спробуйте використати свої улюблені — велика ймовірність, що вони вже підтримуються.
+
+### Крок 6: розгорніть його { #step-6-deploy-it }
+
+Розгорніть ваш застосунок у **FastAPI Cloud** однією командою: `fastapi deploy`. 🎉
+
+#### Про FastAPI Cloud { #about-fastapi-cloud }
+
+**FastAPI Cloud** створено тим самим автором і командою, які стоять за **FastAPI**.
+
+Він спрощує процес **створення**, **розгортання** та **доступу** до API з мінімальними зусиллями.
+
+Він переносить той самий **досвід розробника** зі створення застосунків на FastAPI на **розгортання** їх у хмарі. 🎉
+
+FastAPI Cloud — основний спонсор і джерело фінансування для open source проєктів *FastAPI and friends*. ✨
+
+#### Розгортання в інших хмарних провайдерах { #deploy-to-other-cloud-providers }
+
+FastAPI — це open source і базується на стандартах. Ви можете розгортати FastAPI-застосунки у будь-якого хмарного провайдера на ваш вибір.
+
+Дотримуйтеся інструкцій вашого хмарного провайдера, щоб розгорнути FastAPI-застосунки з їхньою допомогою. 🤓
-## Підіб'ємо підсумки
+## Підібʼємо підсумки { #recap }
-* Імпортуємо `FastAPI`.
-* Створюємо екземпляр `app`.
-* Пишемо **декоратор операції шляху** як `@app.get("/")`.
-* Пишемо **функцію операції шляху**; наприклад, `def root(): ...`.
-* Запускаємо сервер у режимі розробки `fastapi dev`.
+* Імпортуйте `FastAPI`.
+* Створіть екземпляр `app`.
+* Напишіть **декоратор операції шляху**, використовуючи декоратори на кшталт `@app.get("/")`.
+* Визначте **функцію операції шляху**; наприклад, `def root(): ...`.
+* Запустіть сервер розробки командою `fastapi dev`.
+* За бажанням розгорніть ваш застосунок за допомогою `fastapi deploy`.
diff --git a/docs/uk/docs/tutorial/handling-errors.md b/docs/uk/docs/tutorial/handling-errors.md
index 12a356cd0..53b8b12f6 100644
--- a/docs/uk/docs/tutorial/handling-errors.md
+++ b/docs/uk/docs/tutorial/handling-errors.md
@@ -1,10 +1,10 @@
-# Обробка Помилок
+# Обробка помилок { #handling-errors }
-Є багато ситуацій, коли потрібно повідомити клієнта, який використовує Ваш API, про помилку.
+Є багато ситуацій, коли вам потрібно повідомити про помилку клієнта, який використовує ваш API.
Цим клієнтом може бути браузер із фронтендом, код іншого розробника, IoT-пристрій тощо.
-Можливо, Вам потрібно повідомити клієнта, що:
+Можливо, вам потрібно повідомити клієнта, що:
* У нього недостатньо прав для виконання цієї операції.
* Він не має доступу до цього ресурсу.
@@ -13,37 +13,37 @@
У таких випадках зазвичай повертається **HTTP статус-код** в діапазоні **400** (від 400 до 499).
-Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці "200" статус-коди означають, що запит пройшов успішно.
+Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці «200» статус-коди означають, що якимось чином запит був «успішним».
Статус-коди в діапазоні 400 означають, що сталася помилка з боку клієнта.
-Пам'ятаєте всі ці помилки **404 Not Found** (і жарти про них)?
+Пам'ятаєте всі ці помилки **«404 Not Found»** (і жарти про них)?
-## Використання `HTTPException`
+## Використання `HTTPException` { #use-httpexception }
Щоб повернути HTTP-відповіді з помилками клієнту, використовуйте `HTTPException`.
-### Імпорт `HTTPException`
+### Імпорт `HTTPException` { #import-httpexception }
-{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[1] *}
-### Використання `HTTPException` у коді
+### Згенеруйте `HTTPException` у своєму коді { #raise-an-httpexception-in-your-code }
`HTTPException` — це звичайна помилка Python із додатковими даними, які стосуються API.
-Оскільки це помилка Python, Ви не `повертаєте` його, а `генеруєте` (генеруєте помилку).
+Оскільки це помилка Python, ви не `return` її, а `raise` її.
-Це також означає, що якщо Ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там генеруєте `HTTPException`, всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту.
+Це також означає, що якщо ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там згенеруєте `HTTPException` всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту.
-Перевага використання `генерації` (raise) помилки замість `повернення` значення (return) стане більш очевидним в розділі про Залежності та Безпеку.
+Перевага генерації виключення замість повернення значення стане більш очевидною в розділі про залежності та безпеку.
-У цьому прикладі, якщо клієнт запитує елемент за ID, якого не існує, буде згенеровано помилку зі статус-кодом `404`:
+У цьому прикладі, коли клієнт запитує елемент за ID, якого не існує, згенеруйте виключення зі статус-кодом `404`:
-{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
+{* ../../docs_src/handling_errors/tutorial001_py39.py hl[11] *}
-### Отримана відповідь
+### Отримана відповідь { #the-resulting-response }
-Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає статус-код 200 і JSON відповідь:
+Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає HTTP статус-код 200 і JSON відповідь:
```JSON
{
@@ -51,7 +51,7 @@
}
```
-Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає статус-код 404 (помилка "не знайдено") та відповідь:
+Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає HTTP статус-код 404 (помилка «не знайдено») та JSON відповідь:
```JSON
{
@@ -61,7 +61,7 @@
/// tip | Порада
-Під час виклику `HTTPException` Ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише рядок (`str`).
+Під час генерації `HTTPException` ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише `str`.
Ви можете передати `dict`, `list` тощо.
@@ -69,33 +69,33 @@
///
-## Додавання власних заголовків
+## Додавання власних заголовків { #add-custom-headers }
-Іноді потрібно додати власні заголовки до HTTP-помилки, наприклад, для певних типів безпеки.
+Є деякі ситуації, коли корисно мати можливість додавати власні заголовки до HTTP-помилки. Наприклад, для деяких типів безпеки.
-Ймовірно, Вам не доведеться використовувати це безпосередньо у своєму коді.
+Ймовірно, вам не доведеться використовувати це безпосередньо у своєму коді.
-Але якщо Вам знадобиться це для складного сценарію, Ви можете додати власні заголовки:
+Але якщо вам знадобиться це для складного сценарію, ви можете додати власні заголовки:
-{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
+{* ../../docs_src/handling_errors/tutorial002_py39.py hl[14] *}
-## Встановлення власних обробників помилок
+## Встановлення власних обробників виключень { #install-custom-exception-handlers }
-Ви можете додати власні обробники помилок за допомогою тих самих утиліт обробки помилок зі Starlette.
+Ви можете додати власні обробники виключень за допомогою тих самих утиліт для виключень зі Starlette.
-Припустимо, у Вас є власний обʼєкт помилки `UnicornException`, яке Ви (або бібліотека, яку Ви використовуєте) може `згенерувати` (`raise`).
+Припустімо, у вас є власне виключення `UnicornException`, яке ви (або бібліотека, яку ви використовуєте) можете `raise`.
-І Ви хочете обробляти це виключення глобально за допомогою FastAPI.
+І ви хочете обробляти це виключення глобально за допомогою FastAPI.
Ви можете додати власний обробник виключень за допомогою `@app.exception_handler()`:
-{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}
+{* ../../docs_src/handling_errors/tutorial003_py39.py hl[5:7,13:18,24] *}
-Тут, якщо Ви звернетеся до `/unicorns/yolo`, то згенерується помилка `UnicornException`.
+Тут, якщо ви звернетеся до `/unicorns/yolo`, *операція шляху* згенерує (`raise`) `UnicornException`.
Але вона буде оброблена функцією-обробником `unicorn_exception_handler`.
-Отже, Ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-відповіддю:
+Отже, ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-вмістом:
```JSON
{"message": "Oops! yolo did something. There goes a rainbow..."}
@@ -105,31 +105,31 @@
Ви також можете використовувати `from starlette.requests import Request` і `from starlette.responses import JSONResponse`.
-**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме стосується і `Request`.
+**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме з `Request`.
///
-## Перевизначення обробників помилок за замовчуванням
+## Перевизначення обробників виключень за замовчуванням { #override-the-default-exception-handlers }
-**FastAPI** має кілька обробників помилок за замовчуванням.
+**FastAPI** має кілька обробників виключень за замовчуванням.
-Ці обробники відповідають за повернення стандартних JSON-відповідей, коли Ви `генеруєте` (`raise`) `HTTPException`, а також коли запит містить некоректні дані.
+Ці обробники відповідають за повернення стандартних JSON-відповідей, коли ви `raise` `HTTPException`, а також коли запит містить некоректні дані.
-Ви можете перевизначити ці обробники, створивши власні.
+Ви можете перевизначити ці обробники виключень власними.
-### Перевизначення помилок валідації запиту
+### Перевизначення виключень валідації запиту { #override-request-validation-exceptions }
-Коли запит містить некоректні дані, **FastAPI** генерує `RequestValidationError`.
+Коли запит містить некоректні дані, **FastAPI** внутрішньо генерує `RequestValidationError`.
-І також включає обробник помилок за замовчуванням для нього.
+І також включає обробник виключень за замовчуванням для нього.
-Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника помилок.
+Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника виключень.
-Обробник помилок отримує `Request` і саму помилку.
+Обробник виключень отримає `Request` і саме виключення.
-{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[2,14:19] *}
-Тепер, якщо Ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку:
+Тепер, якщо ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку:
```JSON
{
@@ -146,55 +146,44 @@
}
```
-Ви отримаєте текстову версію:
+ви отримаєте текстову версію:
```
-1 validation error
-path -> item_id
- value is not a valid integer (type=type_error.integer)
+Validation errors:
+Field: ('path', 'item_id'), Error: Input should be a valid integer, unable to parse string as an integer
```
-#### `RequestValidationError` проти `ValidationError`
+### Перевизначення обробника помилок `HTTPException` { #override-the-httpexception-error-handler }
-/// warning | Увага
+Аналогічно, ви можете перевизначити обробник `HTTPException`.
-Це технічні деталі, які Ви можете пропустити, якщо вони зараз не важливі для Вас.
+Наприклад, ви можете захотіти повернути відповідь у вигляді простого тексту замість JSON для цих помилок:
-///
-
-`RequestValidationError` є підкласом Pydantic `ValidationError`.
-
-**FastAPI** використовує його для того, якщо Ви використовуєте модель Pydantic у `response_model` і у ваших даних є помилка, Ви побачили помилку у своєму журналі.
-
-Але клієнт/користувач не побачить її. Натомість клієнт отримає "Internal Server Error" зі статусом HTTP `500`.
-
-Так має бути, якщо у Вас виникла `ValidationError` Pydantic у *відповіді* або деінде у вашому коді (не у *запиті* клієнта), це насправді є помилкою у Вашому коді.
-
-І поки Ви її виправляєте, клієнти/користувачі не повинні мати доступу до внутрішньої інформації про помилку, оскільки це може призвести до вразливості безпеки.
+{* ../../docs_src/handling_errors/tutorial004_py39.py hl[3:4,9:11,25] *}
-### Перевизначення обробника помилок `HTTPException`
+/// note | Технічні деталі
-Аналогічно, Ви можете перевизначити обробник `HTTPException`.
+Ви також можете використовувати `from starlette.responses import PlainTextResponse`.
-Наприклад, Ви можете захотіти повернути текстову відповідь замість JSON для цих помилок:
+**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette.
-{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}
+///
-/// note | Технічні деталі
+/// warning | Попередження
-Ви також можете використовувати `from starlette.responses import PlainTextResponse`.
+Пам’ятайте, що `RequestValidationError` містить інформацію про назву файлу та рядок, де сталася помилка валідації, щоб за потреби ви могли показати це у своїх логах із відповідною інформацією.
-**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette.
+Але це означає, що якщо ви просто перетворите це на рядок і повернете цю інформацію напряму, ви можете розкрити трохи інформації про вашу систему, тому тут код витягає та показує кожну помилку незалежно.
///
-### Використання тіла `RequestValidationError`
+### Використання тіла `RequestValidationError` { #use-the-requestvalidationerror-body }
`RequestValidationError` містить `body`, який він отримав із некоректними даними.
Ви можете використовувати це під час розробки свого додатка, щоб логувати тіло запиту та налагоджувати його, повертати користувачеві тощо.
-{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}
+{* ../../docs_src/handling_errors/tutorial005_py39.py hl[14] *}
Тепер спробуйте надіслати некоректний елемент, наприклад:
@@ -204,8 +193,8 @@ path -> item_id
"size": "XL"
}
```
-Ви отримаєте відповідь, яка повідомить Вам, які саме дані є некоректні у вашому тілі запиту:
+Ви отримаєте відповідь, яка повідомить вам, що дані є некоректними, і міститиме отримане тіло запиту:
```JSON hl_lines="12-15"
{
@@ -226,30 +215,30 @@ path -> item_id
}
```
-#### `HTTPException` FastAPI проти `HTTPException` Starlette
+#### `HTTPException` FastAPI проти `HTTPException` Starlette { #fastapis-httpexception-vs-starlettes-httpexception }
**FastAPI** має власний `HTTPException`.
-І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` в Starlette.
+І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` у Starlette.
Єдина різниця полягає в тому, що `HTTPException` в **FastAPI** приймає будь-які дані, які можна перетворити на JSON, для поля `detail`, тоді як `HTTPException` у Starlette приймає тільки рядки.
-Отже, Ви можете продовжувати використовувати `HTTPException` в **FastAPI** як зазвичай у своєму коді.
+Отже, ви можете продовжувати генерувати `HTTPException` **FastAPI** як зазвичай у своєму коді.
-Але коли Ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette.
+Але коли ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette.
-Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує (raise) `HTTPException`, Ваш обробник зможе перехопити та обробити її.
+Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує Starlette `HTTPException`, ваш обробник зможе перехопити та обробити її.
-У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, помилка Starlette перейменовується на `StarletteHTTPException`:
+У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, виключення Starlette перейменовується на `StarletteHTTPException`:
```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
```
-### Повторне використання обробників помилок **FastAPI**
+### Повторне використання обробників виключень **FastAPI** { #reuse-fastapis-exception-handlers }
-Якщо Ви хочете використовувати помилки разом із такими ж обробниками помилок за замовчуванням, як у **FastAPI**, Ви можете імпортувати та повторно використовувати їх із `fastapi.exception_handlers`:
+Якщо ви хочете використовувати виключення разом із такими ж обробниками виключень за замовчуванням, як у **FastAPI**, ви можете імпортувати та повторно використати обробники виключень за замовчуванням із `fastapi.exception_handlers`:
-{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}
+{* ../../docs_src/handling_errors/tutorial006_py39.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
index 6f7b0bdae..c080c19f0 100644
--- a/docs/uk/docs/tutorial/header-param-models.md
+++ b/docs/uk/docs/tutorial/header-param-models.md
@@ -1,26 +1,24 @@
-# Моделі Параметрів Заголовків
+# Моделі параметрів заголовків { #header-parameter-models }
-Якщо у Вас є група пов’язаних параметрів заголовків, Ви можете створити **Pydantic модель** для їх оголошення.
+Якщо у Вас є група пов’язаних **параметрів заголовків**, Ви можете створити **Pydantic модель** для їх оголошення.
Це дозволить Вам повторно **використовувати модель** в **різних місцях**, а також оголосити валідації та метадані для всіх параметрів одночасно. 😎
-/// note | Нотатки
+/// note | Примітка
Ця можливість підтримується починаючи з версії FastAPI `0.115.0`. 🤓
///
-## Параметри Заголовків з Використанням Pydantic Model
+## Параметри заголовків з використанням Pydantic моделі { #header-parameters-with-a-pydantic-model }
Оголосіть потрібні **параметри заголовків** у **Pydantic моделі**, а потім оголосіть параметр як `Header`:
{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *}
-FastAPI буде витягувати дані для кожного поля з заголовків у запиті та передавати їх у створену Вами Pydantic модель.
-
**FastAPI** буде **витягувати** дані для **кожного поля** з **заголовків** у запиті та передавати їх у створену Вами Pydantic модель.
-## Перевірка в Документації
+## Перевірка в документації { #check-the-docs }
Ви можете побачити необхідні заголовки в інтерфейсі документації за адресою `/docs`:
@@ -28,7 +26,7 @@ FastAPI буде витягувати дані для кожного поля з
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. |
contact поля| Параметр | Тип | Опис |
|---|---|---|
name | str | Ідентифікаційне ім'я контактної особи або організації. |
url | str | URL, що вказує на контактну інформацію. МАЄ бути у форматі URL. |
email | str | Адреса електронної пошти контактної особи або організації. МАЄ бути у форматі адреси електронної пошти. |
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. |
-## Ідентифікатор ліцензії
+## Ідентифікатор ліцензії { #license-identifier }
З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати `license_info` за допомогою `identifier` замість `url`.
Наприклад:
-{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
+{* ../../docs_src/metadata/tutorial001_1_py39.py hl[31] *}
-## Метадані для тегів
+## Метадані для тегів { #metadata-for-tags }
Ви також можете додати додаткові метадані для різних тегів, які використовуються для групування операцій шляхів, за допомогою параметра `openapi_tags`.
@@ -46,53 +46,53 @@
Кожен словник може містити:
-* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s.
-* `description`: `str` з коротким описом тегу. Може містити Markdown і буде відображено в інтерфейсі документації.
-* `externalDocs`: `dict` який описує зовнішню документацію з такими полями:
+* `name` (**обов'язково**): `str` з тією ж назвою тегу, яку Ви використовуєте у параметрі `tags` у Ваших *операціях шляху* та `APIRouter`s.
+* `description`: `str` з коротким описом тегу. Може містити Markdown і буде показано в інтерфейсі документації.
+* `externalDocs`: `dict`, який описує зовнішню документацію з такими полями:
* `description`: `str` з коротким описом зовнішньої документації.
- * `url` (**обов'язково**): `str`з URL-адресою зовнішньої документації.
+ * `url` (**обов'язково**): `str` з URL-адресою зовнішньої документації.
-### Створення метаданих для тегів
+### Створення метаданих для тегів { #create-metadata-for-tags }
Спробуймо це на прикладі з тегами для `users` та `items`.
-Створіть метадані для своїх тегів і передайте їх у параметр `openapi_tags`:
+Створіть метадані для своїх тегів і передайте їх у параметр `openapi_tags`:
-{* ../../docs_src/metadata/tutorial004.py hl[3:16,18] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[3:16,18] *}
Зверніть увагу, що в описах можна використовувати Markdown, наприклад, "login" буде показано жирним шрифтом (**login**), а "fancy" буде показано курсивом (_fancy_).
/// tip | Порада
-Не обов'язково додавати метадані для всіх тегів, які Ви використовуєте.
+Вам не потрібно додавати метадані для всіх тегів, які Ви використовуєте.
///
-### Використання тегів
+### Використовуйте свої теги { #use-your-tags }
-Використовуйте параметр `tags` зі своїми *операціями шляху* (і `APIRouter`) для призначення їх до різних тегів:
+Використовуйте параметр `tags` зі своїми *операціями шляху* (і `APIRouter`s), щоб призначити їх до різних тегів:
-{* ../../docs_src/metadata/tutorial004.py hl[21,26] *}
+{* ../../docs_src/metadata/tutorial004_py39.py hl[21,26] *}
/// info | Інформація
-Детальніше про теги читайте в розділі [Конфігурація шляхів операцій](path-operation-configuration.md#tags){.internal-link target=_blank}.
+Детальніше про теги читайте в розділі [Конфігурація операції шляху](path-operation-configuration.md#tags){.internal-link target=_blank}.
///
-### Перевірка документації
+### Перевірте документацію { #check-the-docs }
-Якщо Ви зараз перевірите документацію, вона покаже всі додаткові метадані:
+Тепер, якщо Ви перевірите документацію, вона покаже всі додаткові метадані:
-### Порядок тегів
+### Порядок тегів { #order-of-tags }
Порядок кожного словника метаданих тегу також визначає порядок відображення в інтерфейсі документації.
-Наприклад, хоча `users` мав би йти після `items` в алфавітному порядку, він відображається перед ними, оскільки ми додали його метадані як перший словник у списку.
+Наприклад, хоча `users` мав би йти після `items` в алфавітному порядку, він відображається перед ними, оскільки ми додали їхні метадані як перший словник у списку.
-## URL для OpenAPI
+## URL для OpenAPI { #openapi-url }
За замовчуванням схема OpenAPI надається за адресою `/openapi.json`.
@@ -100,11 +100,11 @@
Наприклад, щоб налаштувати його на `/api/v1/openapi.json`:
-{* ../../docs_src/metadata/tutorial002.py hl[3] *}
+{* ../../docs_src/metadata/tutorial002_py39.py hl[3] *}
Якщо Ви хочете повністю вимкнути схему OpenAPI, Ви можете встановити `openapi_url=None`, це також вимкне інтерфейси документації, які її використовують.
-## URL-адреси документації
+## URL-адреси документації { #docs-urls }
Ви можете налаштувати два інтерфейси користувача для документації, які включені:
@@ -117,4 +117,4 @@
Наприклад, щоб налаштувати Swagger UI на `/documentation` і вимкнути ReDoc:
-{* ../../docs_src/metadata/tutorial003.py hl[3] *}
+{* ../../docs_src/metadata/tutorial003_py39.py hl[3] *}
diff --git a/docs/uk/docs/tutorial/middleware.md b/docs/uk/docs/tutorial/middleware.md
index 807be484a..2d1580e49 100644
--- a/docs/uk/docs/tutorial/middleware.md
+++ b/docs/uk/docs/tutorial/middleware.md
@@ -1,45 +1,43 @@
-# Middleware (Проміжний шар)
+# Middleware { #middleware }
-У **FastAPI** можна додавати middleware (проміжний шар).
+У **FastAPI** можна додавати middleware.
-"Middleware" — це функція, яка працює з кожним **запитом** перед його обробкою будь-якою конкретною *операцією шляху* (*path operation*), а також з кожною **відповіддю** перед її поверненням.
+«Middleware» — це функція, яка працює з кожним **запитом** перед його обробкою будь-якою конкретною *операцією шляху*. А також з кожною **відповіддю** перед її поверненням.
-* Middleware отримує кожен **запит**, що надходить до Вашого застосунку.
-* Може виконати певні дії із цим **запитом** або запустити необхідний код.
-* Далі передає **запит** для обробки основним застосунком (*операцією шляху*).
-* Отримує **відповідь**, сформовану застосунком (*операцією шляху*).
-* Може змінити цю **відповідь** або виконати додатковий код.
-* Повертає **відповідь** клієнту.
+* Вона отримує кожен **запит**, що надходить до вашого застосунку.
+* Потім вона може виконати певні дії із цим **запитом** або запустити необхідний код.
+* Далі вона передає **запит** для обробки рештою застосунку (якоюсь *операцією шляху*).
+* Потім вона отримує **відповідь**, сформовану застосунком (якоюсь *операцією шляху*).
+* Вона може виконати певні дії із цією **відповіддю** або запустити необхідний код.
+* Потім вона повертає **відповідь**.
/// note | Технічні деталі
-Якщо у Вас є залежності з `yield`, код виходу виконається *після* middleware.
+Якщо у вас є залежності з `yield`, код виходу виконається *після* middleware.
-Якщо були заплановані фонові задачі (background tasks - розглянуто далі), вони виконаються *після* всіх middleware.
+Якщо були заплановані фонові задачі (розглянуто в розділі [Background Tasks](background-tasks.md){.internal-link target=_blank}, ви побачите це пізніше), вони виконаються *після* всіх middleware.
///
-## Створення middleware
+## Створення middleware { #create-a-middleware }
-Щоб створити middleware, Ви використовуєте декоратор `@app.middleware("http")` на функції.
+Щоб створити middleware, ви використовуєте декоратор `@app.middleware("http")` над функцією.
Функція middleware отримує:
-* `Запит`.
-* Функцію `call_next`, яка приймає `запит` як параметр.
- * Ця функція передає `запит` відповідній *операції шляху*.
- * Потім вона повертає `відповідь`, згенеровану цією *операцією шляху*.
+* `request`.
+* Функцію `call_next`, яка отримає `request` як параметр.
+ * Ця функція передасть `request` відповідній *операції шляху*.
+ * Потім вона поверне `response`, згенеровану відповідною *операцією шляху*.
+* Потім ви можете додатково змінити `response` перед тим, як повернути її.
-* Ви можете ще змінити `відповідь` перед тим, як повернути її.
-
-
-{* ../../docs_src/middleware/tutorial001.py hl[8:9,11,14] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[8:9,11,14] *}
/// tip | Порада
-Не забувайте, що власні заголовки можна додавати, використовуючи префікс 'X-'.
+Пам’ятайте, що власні пропрієтарні заголовки можна додавати використовуючи префікс `X-`.
-Але якщо у Вас є власні заголовки, які Ви хочете, щоб браузерний клієнт міг побачити, потрібно додати їх до Вашої конфігурації CORS (див. [CORS (Обмін ресурсами між різними джерелами)](cors.md){.internal-link target=_blank} за допомогою параметра `expose_headers`, описаного в документації Starlette по CORS.
+Але якщо у вас є власні заголовки, які ви хочете, щоб клієнт у браузері міг побачити, потрібно додати їх до ваших конфігурацій CORS ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) за допомогою параметра `expose_headers`, описаного в документації Starlette по CORS.
///
@@ -47,28 +45,50 @@
Ви також можете використати `from starlette.requests import Request`.
-**FastAPI** надає це для Вашої зручності як розробника. Але він походить безпосередньо зі Starlette.
+**FastAPI** надає це для вашої зручності як розробника. Але воно походить безпосередньо зі Starlette.
///
-### До і після `response`(`відповіді`)
+### До і після `response` { #before-and-after-the-response }
-Ви можете додати код, який буде виконуватися з `запитом` (`request`), до того, як його обробить будь-яка *операція шляху* (*path operation*).
+Ви можете додати код, який буде виконуватися з `request`, до того, як його отримає будь-яка *операція шляху*.
-Також Ви можете додати код, який буде виконуватися після того, як `відповідь` (`response`) буде згенеровано, перед тим як його повернути.
+Також ви можете додати код, який буде виконуватися після того, як `response` буде згенеровано, перед тим як її повернути.
-Наприклад, Ви можете додати власний заголовок `X-Process-Time`, який міститиме час у секундах, який витратився на обробку запиту та генерацію відповіді:
+Наприклад, ви можете додати власний заголовок `X-Process-Time`, який міститиме час у секундах, який витратився на обробку запиту та генерацію відповіді:
-{* ../../docs_src/middleware/tutorial001.py hl[10,12:13] *}
+{* ../../docs_src/middleware/tutorial001_py39.py hl[10,12:13] *}
-
-/// tip | Підказка
+/// tip | Порада
Тут ми використовуємо `time.perf_counter()` замість `time.time()` оскільки він може бути більш точним для таких випадків. 🤓
///
-## Інші middlewares
+## Порядок виконання кількох middleware { #multiple-middleware-execution-order }
+
+Коли ви додаєте кілька middleware, використовуючи або декоратор `@app.middleware()` або метод `app.add_middleware()`, кожен новий middleware обгортає застосунок, утворюючи стек. Останній доданий middleware є *зовнішнім*, а перший — *внутрішнім*.
+
+На шляху запиту першим виконується *зовнішній* middleware.
+
+На шляху відповіді він виконується останнім.
+
+Наприклад:
+
+```Python
+app.add_middleware(MiddlewareA)
+app.add_middleware(MiddlewareB)
+```
+
+Це призводить до такого порядку виконання:
+
+* **Запит**: MiddlewareB → MiddlewareA → route
+
+* **Відповідь**: route → MiddlewareA → MiddlewareB
+
+Така поведінка стеку гарантує, що middleware виконуються у передбачуваному та керованому порядку.
+
+## Інші middlewares { #other-middlewares }
Ви можете пізніше прочитати більше про інші middlewares в [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.
diff --git a/docs/uk/docs/tutorial/path-params-numeric-validations.md b/docs/uk/docs/tutorial/path-params-numeric-validations.md
index 8ee4f480f..f6aa92019 100644
--- a/docs/uk/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/uk/docs/tutorial/path-params-numeric-validations.md
@@ -1,8 +1,8 @@
-# Path Параметри та валідація числових даних
+# Параметри шляху та валідація числових даних { #path-parameters-and-numeric-validations }
-Так само як Ви можете оголошувати додаткові перевірки та метадані для query параметрів за допомогою `Query`, Ви можете оголошувати той самий тип перевірок і метаданих для параметрів шляху за допомогою `Path`.
+Так само як ви можете оголошувати додаткові перевірки та метадані для query параметрів за допомогою `Query`, ви можете оголошувати той самий тип перевірок і метаданих для параметрів шляху за допомогою `Path`.
-## Імпорт Path
+## Імпорт `Path` { #import-path }
Спочатку імпортуйте `Path` з `fastapi` і імпортуйте `Annotated`:
@@ -10,70 +10,69 @@
/// info | Інформація
-FastAPI додав підтримку `Annotated` (і почав рекомендувати його використання) у версії 0.95.0.
+FastAPI додав підтримку `Annotated` (і почав рекомендувати його використання) у версії 0.95.0.
-Якщо у Вас стара версія, при спробі використати `Annotated` можуть виникати помилки.
+Якщо у вас стара версія, при спробі використати `Annotated` можуть виникати помилки.
-Переконайтеся, що Ви [оновили версію FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} принаймні до версії 0.95.1 перед використанням `Annotated`.
+Переконайтеся, що ви [оновили версію FastAPI](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} принаймні до версії 0.95.1 перед використанням `Annotated`.
///
-## Оголошення метаданих
+## Оголошення метаданих { #declare-metadata }
Ви можете оголошувати всі ті ж параметри, що і для `Query`.
-Наприклад, щоб оголосити значення метаданих `title` для параметра шляху `item_id`, Ви можете написати:
+Наприклад, щоб оголосити значення метаданих `title` для параметра шляху `item_id`, ви можете написати:
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[10] *}
/// note | Примітка
-Параметр шляху завжди є обов’язковим, оскільки він має бути частиною шляху. Навіть якщо Ви оголосите його зі значенням `None` або встановите значення за замовчуванням — він все одно залишатиметься обов’язковим.
+Параметр шляху завжди є обов’язковим, оскільки він має бути частиною шляху. Навіть якщо ви оголосите його зі значенням `None` або встановите значення за замовчуванням — це ні на що не вплине, він все одно завжди буде обов’язковим.
///
-## Упорядковуйте параметри, як Вам потрібно
+## Упорядковуйте параметри, як вам потрібно { #order-the-parameters-as-you-need }
-/// tip | Підказка
+/// tip | Порада
-Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`.
+Це, мабуть, не настільки важливо або необхідно, якщо ви використовуєте `Annotated`.
///
-Припустимо, Ви хочете оголосити параметр запиту `q` як обов’язковий `str`.
+Припустимо, ви хочете оголосити параметр запиту `q` як обов’язковий `str`.
-І Вам не потрібно оголошувати нічого іншого для цього параметра, тому немає потреби використовувати `Query`.
+І вам не потрібно оголошувати нічого іншого для цього параметра, тому вам насправді не потрібно використовувати `Query`.
-Але Вам все одно потрібно використовувати `Path` для параметра шляху `item_id`. І з певних причин Ви не хочете використовувати `Annotated`.
+Але вам все одно потрібно використовувати `Path` для параметра шляху `item_id`. І з певних причин ви не хочете використовувати `Annotated`.
Python видасть помилку, якщо розмістити значення з "default" перед значенням, яке не має "default".
-Але Ви можете змінити порядок і розмістити значення без значення за замовчуванням (параметр запиту `q`) першим.
+Але ви можете змінити порядок і розмістити значення без значення за замовчуванням (параметр запиту `q`) першим.
+Для **FastAPI** порядок не має значення. Він визначає параметри за їхніми іменами, типами та оголошеннями за замовчуванням (`Query`, `Path` тощо) і не звертає уваги на порядок.
-Для **FastAPI** порядок не має значення. Він визначає параметри за їх іменами, типами та значеннями за замовчуванням (`Query`, `Path` тощо) і не звертає уваги на порядок.
+Тому ви можете оголосити вашу функцію так:
-Тому Ви можете оголосити Вашу функцію так:
+{* ../../docs_src/path_params_numeric_validations/tutorial002_py39.py hl[7] *}
-{* ../../docs_src/path_params_numeric_validations/tutorial002.py hl[7] *}
-
-Але майте на увазі, що якщо Ви використовуєте `Annotated`, ця проблема не виникне, оскільки Ви не використовуєте значення за замовчуванням для параметрів `Query()` або `Path()`.
+Але майте на увазі, що якщо ви використовуєте `Annotated`, цієї проблеми не буде, це не матиме значення, оскільки ви не використовуєте значення за замовчуванням параметрів функції для `Query()` або `Path()`.
{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
-## Упорядковуйте параметри за потребою, хитрощі
+## Упорядковуйте параметри, як вам потрібно: хитрощі { #order-the-parameters-as-you-need-tricks }
-/// tip | Підказка
+/// tip | Порада
-Це, мабуть, не настільки важливо або необхідно, якщо Ви використовуєте `Annotated`.
+Це, мабуть, не настільки важливо або необхідно, якщо ви використовуєте `Annotated`.
///
Ось **невелика хитрість**, яка може стати в пригоді, хоча вона рідко знадобиться.
-Якщо Ви хочете:
+Якщо ви хочете:
-* оголосити параметр запиту `q` без використання `Query` або значення за замовчуванням
+* оголосити параметр запиту `q` без `Query` і без жодного значення за замовчуванням
* оголосити параметр шляху `item_id`, використовуючи `Path`
* розмістити їх у різному порядку
* не використовувати `Annotated`
@@ -84,72 +83,72 @@ Python видасть помилку, якщо розмістити значен
Python нічого не зробить із цією `*`, але розпізнає, що всі наступні параметри слід викликати як аргументи за ключовим словом (пари ключ-значення), також відомі як kwargs. Навіть якщо вони не мають значення за замовчуванням.
-{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
+{* ../../docs_src/path_params_numeric_validations/tutorial003_py39.py hl[7] *}
-### Краще з `Annotated`
+### Краще з `Annotated` { #better-with-annotated }
-Майте на увазі, якщо Ви використовуєте `Annotated`, оскільки Ви не використовуєте значення за замовчуванням для параметрів функції, цієї проблеми не виникне, і, швидше за все, Вам не потрібно буде використовувати `*`.
+Майте на увазі, що якщо ви використовуєте `Annotated`, оскільки ви не використовуєте значення за замовчуванням параметрів функції, цієї проблеми не буде, і, ймовірно, вам не потрібно буде використовувати `*`.
{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
-## Валідація числових даних: більше або дорівнює
+## Валідація числових даних: більше або дорівнює { #number-validations-greater-than-or-equal }
-За допомогою `Query` і `Path` (та інших, які Ви побачите пізніше) можна оголошувати числові обмеження.
+За допомогою `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] *}
-## Валідація числових даних: більше ніж і менше або дорівнює
+## Валідація числових даних: більше ніж і менше або дорівнює { #number-validations-greater-than-and-less-than-or-equal }
Те саме застосовується до:
-* `gt`: `g`reater `t`han (більше ніж)
-* `le`: `l`ess than or `e`qual (менше або дорівнює)
+* `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, більше ніж і менше ніж { #number-validations-floats-greater-than-and-less-than }
Валідація чисел також працює для значень типу `float`.
-Ось де стає важливо мати можливість оголошувати gt, а не тільки ge. Це дозволяє, наприклад, вимагати, щоб значення було більше `0`, навіть якщо воно менше `1`.
+Ось де стає важливо мати можливість оголошувати gt, а не тільки ge. Це дозволяє, наприклад, вимагати, щоб значення було більше `0`, навіть якщо воно менше `1`.
Таким чином, значення `0.5` буде допустимим. Але `0.0` або `0` — ні.
-Те саме стосується lt.
+Те саме стосується lt.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## Підсумок
+## Підсумок { #recap }
-За допомогою `Query`, `Path` (і інших параметрів, які Ви ще не бачили) можна оголошувати метадані та перевірки рядків, так само як у [Query параметри та валідація рядків](query-params-str-validations.md){.internal-link target=_blank}.
+За допомогою `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 (менше або дорівнює)
+* `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`.
+`Query`, `Path` та інші класи, які ви побачите пізніше, є підкласами спільного класу `Param`.
-Всі вони мають однакові параметри для додаткових перевірок і метаданих, які Ви вже бачили.
+Всі вони мають однакові параметри для додаткових перевірок і метаданих, які ви вже бачили.
///
/// note | Технічні деталі
-Коли Ви імпортуєте `Query`, `Path` та інші з `fastapi`, насправді це функції.
+Коли ви імпортуєте `Query`, `Path` та інші з `fastapi`, насправді це функції.
При виклику вони повертають екземпляри класів з такими ж іменами.
-Тобто Ви імпортуєте `Query`, яка є функцією. А коли Ви її викликаєте, вона повертає екземпляр класу, який теж називається `Query`.
+Тобто ви імпортуєте `Query`, яка є функцією. А коли ви її викликаєте, вона повертає екземпляр класу, який теж називається `Query`.
-Ці функції створені таким чином (замість використання класів напряму), щоб Ваш редактор не відзначав їхні типи як помилки.
+Ці функції створені таким чином (замість використання класів напряму), щоб ваш редактор не відзначав їхні типи як помилки.
-Таким чином, Ви можете користуватися своїм звичайним редактором і інструментами для програмування без додаткових налаштувань для ігнорування таких помилок.
+Таким чином, ви можете користуватися своїм звичайним редактором і інструментами для програмування без додаткових налаштувань для ігнорування таких помилок.
///
diff --git a/docs/uk/docs/tutorial/path-params.md b/docs/uk/docs/tutorial/path-params.md
index da4ff2f9e..059890549 100644
--- a/docs/uk/docs/tutorial/path-params.md
+++ b/docs/uk/docs/tutorial/path-params.md
@@ -1,34 +1,34 @@
-# Path Параметри
+# Параметри шляху { #path-parameters }
-Ви можете визначити "параметри" або "змінні" шляху, використовуючи синтаксис форматованих рядків:
+Ви можете оголосити «параметри» або «змінні» шляху, використовуючи той самий синтаксис, що й у форматованих рядках Python:
-{* ../../docs_src/path_params/tutorial001.py hl[6:7] *}
+{* ../../docs_src/path_params/tutorial001_py39.py hl[6:7] *}
-Значення параметра шляху `item_id` передається у функцію як аргумент `item_id`.
+Значення параметра шляху `item_id` буде передано у вашу функцію як аргумент `item_id`.
-Якщо запустити цей приклад та перейти за посиланням http://127.0.0.1:8000/items/foo, то отримаємо таку відповідь:
+Отже, якщо ви запустите цей приклад і перейдете за посиланням http://127.0.0.1:8000/items/foo, то побачите відповідь:
```JSON
{"item_id":"foo"}
```
-## Path параметри з типами
+## Параметри шляху з типами { #path-parameters-with-types }
-Ви можете визначити тип параметра шляху у функції, використовуючи стандартні анотації типів Python:
+Ви можете оголосити тип параметра шляху у функції, використовуючи стандартні анотації типів Python:
-{* ../../docs_src/path_params/tutorial002.py hl[7] *}
+{* ../../docs_src/path_params/tutorial002_py39.py hl[7] *}
-У такому випадку `item_id` визначається як `int`.
+У цьому випадку `item_id` оголошено як `int`.
/// check | Примітка
-Це дасть можливість підтримки редактора всередині функції з перевірками помилок, автодоповнення тощо.
+Це дасть вам підтримку редактора всередині функції з перевірками помилок, автодоповненням тощо.
///
-## Перетворення даних
+## Перетворення даних { #data-conversion }
-Якщо запустити цей приклад і перейти за посиланням http://127.0.0.1:8000/items/3, то отримаєте таку відповідь:
+Якщо ви запустите цей приклад і відкриєте у браузері http://127.0.0.1:8000/items/3, то побачите відповідь:
```JSON
{"item_id":3}
@@ -36,15 +36,15 @@
/// check | Примітка
-Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`. Це Python `int`, а не рядок `"3"`.
+Зверніть увагу, що значення, яке отримала (і повернула) ваша функція, — це `3`, як Python `int`, а не рядок `"3"`.
-Отже, з таким оголошенням типу **FastAPI** автоматично виконує "парсинг" запитів.
+Отже, з таким оголошенням типу **FastAPI** надає вам автоматичний «parsing» запиту.
///
-## Перевірка даних
+## Валідація даних { #data-validation }
-Якщо ж відкрити у браузері посилання http://127.0.0.1:8000/items/foo, то побачимо цікаву HTTP-помилку:
+Але якщо ви перейдете у браузері за посиланням http://127.0.0.1:8000/items/foo, ви побачите гарну HTTP-помилку:
```JSON
{
@@ -61,144 +61,136 @@
]
}
```
-тому що параметр шляху має значення `"foo"`, яке не є типом `int`.
-Таку саму помилку отримаємо, якщо передати `float` замість `int`, як бачимо, у цьому прикладі: http://127.0.0.1:8000/items/4.2
+тому що параметр шляху `item_id` мав значення `"foo"`, яке не є `int`.
+
+Та сама помилка з’явиться, якщо ви передасте `float` замість `int`, як у: http://127.0.0.1:8000/items/4.2
/// check | Примітка
-Отже, **FastAPI** надає перевірку типів з таким самим оголошенням типу в Python.
+Отже, з тим самим оголошенням типу в Python **FastAPI** надає вам валідацію даних.
-Зверніть увагу, що помилка також чітко вказує саме на те місце, де валідація не пройшла.
+Зверніть увагу, що помилка також чітко вказує саме місце, де валідація не пройшла.
-Це неймовірно корисно під час розробки та дебагінгу коду, що взаємодіє з вашим API.
+Це неймовірно корисно під час розробки та налагодження коду, що взаємодіє з вашим API.
///
-## Документація
+## Документація { #documentation }
-Тепер коли відкриєте свій браузер за посиланням http://127.0.0.1:8000/docs, то побачите автоматично згенеровану, інтерактивну API-документацію:
+А коли ви відкриєте у браузері http://127.0.0.1:8000/docs, ви побачите автоматичну, інтерактивну, API-документацію на кшталт:
/// check | Примітка
-Знову ж таки, лише з цим самим оголошенням типу в Python, FastAPI надає вам автоматичну, інтерактивну документацію (з інтеграцією Swagger UI).
-
-Зверніть увагу, що параметр шляху оголошений як ціле число.
+Знову ж таки, лише з тим самим оголошенням типу в Python **FastAPI** надає вам автоматичну, інтерактивну документацію (з інтеграцією Swagger UI).
+Зверніть увагу, що параметр шляху оголошено як ціле число.
///
-## Переваги стандартизації, альтернативна документація
+## Переваги стандартів, альтернативна документація { #standards-based-benefits-alternative-documentation }
І оскільки згенерована схема відповідає стандарту OpenAPI, існує багато сумісних інструментів.
-З цієї причини FastAPI також надає альтернативну документацію API (використовуючи ReDoc), до якої можна отримати доступ за посиланням http://127.0.0.1:8000/redoc:
+Через це **FastAPI** також надає альтернативну API-документацію (використовуючи ReDoc), до якої ви можете отримати доступ за посиланням http://127.0.0.1:8000/redoc:
-Таким чином, існує багато сумісних інструментів, включаючи інструменти для генерації коду для багатьох мов.
+Так само, існує багато сумісних інструментів. Зокрема інструменти генерації коду для багатьох мов.
+## Pydantic { #pydantic }
-## Pydantic
+Уся валідація даних виконується за лаштунками за допомогою Pydantic, тож ви отримуєте всі переваги від його використання. І ви знаєте, що ви в надійних руках.
-Вся валідація даних виконується за лаштунками за допомогою Pydantic, тому Ви отримуєте всі переваги від його використання. І можете бути впевнені, що все в надійних руках.
+Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних.
-Ви можете використовувати ті самі оголошення типів з `str`, `float`, `bool` та багатьма іншими складними типами даних.
+Декілька з них розглядаються в наступних розділах посібника.
-Декілька з них будуть розглянуті в наступних розділах посібника.
+## Порядок має значення { #order-matters }
-## Порядок має значення
+Під час створення *операцій шляху* можуть виникати ситуації, коли у вас є фіксований шлях.
-При створенні *операцій шляху* можуть виникати ситуації, коли шлях фіксований.
+Наприклад, `/users/me` — припустімо, це для отримання даних про поточного користувача.
-Наприклад, `/users/me`. Припустимо, що це шлях для отримання даних про поточного користувача.
+І тоді у вас також може бути шлях `/users/{user_id}` для отримання даних про конкретного користувача за його ID.
-А також у вас може бути шлях `/users/{user_id}`, щоб отримати дані про конкретного користувача за його ID.
+Оскільки *операції шляху* оцінюються по черзі, вам потрібно переконатися, що шлях для `/users/me` оголошено перед шляхом для `/users/{user_id}`:
-Оскільки *операції шляху* оцінюються по черзі, Ви повинні переконатися, що шлях для `/users/me` оголошений перед шляхом для `/users/{user_id}`:
+{* ../../docs_src/path_params/tutorial003_py39.py hl[6,11] *}
-{* ../../docs_src/path_params/tutorial003.py hl[6,11] *}
+Інакше шлях для `/users/{user_id}` також відповідатиме `/users/me`, «вважаючи», що отримує параметр `user_id` зі значенням `"me"`.
-Інакше шлях для `/users/{user_id}` також буде відповідати для `/users/me`, "вважаючи", що він отримує параметр `user_id` зі значенням `"me"`.
+Так само ви не можете перевизначити операцію шляху:
-Аналогічно, Ви не можете оголосити операцію шляху:
+{* ../../docs_src/path_params/tutorial003b_py39.py hl[6,11] *}
-{* ../../docs_src/path_params/tutorial003b.py hl[6,11] *}
+Завжди використовуватиметься перша, оскільки шлях збігається першим.
-Перша операція буде завжди використовуватися, оскільки шлях збігається першим.
-## Попередньо визначені значення
+## Попередньо визначені значення { #predefined-values }
-Якщо у вас є *операція шляху*, яка приймає *параметр шляху*, але Ви хочете, щоб можливі допустимі значення *параметра шляху* були попередньо визначені, Ви можете використати стандартний Python Enum.
+Якщо у вас є *операція шляху*, яка отримує *параметр шляху*, але ви хочете, щоб можливі коректні значення *параметра шляху* були попередньо визначені, ви можете використати стандартний Python `Enum`.
-### Створення класу `Enum`
+### Створіть клас `Enum` { #create-an-enum-class }
Імпортуйте `Enum` і створіть підклас, що наслідується від `str` та `Enum`.
-Наслідуючи від `str`, документація API зможе визначити, що значення повинні бути типу `string`, і правильно їх відобразить.
-
-Після цього створіть атрибути класу з фіксованими значеннями, які будуть доступними допустимими значеннями:
+Завдяки наслідуванню від `str` документація API зможе визначити, що значення повинні бути типу `string`, і зможе коректно їх відобразити.
-{* ../../docs_src/path_params/tutorial005.py hl[1,6:9] *}
+Після цього створіть атрибути класу з фіксованими значеннями, які будуть доступними коректними значеннями:
-/// info | Додаткова інформація
-
-Перелічення (або enums) доступні в Python починаючи з версії 3.4.
-
-///
+{* ../../docs_src/path_params/tutorial005_py39.py hl[1,6:9] *}
/// tip | Порада
-Якщо вам цікаво, "AlexNet", "ResNet" та "LeNet" — це просто назви ML моделей Machine Learning.
+Якщо вам цікаво, «AlexNet», «ResNet» та «LeNet» — це просто назви Machine Learning models.
///
-
-### Оголосіть *параметр шляху*
+### Оголосіть *параметр шляху* { #declare-a-path-parameter }
Потім створіть *параметр шляху* з анотацією типу, використовуючи створений вами клас enum (`ModelName`):
-{* ../../docs_src/path_params/tutorial005.py hl[16] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[16] *}
-### Перевірка документації
+### Перевірте документацію { #check-the-docs }
-Оскільки доступні значення для *параметра шляху* визначені заздалегідь, інтерактивна документація зможе красиво їх відобразити:
+Оскільки доступні значення для *параметра шляху* визначені заздалегідь, інтерактивна документація може красиво їх показати:
-### Робота з *перелічуваннями* у Python
+### Робота з Python *переліченнями* { #working-with-python-enumerations }
-Значення *параметра шляху* буде елементом *перелічування*.
+Значення *параметра шляху* буде *елементом перелічування*.
-#### Порівняння *елементів перелічування*
+#### Порівняйте *елементи перелічування* { #compare-enumeration-members }
-Ви можете порівнювати його з *елементами перелічування* у створеному вами enum `ModelName`:
+Ви можете порівнювати його з *елементом перелічування* у створеному вами enum `ModelName`:
-{* ../../docs_src/path_params/tutorial005.py hl[17] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[17] *}
-#### Отримання *значення перелічування*
+#### Отримайте *значення перелічування* { #get-the-enumeration-value }
Ви можете отримати фактичне значення (у цьому випадку це `str`), використовуючи `model_name.value`, або загалом `your_enum_member.value`:
-{* ../../docs_src/path_params/tutorial005.py hl[20] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[20] *}
/// tip | Порада
-Ви також можете отримати доступ до значення `"lenet"`, використовуючи `ModelName.lenet.value`.
+Ви також можете отримати доступ до значення `"lenet"` через `ModelName.lenet.value`.
///
+#### Поверніть *елементи перелічування* { #return-enumeration-members }
-#### Повернення *елементів перелічування*
-
-Ви можете повертати *елементи перелічування* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`).
+Ви можете повертати *елементи enum* з вашої *операції шляху*, навіть вкладені у JSON-тіло (наприклад, `dict`).
Вони будуть перетворені на відповідні значення (у цьому випадку рядки) перед поверненням клієнту:
-{* ../../docs_src/path_params/tutorial005.py hl[18,21,23] *}
+{* ../../docs_src/path_params/tutorial005_py39.py hl[18,21,23] *}
-На стороні клієнта Ви отримаєте відповідь у форматі JSON, наприклад:
+На стороні клієнта ви отримаєте відповідь у форматі JSON, наприклад:
```JSON
{
@@ -207,36 +199,35 @@
}
```
-## Path-параметри, що містять шляхи
-
-Припустимо, у вас є *операція шляху* з маршрутом `/files/{file_path}`.
+## Параметри шляху, що містять шляхи { #path-parameters-containing-paths }
-Але вам потрібно, щоб `file_path` містив *шлях*, наприклад `home/johndoe/myfile.txt`.
+Припустімо, у вас є *операція шляху* зі шляхом `/files/{file_path}`.
-Отже, URL для цього файлу виглядатиме так: `/files/home/johndoe/myfile.txt`.
+Але вам потрібно, щоб `file_path` сам містив *шлях*, наприклад `home/johndoe/myfile.txt`.
+Отже, URL для цього файлу виглядатиме приблизно так: `/files/home/johndoe/myfile.txt`.
+### Підтримка OpenAPI { #openapi-support }
-### Підтримка OpenAPI
+OpenAPI не підтримує спосіб оголошення *параметра шляху*, який має містити всередині *шлях*, оскільки це може призвести до сценаріїв, які складно тестувати та визначати.
-OpenAPI не підтримує спосіб оголошення *параметра шляху*, що містить *шлях* всередині, оскільки це може призвести до сценаріїв, які складно тестувати та визначати.
+Проте ви все одно можете зробити це в **FastAPI**, використовуючи один із внутрішніх інструментів Starlette.
-Однак (одначе), Ви все одно можете зробити це в **FastAPI**, використовуючи один із внутрішніх інструментів Starlette.
+І документація все ще працюватиме, хоча й не додаватиме жодної документації, яка б казала, що параметр має містити шлях.
-Документація все ще працюватиме, хоча й не додаватиме опису про те, що параметр повинен містити шлях.
+### Конвертер шляху { #path-convertor }
-### Конвертер шляху
-
-Використовуючи опцію безпосередньо зі Starlette, Ви можете оголосити *параметр шляху*, що містить *шлях*, використовуючи URL на кшталт:
+Використовуючи опцію безпосередньо зі Starlette, ви можете оголосити *параметр шляху*, що містить *шлях*, використовуючи URL на кшталт:
```
/files/{file_path:path}
```
-У цьому випадку ім'я параметра — `file_path`, а остання частина `:path` вказує на те, що параметр повинен відповідати будь-якому *шляху*.
-Отже, Ви можете використати його так:
+У цьому випадку ім’я параметра — `file_path`, а остання частина `:path` вказує, що параметр має відповідати будь-якому *шляху*.
+
+Отже, ви можете використати його так:
-{* ../../docs_src/path_params/tutorial004.py hl[6] *}
+{* ../../docs_src/path_params/tutorial004_py39.py hl[6] *}
/// tip | Порада
@@ -246,15 +237,15 @@ OpenAPI не підтримує спосіб оголошення *параме
///
-## Підсумок
+## Підсумок { #recap }
-З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, Ви отримуєте:
+З **FastAPI**, використовуючи короткі, інтуїтивно зрозумілі та стандартні оголошення типів Python, ви отримуєте:
-* Підтримку в редакторі: перевірка помилок, автодоповнення тощо.
-* "Парсинг" даних
+* Підтримку редактора: перевірка помилок, автодоповнення тощо.
+* Перетворення даних «parsing»
* Валідацію даних
* Анотацію API та автоматичну документацію
І вам потрібно оголосити їх лише один раз.
-Це, ймовірно, основна видима перевага **FastAPI** порівняно з альтернативними фреймворками (окрім високої продуктивності).
+Це, ймовірно, основна видима перевага **FastAPI** порівняно з альтернативними фреймворками (окрім сирої продуктивності).
diff --git a/docs/uk/docs/tutorial/query-param-models.md b/docs/uk/docs/tutorial/query-param-models.md
index 97eb82fa1..a28bf6c27 100644
--- a/docs/uk/docs/tutorial/query-param-models.md
+++ b/docs/uk/docs/tutorial/query-param-models.md
@@ -1,4 +1,4 @@
-# Моделі Query параметрів
+# Моделі параметрів запиту { #query-parameter-models }
Якщо у Вас є група **query параметрів**, які пов’язані між собою, Ви можете створити **Pydantic-модель** для їх оголошення.
@@ -10,7 +10,7 @@
///
-## Query параметри з Pydantic-моделлю
+## Query параметри з Pydantic-моделлю { #query-parameters-with-a-pydantic-model }
Оголосіть **query параметри**, які Вам потрібні, у **Pydantic-моделі**, а потім оголосіть цей параметр як `Query`:
@@ -18,7 +18,7 @@
**FastAPI** буде **витягувати** дані для **кожного поля** з **query параметрів** у запиті та передавати їх у визначену вами Pydantic-модель.
-## Перевірте документацію
+## Перевірте документацію { #check-the-docs }
Ви можете побачити параметри запиту в UI документації за `/docs`:
@@ -26,7 +26,7 @@
-### Список параметрів запиту / кілька значень за замовчуванням
+### Список query параметрів / кілька значень за замовчуванням { #query-parameter-list-multiple-values-with-defaults }
-Ви також можете визначити значення за замовчуванням для `list`, якщо жодне значення не було передане:
+Ви також можете визначити значення за замовчуванням `list`, якщо жодне значення не було передане:
{* ../../docs_src/query_params_str_validations/tutorial012_an_py39.py hl[9] *}
-Якщо Ви перейдете за посиланням:
+Якщо ви перейдете за посиланням:
```
http://localhost:8000/items/
```
-то значення `q` за замовчуванням буде: `["foo", "bar"]`, і Ваша відповідь виглядатиме так:
+то значення `q` за замовчуванням буде: `["foo", "bar"]`, і ваша відповідь виглядатиме так:
```JSON
{
@@ -329,35 +312,35 @@ http://localhost:8000/items/
}
```
-#### Використання тільки `list`
+#### Використання тільки `list` { #using-just-list }
-Ви також можете використовувати `list` без уточнення типу, замість `list[str]`:
+Ви також можете використовувати `list` напряму замість `list[str]`:
{* ../../docs_src/query_params_str_validations/tutorial013_an_py39.py hl[9] *}
-/// note | Технічні деталі
+/// note | Примітка
Майте на увазі, що в цьому випадку FastAPI не перевірятиме вміст списку.
-Наприклад, `list[int]` перевірятиме (і документуватиме), що всі елементи списку є цілими числами. Але `list` без уточнення цього не робитиме.
+Наприклад, `list[int]` перевірятиме (і документуватиме), що вміст списку — цілі числа. Але `list` без уточнення цього не робитиме.
///
-## Додавання додаткових метаданих
+## Оголосити більше метаданих { #declare-more-metadata }
Ви можете додати більше інформації про параметр.
-Ця інформація буде включена у згенерований OpenAPI та використана в інтерфейсах документації та зовнішніх інструментах.
+Ця інформація буде включена у згенерований OpenAPI та використана інтерфейсами документації та зовнішніми інструментами.
-/// note | Технічні деталі
+/// note | Примітка
Майте на увазі, що різні інструменти можуть мати різний рівень підтримки OpenAPI.
-Деякі з них можуть ще не відображати всю додаткову інформацію, хоча в більшості випадків ця функція вже запланована для розробки.
+Деякі з них можуть ще не відображати всю додаткову інформацію, хоча в більшості випадків відсутню функцію вже заплановано до реалізації.
///
-Ви можете додати `title` :
+Ви можете додати `title`:
{* ../../docs_src/query_params_str_validations/tutorial007_an_py310.py hl[10] *}
@@ -365,9 +348,9 @@ http://localhost:8000/items/
{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## Аліаси параметрів
+## Аліаси параметрів { #alias-parameters }
-Уявіть, що Ви хочете, щоб параметр називався `item-query`.
+Уявіть, що ви хочете, щоб параметр називався `item-query`.
Наприклад:
@@ -379,19 +362,19 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
Найближчий допустимий варіант — `item_query`.
-Проте Вам потрібно, щоб параметр залишався саме `item-query`...
+Проте вам потрібно, щоб параметр залишався саме `item-query`...
У такому випадку можна оголосити `alias`, і саме він буде використовуватися для отримання значення параметра:
{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## Виведення параметрів як застарілих
+## Позначення параметрів як застарілих { #deprecating-parameters }
-Припустимо, що Ви більше не хочете використовувати цей параметр.
+Припустімо, що вам більше не подобається цей параметр.
-Вам потрібно залишити його на деякий час, оскільки ним користуються клієнти, але Ви хочете, щоб документація чітко показувала, що він є застарілим.
+Вам потрібно залишити його на деякий час, оскільки ним користуються клієнти, але ви хочете, щоб документація чітко показувала, що він є deprecated.
-Тоді Ви можете передати параметр `deprecated=True` до `Query`:
+Тоді передайте параметр `deprecated=True` до `Query`:
{* ../../docs_src/query_params_str_validations/tutorial010_an_py310.py hl[19] *}
@@ -399,27 +382,27 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
-## Виняток параметрів з OpenAPI
+## Виняток параметрів з OpenAPI { #exclude-parameters-from-openapi }
-Щоб виключити параметр запиту зі згенерованої схеми OpenAPI (і, таким чином, з автоматичних систем документації), встановіть параметр `include_in_schema` для `Query` в `False`:
+Щоб виключити query параметр зі згенерованої схеми OpenAPI (і, таким чином, з автоматичних систем документації), встановіть параметр `include_in_schema` для `Query` в `False`:
{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
-## Кастомна валідація
+## Кастомна валідація { #custom-validation }
-Можуть бути випадки, коли Вам потрібно провести **кастомну валідацію**, яку не можна реалізувати за допомогою параметрів, показаних вище.
+Можуть бути випадки, коли вам потрібно провести **кастомну валідацію**, яку не можна реалізувати за допомогою параметрів, показаних вище.
-У таких випадках ви можете використати **кастомну функцію валідації**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`).
+У таких випадках ви можете використати **кастомну функцію-валідатор**, яка буде застосована після звичайної валідації (наприклад, після перевірки, що значення є типом `str`).
Це можна досягти за допомогою Pydantic's `AfterValidator` в середині `Annotated`.
-/// tip | Підказка
+/// tip | Порада
Pydantic також має `BeforeValidator` та інші. 🤓
///
-Наприклад, цей кастомний валідатор перевіряє, чи починається ID елемента з `isbn-` для номера книги ISBN або з `imdb-` для ID URL фільму на IMDB:
+Наприклад, цей кастомний валідатор перевіряє, чи починається ID елемента з `isbn-` для номера книги ISBN або з `imdb-` для ID URL фільму на IMDB:
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
@@ -429,49 +412,49 @@ Pydantic також має ітерабельний об'єкт із кортежами, що містять ключ і значення для кожного елемента словника.
+За допомогою `data.items()` ми отримуємо iterable object із кортежами, що містять ключ і значення для кожного елемента словника.
-Ми перетворюємо цей ітерабельний об'єкт у звичайний `list` за допомогою `list(data.items())`.
+Ми перетворюємо цей iterable object у звичайний `list` за допомогою `list(data.items())`.
-Потім, використовуючи `random.choice()`, ми можемо отримати випадкове значення зі списку, тобто отримуємо кортеж із `(id, name)`. Це може бути щось на зразок `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
+Потім, використовуючи `random.choice()`, ми можемо отримати **випадкове значення** зі списку, тобто отримуємо кортеж із `(id, name)`. Це може бути щось на зразок `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
Далі ми **присвоюємо ці два значення** кортежу змінним `id` і `name`.
Тож, якщо користувач не вказав ID елемента, він все одно отримає випадкову рекомендацію.
-...і все це реалізовано в **одному рядку коду**. 🤯 Хіба не прекрасний Python? 🐍
+...ми робимо все це в **одному простому рядку**. 🤯 Хіба ви не любите Python? 🐍
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
-## Підсумок
+## Підсумок { #recap }
-Ви можете оголошувати додаткові валідації та метаінформацію для своїх параметрів.
+Ви можете оголошувати додаткові валідації та метадані для ваших параметрів.
-Загальні валідації та метаінформація:
+Загальні валідації та метадані:
* `alias`
* `title`
@@ -486,6 +469,6 @@ Pydantic також має "Парсинг" даних
+* Підтримка в редакторі (очевидно)
+* «parsing» даних
* Валідація даних
* Автоматична документація
+## Значення за замовчуванням { #defaults }
-## Значення за замовчуванням
-
-Оскільки query параметри не є фіксованою частиною шляху, вони можуть бути необов’язковими та мати значення за замовчуванням.
+Оскільки параметри query не є фіксованою частиною шляху, вони можуть бути необов’язковими та мати значення за замовчуванням.
У наведеному вище прикладі вони мають значення за замовчуванням: `skip=0` і `limit=10`.
-Отже, результат переходу за URL:
+Отже, перехід за 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
@@ -54,12 +54,12 @@ http://127.0.0.1:8000/items/?skip=20
Значення параметрів у вашій функції будуть такими:
-* `skip=20`: оскільки Ви вказали його в URL
+* `skip=20`: оскільки ви вказали його в URL
* `limit=10`: оскільки це значення за замовчуванням
-## Необов'язкові параметри
+## Необов'язкові параметри { #optional-parameters }
-Аналогічно, Ви можете оголосити необов’язкові query параметри, встановивши для них значення за замовчуванням `None`:
+Так само ви можете оголосити необов’язкові параметри query, встановивши для них значення за замовчуванням `None`:
{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}
@@ -67,18 +67,17 @@ http://127.0.0.1:8000/items/?skip=20
/// check | Примітка
-Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це query параметр.
+Також зверніть увагу, що **FastAPI** достатньо розумний, щоб визначити, що параметр шляху `item_id` є параметром шляху, а `q` — ні, отже, це параметр query.
///
-## Перетворення типу Query параметра
+## Перетворення типу параметра query { #query-parameter-type-conversion }
Ви також можете оголошувати параметри типу `bool`, і вони будуть автоматично конвертовані:
{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}
-У цьому випадку, якщо Ви звернетесь до:
-
+У цьому випадку, якщо ви перейдете за:
```
http://127.0.0.1:8000/items/foo?short=1
@@ -108,38 +107,38 @@ http://127.0.0.1:8000/items/foo?short=on
http://127.0.0.1:8000/items/foo?short=yes
```
-або будь-який інший варіант написання (великі літери, перша літера велика тощо), ваша функція побачить параметр `short` зі значенням `True` з типом даних `bool`. В іншому випадку – `False`.
+або будь-який інший варіант написання (великі літери, перша літера велика тощо), ваша функція побачить параметр `short` зі значенням `True` типу `bool`. В іншому випадку — `False`.
-## Кілька path і query параметрів
-Ви можете одночасно оголошувати кілька path і query параметрів, і **FastAPI** автоматично визначить, який з них до чого належить.
+## Кілька path і query параметрів { #multiple-path-and-query-parameters }
+Ви можете одночасно оголошувати кілька параметрів шляху та параметрів query, **FastAPI** знає, який з них який.
-Не потрібно дотримуватись певного порядку їх оголошення.
+І вам не потрібно оголошувати їх у якомусь конкретному порядку.
Вони визначаються за назвою:
{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## Обов’язкові Query параметри
+## Обов’язкові параметри query { #required-query-parameters }
-Якщо Ви оголошуєте значення за замовчуванням для параметрів, які не є path-параметрами (у цьому розділі ми бачили поки що лише path параметри), тоді вони стають необов’язковими.
+Коли ви оголошуєте значення за замовчуванням для не-path-параметрів (поки що ми бачили лише параметри query), тоді вони не є обов’язковими.
-Якщо Ви не хочете вказувати конкретні значення, але хочете зробити параметр опціональним, задайте `None` як значення за замовчуванням.
+Якщо ви не хочете задавати конкретне значення, а просто зробити параметр необов’язковим, задайте `None` як значення за замовчуванням.
-Але якщо Ви хочете зробити query параметр обов’язковим, просто не вказуйте для нього значення за замовчуванням:
+Але якщо ви хочете зробити параметр query обов’язковим, просто не вказуйте для нього значення за замовчуванням:
-{* ../../docs_src/query_params/tutorial005.py hl[6:7] *}
+{* ../../docs_src/query_params/tutorial005_py39.py hl[6:7] *}
-Тут `needy` – обов’язковий query параметр типу `str`.
+Тут параметр query `needy` — обов’язковий параметр query типу `str`.
-Якщо Ви відкриєте у браузері URL-адресу:
+Якщо ви відкриєте у браузері URL-адресу:
```
http://127.0.0.1:8000/items/foo-item
```
-...без додавання обов’язкового параметра `needy`, Ви побачите помилку:
+...без додавання обов’язкового параметра `needy`, ви побачите помилку на кшталт:
```JSON
{
@@ -163,7 +162,7 @@ http://127.0.0.1:8000/items/foo-item
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
```
-...цей запит поверне:
+...це спрацює:
```JSON
{
@@ -172,20 +171,18 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
}
```
-
-Звичайно, Ви можете визначити деякі параметри як обов’язкові, інші зі значенням за замовчуванням, а ще деякі — повністю опціональні:
+І звісно, ви можете визначити деякі параметри як обов’язкові, деякі — зі значенням за замовчуванням, а деякі — повністю необов’язкові:
{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}
-У цьому випадку є 3 query параметри:
+У цьому випадку є 3 параметри query:
* `needy`, обов’язковий `str`.
* `skip`, `int` зі значенням за замовчуванням `0`.
-* `limit`, опціональний `int`.
-
+* `limit`, необов’язковий `int`.
-/// tip | Підказка
+/// tip | Порада
-Ви також можете використовувати `Enum`-и, так само як і з [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
+Ви також можете використовувати `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
index 18b7cc01c..a6ff70dc0 100644
--- a/docs/uk/docs/tutorial/request-files.md
+++ b/docs/uk/docs/tutorial/request-files.md
@@ -1,56 +1,56 @@
-# Запит файлів
+# Запит файлів { #request-files }
Ви можете визначити файли, які будуть завантажуватися клієнтом, використовуючи `File`.
/// info | Інформація
-Щоб отримувати завантажені файли, спочатку встановіть python-multipart.
+Щоб отримувати завантажені файли, спочатку встановіть `python-multipart`.
-Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його та встановили пакет, наприклад:
+Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад:
```console
$ pip install python-multipart
```
-Це необхідно, оскільки завантажені файли передаються у вигляді "форматованих даних форми".
+Це необхідно, оскільки завантажені файли передаються у вигляді «form data».
///
-## Імпорт `File`
+## Імпорт `File` { #import-file }
Імпортуйте `File` та `UploadFile` з `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## Визначення параметрів `File`
+## Визначення параметрів `File` { #define-file-parameters }
-Створіть параметри файлів так само як Ви б створювали `Body` або `Form`:
+Створіть параметри файлів так само як ви б створювали `Body` або `Form`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[9] *}
/// info | Інформація
-`File` — це клас, який безпосередньо успадковує `Form`.
+`File` — це клас, який безпосередньо успадковує `Form`.
-Але пам’ятайте, що коли Ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи.
+Але пам’ятайте, що коли ви імпортуєте `Query`, `Path`, `File` та інші з `fastapi`, це насправді функції, які повертають спеціальні класи.
///
-/// tip | Підказка
+/// tip | Порада
-Щоб оголосити тіла файлів, Вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON).
+Щоб оголосити тіла файлів, вам потрібно використовувати `File`, тому що інакше параметри будуть інтерпретовані як параметри запиту або параметри тіла (JSON).
///
-Файли будуть завантажені у вигляді "форматованих даних форми".
+Файли будуть завантажені у вигляді «form data».
-Якщо Ви оголосите тип параметра функції обробника маршруту як `bytes`, **FastAPI** прочитає файл за Вас, і Ви отримаєте його вміст у вигляді `bytes`.
+Якщо ви оголосите тип параметра *функції операції шляху* як `bytes`, **FastAPI** прочитає файл за вас, і ви отримаєте його вміст у вигляді `bytes`.
-Однак майте на увазі, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів.
+Майте на увазі, що це означає, що весь вміст буде збережено в пам'яті. Це працюватиме добре для малих файлів.
-Але в деяких випадках Вам може знадобитися `UploadFile`.
+Але є кілька випадків, у яких вам може бути корисно використовувати `UploadFile`.
-## Параметри файлу з `UploadFile`
+## Параметри файлу з `UploadFile` { #file-parameters-with-uploadfile }
Визначте параметр файлу з типом `UploadFile`:
@@ -59,38 +59,39 @@ $ pip install python-multipart
Використання `UploadFile` має кілька переваг перед `bytes`:
* Вам не потрібно використовувати `File()` у значенні за замовчуванням параметра.
-* Використовується "буферизований" файл:
- * Файл зберігається в пам'яті до досягнення певного обмеження, після чого він записується на диск.
-* Це означає, що він добре працює для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять.
-Ви можете отримати метадані про завантажений файл.
-* Він має file-like `асинхронний файловий інтерфейс` interface.
-* Він надає фактичний об'єкт Python `SpooledTemporaryFile`, який можна передавати безпосередньо іншим бібліотекам.
+* Використовується «spooled» файл:
+ * Файл зберігається в пам'яті до досягнення максимального обмеження розміру, після чого він буде збережений на диску.
+* Це означає, що він добре працюватиме для великих файлів, таких як зображення, відео, великі двійкові файли тощо, не споживаючи всю пам'ять.
+* Ви можете отримати метадані про завантажений файл.
+* Він має file-like `async` інтерфейс.
+* Він надає фактичний об'єкт Python `SpooledTemporaryFile`, який можна передавати безпосередньо іншим бібліотекам, що очікують file-like об'єкт.
-### `UploadFile`
+### `UploadFile` { #uploadfile }
`UploadFile` має такі атрибути:
* `filename`: Рядок `str` з оригінальною назвою файлу, який був завантажений (наприклад, `myimage.jpg`).
-* `content_type`: Рядок `str` з MIME-типом (наприклад, `image/jpeg`).
-* `file`: Об'єкт SpooledTemporaryFile (файлоподібний об'єкт). Це фактичний файловий об'єкт Python, який можна безпосередньо передавати іншим функціям або бібліотекам, що очікують "файлоподібний" об'єкт.
+* `content_type`: Рядок `str` з типом вмісту (MIME type / media type) (наприклад, `image/jpeg`).
+* `file`: `SpooledTemporaryFile` (file-like об'єкт). Це фактичний файловий об'єкт Python, який ви можете передавати безпосередньо іншим функціям або бібліотекам, що очікують «file-like» об'єкт.
-`UploadFile` має такі асинхронні `async` методи. Вони викликають відповідні методи файлу під капотом (використовуючи внутрішній `SpooledTemporaryFile`).
+`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()` один раз, а потім потрібно знову прочитати вміст.
+* `seek(offset)`: Переходить до байтової позиції `offset` (`int`) у файлі.
+ * Наприклад, `await myfile.seek(0)` перейде на початок файлу.
+ * Це особливо корисно, якщо ви виконаєте `await myfile.read()` один раз, а потім потрібно знову прочитати вміст.
* `close()`: Закриває файл.
-Оскільки всі ці методи є асинхронними `async`, Вам потрібно використовувати "await":
+Оскільки всі ці методи є асинхронними `async` методами, вам потрібно їх «await»-ити.
-Наприклад, всередині `async` *функції обробки шляху* Ви можете отримати вміст за допомогою:
+Наприклад, всередині `async` *функції операції шляху* ви можете отримати вміст за допомогою:
```Python
contents = await myfile.read()
```
-Якщо Ви знаходитесь у звичайній `def` *функції обробки шляху*, Ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад:
+
+Якщо ви знаходитесь у звичайній `def` *функції операції шляху*, ви можете отримати доступ до `UploadFile.file` безпосередньо, наприклад:
```Python
contents = myfile.file.read()
@@ -98,57 +99,57 @@ contents = myfile.file.read()
/// note | Технічні деталі `async`
-Коли Ви використовуєте `async` методи, **FastAPI** виконує файлові операції у пулі потоків та очікує їх завершення.
+Коли ви використовуєте `async` методи, **FastAPI** виконує файлові методи у пулі потоків і очікує на них.
///
/// note | Технічні деталі Starlette
-`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими компонентами FastAPI.
+`UploadFile` у **FastAPI** успадковується безпосередньо від `UploadFile` у **Starlette**, але додає деякі необхідні частини, щоб зробити його сумісним із **Pydantic** та іншими частинами FastAPI.
///
-## Що таке "Form Data"
+## Що таке «Form Data» { #what-is-form-data }
-Спосіб, у який HTML-форми (``) надсилають дані на сервер, зазвичай використовує "спеціальне" кодування, відмінне від JSON.
+Спосіб, у який HTML-форми (``) надсилають дані на сервер, зазвичай використовує «спеціальне» кодування для цих даних, відмінне від JSON.
-**FastAPI** забезпечує правильне зчитування цих даних з відповідної частини запиту, а не з JSON.
+**FastAPI** забезпечить зчитування цих даних з правильного місця, а не з JSON.
/// note | Технічні деталі
-Дані з форм зазвичай кодуються за допомогою "media type" `application/x-www-form-urlencoded`, якщо вони не містять файлів.
+Дані з форм зазвичай кодуються за допомогою «media type» `application/x-www-form-urlencoded`, якщо вони не містять файлів.
-Але якщо форма містить файли, вона кодується у форматі `multipart/form-data`. Якщо Ви використовуєте `File`, **FastAPI** визначить, що потрібно отримати файли з відповідної частини тіла запиту.
+Але якщо форма містить файли, вона кодується як `multipart/form-data`. Якщо ви використовуєте `File`, **FastAPI** знатиме, що потрібно отримати файли з правильної частини тіла.
-Щоб дізнатися більше про ці типи кодування та формові поля, ознайомтеся з документацією MDN щодо POST.
+Якщо ви хочете дізнатися більше про ці типи кодування та формові поля, ознайомтеся з MDN web docs для POST.
///
-/// warning | Увага
+/// warning | Попередження
-Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але Ви не можете одночасно оголошувати поля `Body`, які мають надходити у форматі JSON, оскільки тіло запиту буде закодоване у форматі `multipart/form-data`, а не `application/json`.
+Ви можете оголосити кілька параметрів `File` і `Form` в *операції шляху*, але ви не можете одночасно оголошувати поля `Body`, які ви очікуєте отримати як JSON, оскільки запит матиме тіло, закодоване як `multipart/form-data`, а не `application/json`.
-Це не обмеження **FastAPI**, а особливість протоколу HTTP.
+Це не обмеження **FastAPI**, а частина протоколу HTTP.
///
-## Опціональне Завантаження Файлів
+## Необов’язкове завантаження файлу { #optional-file-upload }
-Файл можна зробити необов’язковим, використовуючи стандартні анотації типів і встановлюючи значення за замовчуванням `None`:
+Ви можете зробити файл необов’язковим, використовуючи стандартні анотації типів і встановивши значення за замовчуванням `None`:
{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
-## `UploadFile` із Додатковими Мета Даними
+## `UploadFile` із додатковими метаданими { #uploadfile-with-additional-metadata }
-Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, для встановлення додаткових метаданих:
+Ви також можете використовувати `File()` разом із `UploadFile`, наприклад, щоб встановити додаткові метадані:
{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
-## Завантаження Кількох Файлів
+## Завантаження кількох файлів { #multiple-file-uploads }
Можна завантажувати кілька файлів одночасно.
-Вони будуть пов’язані з одним і тим самим "form field", який передається у вигляді "form data".
+Вони будуть пов’язані з одним і тим самим «form field», який передається у вигляді «form data».
Щоб це реалізувати, потрібно оголосити список `bytes` або `UploadFile`:
@@ -160,16 +161,16 @@ contents = myfile.file.read()
Ви також можете використати `from starlette.responses import HTMLResponse`.
-**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, для зручності розробників. Однак більшість доступних відповідей надходять безпосередньо від Starlette.
+**FastAPI** надає ті ж самі `starlette.responses`, що й `fastapi.responses`, просто для зручності для вас, розробника. Але більшість доступних відповідей надходять безпосередньо від Starlette.
///
-### Завантаження декількох файлів із додатковими метаданими
+### Завантаження кількох файлів із додатковими метаданими { #multiple-file-uploads-with-additional-metadata }
-Так само як і раніше, Ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`:
+Так само як і раніше, ви можете використовувати `File()`, щоб встановити додаткові параметри навіть для `UploadFile`:
{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
-## Підсумок
+## Підсумок { #recap }
-Використовуйте `File`, `bytes`та `UploadFile`, щоб оголошувати файли для завантаження у запитах, які надсилаються у вигляді form data.
+Використовуйте `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
index 7f5759e79..1bfd368d6 100644
--- a/docs/uk/docs/tutorial/request-form-models.md
+++ b/docs/uk/docs/tutorial/request-form-models.md
@@ -1,12 +1,12 @@
-# Моделі форм (Form Models)
+# Моделі форм { #form-models }
-У FastAPI Ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**.
+У FastAPI ви можете використовувати **Pydantic-моделі** для оголошення **полів форми**.
/// info | Інформація
-Щоб використовувати форми, спочатку встановіть python-multipart.
+Щоб використовувати форми, спочатку встановіть `python-multipart`.
-Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили бібліотеку, наприклад:
+Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили його, наприклад:
```console
$ pip install python-multipart
@@ -14,21 +14,21 @@ $ pip install python-multipart
///
-/// note | Підказка
+/// note | Примітка
-Ця функція підтримується, починаючи з FastAPI версії `0.113.0`. 🤓
+Це підтримується, починаючи з FastAPI версії `0.113.0`. 🤓
///
-## Використання Pydantic-моделей для форм
+## Pydantic-моделі для форм { #pydantic-models-for-forms }
-Вам просто потрібно оголосити **Pydantic-модель** з полями, які Ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`:
+Вам просто потрібно оголосити **Pydantic-модель** з полями, які ви хочете отримати як **поля форми**, а потім оголосити параметр як `Form`:
{* ../../docs_src/request_form_models/tutorial001_an_py39.py hl[9:11,15] *}
-**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку Ви визначили.
+**FastAPI** **витягне** дані для **кожного поля** з **формових даних** у запиті та надасть вам Pydantic-модель, яку ви визначили.
-## Перевірка документації
+## Перевірте документацію { #check-the-docs }
Ви можете перевірити це в UI документації за `/docs`:
@@ -36,13 +36,13 @@ $ pip install python-multipart
POST.
+Якщо ви хочете дізнатися більше про ці кодування та поля форм, зверніться до MDN вебдокументації для POST.
///
/// warning | Попередження
-Ви можете оголосити кілька параметрів `Form` в *операції шляху*, але не можете одночасно оголосити поля `Body`, які Ви очікуєте отримати у форматі JSON, оскільки тіло запиту буде закодовано у форматі `application/x-www-form-urlencoded`, а не `application/json`.
+Ви можете оголосити кілька параметрів `Form` в *операції шляху*, але не можете одночасно оголосити поля `Body`, які ви очікуєте отримати у форматі JSON, оскільки запит матиме тіло, закодоване як `application/x-www-form-urlencoded`, а не `application/json`.
Це не обмеження **FastAPI**, а частина HTTP-протоколу.
///
-## Підсумок
+## Підсумок { #recap }
Використовуйте `Form` для оголошення вхідних параметрів у вигляді даних форми.
diff --git a/docs/uk/docs/tutorial/response-model.md b/docs/uk/docs/tutorial/response-model.md
index def1f8a2d..2fcad9438 100644
--- a/docs/uk/docs/tutorial/response-model.md
+++ b/docs/uk/docs/tutorial/response-model.md
@@ -1,36 +1,35 @@
-# Модель відповіді — Тип, що повертається
+# Модель відповіді — Тип, що повертається { #response-model-return-type }
-Ви можете оголосити тип, який використовуватиметься у відповіді, за допомогою *анотації типу, що повертається* *функцією операцією шляху* (path operation)
+Ви можете оголосити тип, який використовуватиметься у відповіді, анотувавши **тип повернення** *функції операції шляху*.
-**Анотацію типу** можна вказати так само як і для вхідних **параметрів** функції: це можуть бути моделі Pydantic, списки (lists), словники (dictionaries), скалярні значення, як-от цілі числа (integers), булеві значення (booleans) тощо.
+**Анотації типів** можна використовувати так само, як і для вхідних даних у **параметрах** функції: можна використовувати моделі Pydantic, списки, словники, скалярні значення, як-от цілі числа, булеві значення тощо.
{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
-FastAPI використовуватиме цей тип, щоб:
+FastAPI використовуватиме цей тип повернення, щоб:
* **Перевірити правильність** повернених даних.
- * Якщо дані не валідні (наприклад, відсутнє поле), це означає, що Ваш код додатку працює некоректно і не повертає те, що повинен. У такому випадку FastAPI поверне помилку сервера, замість того щоб віддати недопустимі дані. Так Ви та Ваші клієнти будете впевнені, що отримуєте очікувані дані у правильному форматі.
-
-* Додати **JSON Schema** відповіді до специфікації OpenAPI в *операціях шляху*.
+ * Якщо дані не валідні (наприклад, відсутнє поле), це означає, що *ваш* код застосунку зламаний, не повертає те, що повинен, і буде повернуто помилку сервера замість некоректних даних. Так ви та ваші клієнти можете бути впевнені, що отримаєте дані й очікувану структуру даних.
+* Додати **JSON Schema** для відповіді в OpenAPI *операції шляху*.
* Це буде використано в **автоматичній документації**.
- * А також інструментами, які автоматично генерують клієнтський код.
+ * Це також буде використано інструментами, які автоматично генерують клієнтський код.
Але найголовніше:
-* FastAPI **обмежить та відфільтрує** вихідні дані відповідно до типу, вказаного у відповіді.
- * Це особливо важливо для **безпеки**. Деталі нижче.
+* Це **обмежить та відфільтрує** вихідні дані до того, що визначено в типі повернення.
+ * Це особливо важливо для **безпеки**, нижче ми побачимо про це більше.
-## Параметр `response_model`
+## Параметр `response_model` { #response-model-parameter }
-Іноді Вам потрібно або зручно повертати інші типи даних, ніж ті, що зазначені як тип відповіді.
+Є випадки, коли вам потрібно або ви хочете повертати дані, які не зовсім відповідають тому, що оголошено типом.
-Наприклад, Ви можете **повертати словник** або об’єкт бази даних, але **оголосити модель Pydantic** як модель відповіді. Тоді модель Pydantic автоматично оброблятиме валідацію, документацію тощо.
+Наприклад, ви можете захотіти **повертати словник** або об’єкт бази даних, але **оголосити його як модель Pydantic**. Таким чином модель Pydantic виконуватиме всю документацію даних, валідацію тощо для об’єкта, який ви повернули (наприклад, словника або об’єкта бази даних).
-Якщо Ви додасте анотацію типу для повернення, редактор коду або mypy можуть поскаржитися, що функція повертає інший тип (наприклад, dict замість Item).
+Якщо ви додали анотацію типу повернення, інструменти та редактори скаржитимуться (коректною) помилкою, повідомляючи, що ваша функція повертає тип (наприклад, dict), який відрізняється від того, що ви оголосили (наприклад, модель Pydantic).
-У таких випадках можна скористатися параметром `response_model` в декораторі маршруту (наприклад, @app.get()).
+У таких випадках можна скористатися параметром *декоратора операції шляху* `response_model` замість типу повернення.
-Параметр `response_model` працює з будь-яким *оператором шляху*:
+Ви можете використовувати параметр `response_model` у будь-якій з *операцій шляху*:
* `@app.get()`
* `@app.post()`
@@ -42,33 +41,33 @@ FastAPI використовуватиме цей тип, щоб:
/// note | Примітка
-Зверніть увагу, що `response_model` є параметром методу-декоратора (`get`, `post`, тощо), а не *функцією операцією шляху* (path operation function), як це робиться з параметрами або тілом запиту.
+Зверніть увагу, що `response_model` є параметром методу «декоратора» (`get`, `post` тощо). А не вашої *функції операції шляху*, як усі параметри та тіло.
///
-`response_model` приймає такий самий тип, який Ви б вказали для поля моделі Pydantic. Тобто це може бути як Pydantic-модель, так і, наприклад, `list` із моделей Pydantic — `List[Item]`.
+`response_model` приймає такий самий тип, який ви б вказали для поля моделі Pydantic, тобто це може бути модель Pydantic, але також це може бути, наприклад, `list` моделей Pydantic, як-от `List[Item]`.
-FastAPI використовуватиме `response_model` для створення документації, валідації даних та — найважливіше — **перетворення та фільтрації вихідних даних** згідно з оголошеним типом.
+FastAPI використовуватиме цей `response_model` для виконання всієї документації даних, валідації тощо, а також для **перетворення та фільтрації вихідних даних** до оголошеного типу.
/// tip | Порада
-Якщо у Вас увімкнено сувору перевірку типів у редакторі, mypy тощо, Ви можете оголосити тип повернення функції як `Any`.
+Якщо у вас увімкнено сувору перевірку типів у редакторі, mypy тощо, ви можете оголосити тип повернення функції як `Any`.
-Таким чином, Ви повідомляєте редактору, що свідомо повертаєте будь-що. Але FastAPI усе одно виконуватиме створення документації, валідацію, фільтрацію тощо за допомогою параметра `response_model`.
+Таким чином, ви повідомляєте редактору, що свідомо повертаєте будь-що. Але FastAPI усе одно виконуватиме документацію даних, валідацію, фільтрацію тощо за допомогою `response_model`.
///
-### Пріоритет `response_model`
+### Пріоритет `response_model` { #response-model-priority }
-Якщо Ви вказуєте і тип повернення, і `response_model`, то FastAPI використовуватиме `response_model` з пріоритетом.
+Якщо ви оголошуєте і тип повернення, і `response_model`, то `response_model` матиме пріоритет і буде використаний FastAPI.
-Таким чином, Ви можете додати правильні анотації типів до ваших функцій, навіть якщо вони повертають тип, відмінний від `response_model`. Це буде корисно для редакторів коду та інструментів, таких як mypy. І при цьому FastAPI продовжить виконувати валідацію даних, генерувати документацію тощо на основі `response_model`.
+Таким чином ви можете додати правильні анотації типів до ваших функцій, навіть коли повертаєте тип, відмінний від моделі відповіді, щоб це використовували редактор і інструменти на кшталт mypy. І при цьому FastAPI все одно виконуватиме валідацію даних, документацію тощо, використовуючи `response_model`.
-Ви також можете використати `response_model=None`, щоб вимкнути створення моделі відповіді для цієї *операції шляху*. Це може знадобитися, якщо Ви додаєте анотації типів до об'єктів, які не є допустимими полями Pydantic — приклад цього Ви побачите в одному з наступних розділів.
+Ви також можете використати `response_model=None`, щоб вимкнути створення моделі відповіді для цієї *операції шляху*; це може знадобитися, якщо ви додаєте анотації типів для речей, які не є валідними полями Pydantic, приклад цього ви побачите в одному з розділів нижче.
-## Повернути ті самі вхідні дані
+## Повернути ті самі вхідні дані { #return-the-same-input-data }
-Тут ми оголошуємо модель `UserIn`, яка містить звичайний текстовий пароль:
+Тут ми оголошуємо модель `UserIn`, вона міститиме пароль у відкритому вигляді:
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
@@ -76,7 +75,7 @@ FastAPI використовуватиме `response_model` для створе
Щоб використовувати `EmailStr`, спочатку встановіть `email-validator`.
-Переконайтесь, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад:
+Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили пакет, наприклад:
```console
$ pip install email-validator
@@ -90,29 +89,29 @@ $ pip install "pydantic[email]"
///
-І ми використовуємо цю модель, щоб оголосити і вхідні, і вихідні дані:
+І ми використовуємо цю модель, щоб оголосити наші вхідні дані, і цю ж модель, щоб оголосити наші вихідні дані:
{* ../../docs_src/response_model/tutorial002_py310.py hl[16] *}
-Тепер, коли браузер створює користувача з паролем, API поверне той самий пароль у відповіді.
+Тепер, щоразу коли браузер створює користувача з паролем, API поверне той самий пароль у відповіді.
-У цьому випадку це може не бути проблемою, адже саме користувач надіслав пароль.
+У цьому випадку це може не бути проблемою, адже це той самий користувач надсилає пароль.
-Але якщо ми використаємо цю ж модель для іншої операції шляху, ми можемо випадково надіслати паролі наших користувачів кожному клієнту.
+Але якщо ми використаємо цю ж модель для іншої *операції шляху*, ми можемо надсилати паролі наших користувачів кожному клієнту.
/// danger | Обережно
-Ніколи не зберігайте пароль користувача у відкритому вигляді та не надсилайте його у відповіді, якщо тільки Ви не знаєте всі ризики і точно розумієте, що робите.
+Ніколи не зберігайте пароль користувача у відкритому вигляді та не надсилайте його у відповіді таким чином, якщо тільки ви не знаєте всіх застережень і точно розумієте, що робите.
///
-## Додайте окрему вихідну модель
+## Додати вихідну модель { #add-an-output-model }
-Замість цього ми можемо створити вхідну модель з відкритим паролем і вихідну модель без нього:
+Замість цього ми можемо створити вхідну модель з паролем у відкритому вигляді і вихідну модель без нього:
{* ../../docs_src/response_model/tutorial003_py310.py hl[9,11,16] *}
-Тут, навіть якщо *функція операції шляху* повертає об'єкт користувача, який містить пароль:
+Тут, хоча наша *функція операції шляху* повертає того самого вхідного користувача, який містить пароль:
{* ../../docs_src/response_model/tutorial003_py310.py hl[24] *}
@@ -120,107 +119,107 @@ $ pip install "pydantic[email]"
{* ../../docs_src/response_model/tutorial003_py310.py hl[22] *}
-Таким чином, **FastAPI** автоматично відфільтрує всі дані, які не вказані у вихідній моделі (за допомогою Pydantic).
+Таким чином, **FastAPI** подбає про фільтрацію всіх даних, які не оголошені у вихідній моделі (використовуючи Pydantic).
-### `response_model` або тип повернення
+### `response_model` або тип повернення { #response-model-or-return-type }
-У цьому випадку, оскільки дві моделі різні, якщо ми анотуємо тип повернення функції як `UserOut`, редактор і такі інструменти, як mypy, видадуть помилку, бо фактично ми повертаємо інший тип.
+У цьому випадку, оскільки дві моделі різні, якщо ми анотуємо тип повернення функції як `UserOut`, редактор і інструменти скаржитимуться, що ми повертаємо невалідний тип, адже це різні класи.
-Тому в цьому прикладі ми використовуємо параметр `response_model`, а не анотацію типу повернення.
+Саме тому в цьому прикладі нам треба оголосити це через параметр `response_model`.
-...але читайте далі, щоб дізнатися, як обійти це обмеження.
+...але читайте далі нижче, щоб побачити, як це обійти.
-## Тип повернення і фільтрація даних
+## Тип повернення і фільтрація даних { #return-type-and-data-filtering }
-Продовжимо з попереднього прикладу. Ми хотіли **анотувати функцію одним типом**, але при цьому повертати з неї більше даних.
+Продовжимо з попереднього прикладу. Ми хотіли **анотувати функцію одним типом**, але хотіли мати змогу повертати з функції те, що насправді містить **більше даних**.
-Ми хочемо, щоб FastAPI продовжував **фільтрувати** ці дані за допомогою response_model. Тобто навіть якщо функція повертає більше інформації, у відповіді будуть лише ті поля, які вказані у response_model.
+Ми хочемо, щоб FastAPI продовжував **фільтрувати** дані, використовуючи модель відповіді. Тобто навіть якщо функція повертає більше даних, відповідь міститиме лише поля, оголошені в моделі відповіді.
-У попередньому прикладі, оскільки класи були різні, нам довелося використовувати параметр `response_model`. Але це означає, що ми не отримуємо підтримки з боку редактора коду та інструментів перевірки типів щодо типу, який повертає функція.
+У попередньому прикладі, оскільки класи були різні, нам довелося використовувати параметр `response_model`. Але це також означає, що ми не отримуємо підтримки від редактора та інструментів, які перевіряють тип повернення функції.
-Проте в більшості випадків, коли нам потрібно зробити щось подібне, ми просто хочемо, щоб модель **відфільтрувала або прибрала** частину даних, як у цьому прикладі.
+Проте в більшості випадків, коли нам потрібно зробити щось подібне, ми просто хочемо, щоб модель **відфільтрувала/прибрала** частину даних, як у цьому прикладі.
-У таких випадках ми можемо використати класи та спадкування, щоб скористатися **анотаціями типів** функцій — це дає кращу підтримку з боку редактора та інструментів типу mypy, і при цьому FastAPI продовжує виконувати **фільтрацію даних** у відповіді.
+І в таких випадках ми можемо використати класи та спадкування, щоб скористатися **анотаціями типів** функцій і отримати кращу підтримку в редакторі та інструментах, і при цьому зберегти **фільтрацію даних** у FastAPI.
{* ../../docs_src/response_model/tutorial003_01_py310.py hl[7:10,13:14,18] *}
-Завдяки цьому ми отримуємо підтримку інструментів — від редакторів і mypy, оскільки цей код є коректним з точки зору типів, — але ми також отримуємо фільтрацію даних від FastAPI.
+Завдяки цьому ми отримуємо підтримку інструментів — від редакторів і mypy, адже цей код коректний з точки зору типів, — але ми також отримуємо фільтрацію даних від FastAPI.
Як це працює? Давайте розберемося. 🤓
-### Типи та підтримка інструментів
+### Анотації типів і підтримка інструментів { #type-annotations-and-tooling }
-Спершу подивимось, як це бачать редактори, mypy та інші інструменти.
+Спершу подивімося, як це бачать редактори, mypy та інші інструменти.
-`BaseUser` має базові поля. Потім `UserIn` успадковує `BaseUser` і додає поле `password`, отже, він матиме всі поля з обох моделей.
+`BaseUser` має базові поля. Потім `UserIn` успадковує `BaseUser` і додає поле `password`, отже він включатиме всі поля з обох моделей.
-Ми зазначаємо тип повернення функції як `BaseUser`, але фактично повертаємо екземпляр `UserIn`.
+Ми анотуємо тип повернення функції як `BaseUser`, але фактично повертаємо екземпляр `UserIn`.
-Редактор, mypy та інші інструменти не скаржитимуться на це, тому що з точки зору типізації `UserIn` є підкласом `BaseUser`, а це означає, що він є `валідним` типом, коли очікується будь-що, що є `BaseUser`.
+Редактор, mypy та інші інструменти не скаржитимуться на це, тому що з точки зору типізації `UserIn` є підкласом `BaseUser`, а це означає, що він є *валідним* типом, коли очікується будь-що, що є `BaseUser`.
-### Фільтрація даних у FastAPI
+### Фільтрація даних у FastAPI { #fastapi-data-filtering }
-Тепер для FastAPI він бачить тип повернення і переконується, що те, що Ви повертаєте, містить **тільки** поля, які оголошені у цьому типі.
+Тепер для FastAPI він побачить тип повернення і переконається, що те, що ви повертаєте, містить **лише** поля, які оголошені у цьому типі.
-FastAPI виконує кілька внутрішніх операцій з Pydantic, щоб гарантувати, що правила наслідування класів не застосовуються для фільтрації повернених даних, інакше Ви могли б повернути значно більше даних, ніж очікували.
+FastAPI виконує кілька внутрішніх операцій з Pydantic, щоб гарантувати, що ті самі правила наслідування класів не застосовуються для фільтрації повернених даних, інакше ви могли б зрештою повертати значно більше даних, ніж очікували.
-Таким чином, Ви отримуєте найкраще з двох світів: анотації типів **з підтримкою інструментів** і **фільтрацію даних**.
+Таким чином ви можете отримати найкраще з двох світів: анотації типів із **підтримкою інструментів** і **фільтрацію даних**.
-## Подивитись у документації
+## Подивитися в документації { #see-it-in-the-docs }
-Коли Ви дивитесь автоматичну документацію, Ви можете побачити, що вхідна модель і вихідна модель мають власну JSON-схему:
+Коли ви дивитеся автоматичну документацію, ви можете перевірити, що вхідна модель і вихідна модель матимуть власну JSON Schema:
-І обидві моделі використовуються для інтерактивної API-документації:
+І обидві моделі будуть використані для інтерактивної документації API:
-## Інші анотації типів повернення
+## Інші анотації типів повернення { #other-return-type-annotations }
-Існують випадки, коли Ви повертаєте щось, що не є допустимим полем Pydantic, але анотуєте це у функції лише для того, щоб отримати підтримку від інструментів (редактора, mypy тощо).
+Можуть бути випадки, коли ви повертаєте щось, що не є валідним полем Pydantic, і анотуєте це у функції лише для того, щоб отримати підтримку від інструментів (редактора, mypy тощо).
-### Повернення Response напряму
+### Повернути Response напряму { #return-a-response-directly }
Найпоширенішим випадком буде [повернення Response напряму, як пояснюється пізніше у розширеній документації](../advanced/response-directly.md){.internal-link target=_blank}.
-{* ../../docs_src/response_model/tutorial003_02.py hl[8,10:11] *}
+{* ../../docs_src/response_model/tutorial003_02_py39.py hl[8,10:11] *}
Цей простий випадок автоматично обробляється FastAPI, тому що анотація типу повернення — це клас (або підклас) `Response`.
І інструменти також будуть задоволені, бо і `RedirectResponse`, і `JSONResponse` є підкласами `Response`, отже анотація типу коректна.
-### Анотація підкласу Response
+### Анотувати підклас Response { #annotate-a-response-subclass }
-Також можна використовувати підклас `Response` у анотації типу:
+Ви також можете використати підклас `Response` в анотації типу:
-{* ../../docs_src/response_model/tutorial003_03.py hl[8:9] *}
+{* ../../docs_src/response_model/tutorial003_03_py39.py hl[8:9] *}
Це теж працюватиме, бо `RedirectResponse` — підклас `Response`, і FastAPI автоматично обробить цей простий випадок.
-### Некоректні анотації типу повернення
+### Некоректні анотації типу повернення { #invalid-return-type-annotations }
-Але коли Ви повертаєте якийсь інший довільний об’єкт, що не є валідним типом Pydantic (наприклад, об’єкт бази даних), і анотуєте його так у функції, FastAPI спробує створити Pydantic модель відповіді на основі цієї анотації типу, і це завершиться помилкою.
+Але коли ви повертаєте якийсь інший довільний об’єкт, що не є валідним типом Pydantic (наприклад, об’єкт бази даних), і анотуєте його так у функції, FastAPI спробує створити модель відповіді Pydantic на основі цієї анотації типу і це завершиться помилкою.
-Те саме станеться, якщо Ви використовуєте union між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це спричинить помилку 💥:
+Те саме станеться, якщо ви використаєте union між різними типами, де один або більше не є валідними типами Pydantic, наприклад, це завершиться помилкою 💥:
{* ../../docs_src/response_model/tutorial003_04_py310.py hl[8] *}
-...це не працює, тому що тип анотації не є типом Pydantic і не є просто класом `Response` або його підкласом, а є об’єднанням (union) — або `Response`, або `dict`.
+...це не працює, тому що анотація типу не є типом Pydantic і не є просто одним класом `Response` або його підкласом, це union (будь-який із двох) між `Response` і `dict`.
-### Відключення Моделі Відповіді
+### Вимкнути модель відповіді { #disable-response-model }
-Продовжуючи приклад вище, можливо, Ви не хочете використовувати стандартну валідацію даних, автоматичну документацію, фільтрацію тощо, які FastAPI виконує за замовчуванням.
+Продовжуючи приклад вище, можливо, ви не хочете мати стандартну валідацію даних, документацію, фільтрацію тощо, які виконує FastAPI.
-Але ви все одно можете залишити анотацію типу у функції, щоб зберегти підтримку з боку інструментів, таких як редактори коду або статичні перевірки типів (наприклад, mypy).
+Але ви можете все одно хотіти залишити анотацію типу повернення у функції, щоб отримати підтримку від інструментів, як-от редактори та перевірки типів (наприклад, mypy).
У такому випадку ви можете вимкнути генерацію моделі відповіді, встановивши `response_model=None`:
{* ../../docs_src/response_model/tutorial003_05_py310.py hl[7] *}
-Це змусить FastAPI пропустити генерацію моделі відповіді, і таким чином Ви зможете використовувати будь-які анотації типів повернення без впливу на вашу FastAPI аплікацію. 🤓
+Це змусить FastAPI пропустити генерацію моделі відповіді, і таким чином ви зможете використовувати будь-які потрібні анотації типів повернення без впливу на ваш FastAPI застосунок. 🤓
-## Параметри кодування моделі відповіді
+## Параметри кодування моделі відповіді { #response-model-encoding-parameters }
Ваша модель відповіді може мати значення за замовчуванням, наприклад:
@@ -230,19 +229,19 @@ FastAPI виконує кілька внутрішніх операцій з Pyd
* `tax: float = 10.5` має значення за замовчуванням `10.5`.
* `tags: List[str] = []` має значення за замовчуванням порожній список: `[]`.
-Але Ви можете захотіти не включати їх у результат, якщо вони фактично не були збережені.
+але ви можете захотіти не включати їх у результат, якщо вони фактично не були збережені.
-Наприклад, якщо у Вас є моделі з багатьма необов’язковими атрибутами у NoSQL базі даних, але Ви не хочете відправляти дуже довгі JSON-відповіді, повні значень за замовчуванням.
+Наприклад, якщо у вас є моделі з багатьма необов’язковими атрибутами у NoSQL базі даних, але ви не хочете надсилати дуже довгі JSON-відповіді, повні значень за замовчуванням.
-### Використовуйте параметр `response_model_exclude_unset`
+### Використовуйте параметр `response_model_exclude_unset` { #use-the-response-model-exclude-unset-parameter }
-Ви можете встановити параметр декоратора шляху `response_model_exclude_unset=True`:
+Ви можете встановити параметр *декоратора операції шляху* `response_model_exclude_unset=True`:
{* ../../docs_src/response_model/tutorial004_py310.py hl[22] *}
-і ці значення за замовчуванням не будуть включені у відповідь, тільки фактично встановлені значення.
+і ці значення за замовчуванням не будуть включені у відповідь, лише значення, які фактично встановлені.
-Отже, якщо Ви надішлете запит до цього оператора шляху для елемента з item_id `foo`, відповідь (без включення значень за замовчуванням) буде:
+Отже, якщо ви надішлете запит до цієї *операції шляху* для елемента з ID `foo`, відповідь (без включення значень за замовчуванням) буде:
```JSON
{
@@ -253,32 +252,18 @@ FastAPI виконує кілька внутрішніх операцій з Pyd
/// info | Інформація
-У Pydantic версії 1 метод називався `.dict()`, він був застарілий (але ще підтримується) у Pydantic версії 2 і перейменований у `.model_dump()`.
-
-Приклади тут використовують `.dict()` для сумісності з Pydantic v1, але Вам слід використовувати `.model_dump()`, якщо Ви можете використовувати Pydantic v2.
-
-///
-
-/// info | Інформація
-
-FastAPI використовує `.dict()` моделі Pydantic з параметром `exclude_unset`, щоб досягти цього.
-
-///
-
-/// info | Інформація
-
Ви також можете використовувати:
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
-як описано в документації Pydantic for `exclude_defaults` та `exclude_none`.
+як описано в документації Pydantic для `exclude_defaults` та `exclude_none`.
///
-#### Дані зі значеннями для полів із типовими значеннями
+#### Дані зі значеннями для полів із типовими значеннями { #data-with-values-for-fields-with-defaults }
-Але якщо Ваші дані мають значення для полів моделі з типовими значеннями, як у елемента з item_id `bar`:
+Але якщо ваші дані мають значення для полів моделі з типовими значеннями, як у елемента з ID `bar`:
```Python hl_lines="3 5"
{
@@ -288,11 +273,12 @@ FastAPI використовує `.dict()` моделі Pydantic з `http.HTTPStatus`.
+
+`status_code` також може, як альтернативу, приймати `IntEnum`, наприклад, Python `http.HTTPStatus`.
///
Він буде:
-* Повертати вказаний код статусу у відповіді.
-* Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсі користувача):
+* Повертати цей код статусу у відповіді.
+* Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсах користувача):
-/// note | Нотатка
+/// note | Примітка
Деякі коди відповіді (див. наступний розділ) вказують, що відповідь не має тіла.
-FastAPI знає про це і створить OpenAPI документацію, яка вказує, що тіла відповіді немає.
+FastAPI знає про це і створить документацію OpenAPI, яка вказує, що тіла відповіді немає.
///
-## Про HTTP статус коди
+## Про HTTP коди статусу { #about-http-status-codes }
-/// note | Нотатка
+/// note | Примітка
-Якщо Ви вже знаєте, що таке HTTP коди статусу, переходьте до наступного розділу.
+Якщо ви вже знаєте, що таке HTTP коди статусу, перейдіть до наступного розділу.
///
-В HTTP Ви надсилаєте числовий код статусу з 3 цифр як частину відповіді.
+В 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` "Помилки сервера". Ви майже ніколи не використовуєте їх напряму. Якщо в коді Вашого застосунку або на сервері щось пішло не так, автоматично буде повернено один із цих кодів статусу.
+* `100 - 199` — для «Information». Ви рідко використовуєте їх напряму. Відповіді з такими кодами статусу не можуть мати тіла.
+* **`200 - 299`** — для «Successful» відповідей. Це ті, які ви використовуватимете найчастіше.
+ * `200` — код статусу за замовчуванням, який означає, що все було «OK».
+ * Інший приклад — `201`, «Created». Його зазвичай використовують після створення нового запису в базі даних.
+ * Особливий випадок — `204`, «No Content». Цю відповідь використовують, коли немає вмісту для повернення клієнту, і тому відповідь не повинна мати тіла.
+* **`300 - 399`** — для «Redirection». Відповіді з цими кодами статусу можуть мати або не мати тіла, за винятком `304`, «Not Modified», яка не повинна мати тіла.
+* **`400 - 499`** — для відповідей «Client error». Це другий тип, який ви, ймовірно, будете використовувати найчастіше.
+ * Приклад — `404`, для відповіді «Not Found».
+ * Для загальних помилок з боку клієнта ви можете просто використовувати `400`.
+* `500 - 599` — для помилок сервера. Ви майже ніколи не використовуєте їх напряму. Коли щось піде не так у якійсь частині коду вашого застосунку або на сервері, автоматично буде повернено один із цих кодів статусу.
/// tip | Порада
-Щоб дізнатися більше про кожен код статусу і призначення кожного з них, перегляньте документацію MDN про HTTP коди статусу.
+Щоб дізнатися більше про кожен код статусу і для чого призначений кожен із них, перегляньте документацію MDN про HTTP коди статусу.
///
-## Легкий спосіб запам'ятати назви
+## Скорочення, щоб запам’ятати назви { #shortcut-to-remember-the-names }
-Розглянемо ще раз попередній приклад:
+Розглянемо попередній приклад ще раз:
-{* ../../docs_src/response_status_code/tutorial001.py hl[6] *}
+{* ../../docs_src/response_status_code/tutorial001_py39.py hl[6] *}
-`201` - це код статусу для "Created" (створено).
+`201` — це код статусу для «Created».
-Але Вам не потрібно запам'ятовувати, що означає кожен із цих кодів.
+Але вам не потрібно запам'ятовувати, що означає кожен із цих кодів.
-Ви можете використовувати зручні змінні з `fastapi.status`
+Ви можете використовувати зручні змінні з `fastapi.status`.
-{* ../../docs_src/response_status_code/tutorial002.py hl[1,6] *}
+{* ../../docs_src/response_status_code/tutorial002_py39.py hl[1,6] *}
-Ці змінні просто для зручності. Вони містять ті ж самі числа, але Ви можете скористатися автозаповненням в редакторі:
+Вони — просто для зручності, містять те саме число, але так ви можете скористатися автозаповненням редактора, щоб знайти їх:
@@ -91,10 +92,10 @@ FastAPI знає про це і створить OpenAPI документаці
Ви також можете використати `from starlette import status`.
-**FastAPI** надає ті ж самі змінні `starlette.status` як `fastapi.status`, просто для зручності розробника. Однак вони походять безпосередньо зі Starlette.
+**FastAPI** надає той самий `starlette.status` як `fastapi.status` просто як зручність для вас, розробника. Але він походить безпосередньо зі Starlette.
///
-## Зміна значення за замовчуванням
+## Зміна значення за замовчуванням { #changing-the-default }
-Далі, у Посібнику для досвідчених користувачів{.internal-link target=_blank}, Ви дізнаєтесь, як повернути інший код статусу, ніж той, який Ви оголосили тут.
+Пізніше, у [Посібнику для досвідчених користувачів](../advanced/response-change-status-code.md){.internal-link target=_blank}, ви побачите, як повертати інший код статусу, ніж значення за замовчуванням, яке ви оголошуєте тут.
diff --git a/docs/uk/docs/tutorial/schema-extra-example.md b/docs/uk/docs/tutorial/schema-extra-example.md
index 853fd5e65..54608c2ab 100644
--- a/docs/uk/docs/tutorial/schema-extra-example.md
+++ b/docs/uk/docs/tutorial/schema-extra-example.md
@@ -1,44 +1,22 @@
-# Декларування прикладів вхідних даних
+# Декларування прикладів вхідних даних { #declare-request-example-data }
Ви можете задати приклади даних, які Ваш застосунок може отримувати.
Ось кілька способів, як це зробити.
-## Додаткові дані JSON-схеми в моделях Pydantic
+## Додаткові дані JSON-схеми в моделях Pydantic { #extra-json-schema-data-in-pydantic-models }
Ви можете задати `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
+Ця додаткова інформація буде додана як є до **JSON-схеми** для цієї моделі, і вона буде використана в документації до API.
-У версії Pydantic 2 використовується атрибут `model_config`, який приймає `dict`, як описано в документації Pydantic: Конфігурація.
+Ви можете використати атрибут `model_config`, який приймає `dict`, як описано в документації Pydantic: Configuration.
Ви можете встановити `"json_schema_extra"` як `dict`, що містить будь-які додаткові дані, які Ви хочете відобразити у згенерованій JSON-схемі, включаючи `examples`.
-////
-
-//// tab | Pydantic v1
-
-У версії Pydantic 1 використовується внутрішній клас `Config` і параметр `schema_extra`, як описано в документації Pydantic: Налаштування схеми.
-
-Ви можете задати `schema_extra` як `dict`, що містить будь-які додаткові дані, які Ви хочете бачити у згенерованій JSON-схемі, включаючи `examples`.
-
-////
-
-/// tip | Підказка
+/// tip | Порада
Ви можете використати ту ж техніку, щоб розширити JSON-схему і додати власну додаткову інформацію.
@@ -50,19 +28,19 @@
OpenAPI 3.1.0 (який використовується починаючи з FastAPI 0.99.0) додав підтримку `examples`, що є частиною стандарту **JSON-схеми**.
-До цього підтримувався лише ключ `example` з одним прикладом. Він все ще підтримується в OpenAPI 3.1.0, але є застарілим і не входить до стандарту JSON Schema. Тому рекомендується перейти з `example` на `examples`. 🤓
+До цього підтримувався лише ключ `example` з одним прикладом. Він все ще підтримується в OpenAPI 3.1.0, але є застарілим і не входить до стандарту JSON Schema. Тому рекомендується перейти з `example` на `examples`. 🤓
Більше про це можна прочитати в кінці цієї сторінки.
///
-## Додаткові аргументи `Field`
+## Додаткові аргументи `Field` { #field-additional-arguments }
Коли ви використовуєте `Field()` у моделях Pydantic, Ви також можете вказати додаткові `examples`:
{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
-## `examples` у JSON-схемі — OpenAPI
+## `examples` у JSON-схемі — OpenAPI { #examples-in-json-schema-openapi }
При використанні будь-кого з наступного:
@@ -76,41 +54,41 @@ OpenAPI 3.1.0 (який використовується починаючи з F
Ви також можете задати набір `examples` з додатковою інформацією, яка буде додана до їхніх **JSON-схем** у **OpenAPI**.
-### `Body` з `examples`
+### `Body` з `examples` { #body-with-examples }
Тут ми передаємо `examples`, які містять один приклад очікуваних даних у `Body()`:
{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
-### Приклад у UI документації
+### Приклад у UI документації { #example-in-the-docs-ui }
-За допомогою будь-якого з наведених вище методів це виглядатиме так у документації за `/docs`:
+За допомогою будь-якого з наведених вище методів це виглядатиме так у `/docs`:
-### `Body` з кількома `examples`
+### `Body` з кількома `examples` { #body-with-multiple-examples }
Звичайно, Ви також можете передати кілька `examples`:
{* ../../docs_src/schema_extra_example/tutorial004_an_py310.py hl[23:38] *}
-Коли Ви це робите, приклади будуть частиною внутрішньої **JSON-схеми** для цих даних.
+Коли Ви це робите, приклади будуть частиною внутрішньої **JSON-схеми** для цих даних тіла.
-Втім, на момент написання цього (26 серпня 2023), Swagger UI — інструмент, який відповідає за відображення UI документації — не підтримує показ кількох прикладів у **JSON-схеми**. Але нижче можна прочитати про обхідний шлях.
+Втім, на момент написання цього (час написання цього), Swagger UI — інструмент, який відповідає за відображення UI документації — не підтримує показ кількох прикладів для даних у **JSON-схемі**. Але нижче можна прочитати про обхідний шлях.
-### Специфічні для OpenAPI `examples`
+### Специфічні для OpenAPI `examples` { #openapi-specific-examples }
-Ще до того, як **JSON-схема** почала підтримувати `examples`, OpenAPI вже мала підтримку поля з такою ж назвою — `examples`.
+Ще до того, як **JSON-схема** почала підтримувати `examples`, OpenAPI вже мала підтримку іншого поля, яке також називається `examples`.
-Це **специфічне для OpenAPI** поле `examples` розміщується в іншій частині специфікації OpenAPI — у **деталях кожної *операції шляху***, а не всередині самої JSON-схеми.
+Це **специфічне для OpenAPI** поле `examples` розміщується в іншому розділі специфікації OpenAPI. Воно розміщується в **деталях кожної *операції шляху***, а не всередині кожної JSON-схеми.
-Swagger UI вже давно підтримує це поле `examples`. Тому Ви можете використовувати його, щоб **відображати** кілька **прикладів у документації**.
+І Swagger UI вже давно підтримує це поле `examples`. Тому Ви можете використовувати його, щоб **відображати** різні **приклади в UI документації**.
-Це поле `examples` у специфікації OpenAPI — це `dict` (словник) з **кількома прикладами** (а не список `list`), кожен із яких може містити додаткову інформацію, що буде додана до **OpenAPI**.
+Форма цього специфічного для OpenAPI поля `examples` — це `dict` з **кількома прикладами** (а не `list`), кожен із яких має додаткову інформацію, яка також буде додана до **OpenAPI**.
-Воно не включається до JSON Schema кожного параметра, а розміщується зовні, безпосередньо в *операції шляху*.
+Воно не включається всередину кожної JSON-схеми, що міститься в OpenAPI, воно розміщується зовні, безпосередньо в *операції шляху*.
-### Використання параметра `openapi_examples`
+### Використання параметра `openapi_examples` { #using-the-openapi-examples-parameter }
Ви можете оголосити специфічні для OpenAPI `examples` у FastAPI за допомогою параметра `openapi_examples` для:
@@ -122,30 +100,32 @@ Swagger UI вже давно підтримує це поле `examples`. Том
* `Form()`
* `File()`
-Ключі словника (`dict`) ідентифікують кожен приклад, а кожне значення `dict` — кожен специфічний словник `dict` в `examples` може містити:
+Ключі `dict` ідентифікують кожен приклад, а кожне значення — це інший `dict`.
+
+Кожен специфічний `dict` прикладу в `examples` може містити:
* `summary`: короткий опис прикладу.
-* `description`: розгорнутий опис (може містити Markdown).
-* `value`: сам приклад, наприклад, словник (`dict`).
-* `externalValue`: альтернатива `value`, URL-адреса, що вказує на приклад. Проте ця опція може не підтримуватися більшістю інструментів, на відміну від `value`.
+* `description`: розгорнутий опис, який може містити Markdown.
+* `value`: це сам приклад, який буде показано, наприклад `dict`.
+* `externalValue`: альтернатива `value`, URL-адреса, що вказує на приклад. Проте це може не підтримуватися такою кількістю інструментів, як `value`.
Використання виглядає так:
{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
-### Приклади OpenAPI у UI документації
+### Приклади OpenAPI в UI документації { #openapi-examples-in-the-docs-ui }
-З параметром `openapi_examples`, доданим до `Body()`, документація `/docs` виглядатиме так:
+З `openapi_examples`, доданим до `Body()`, `/docs` виглядатиме так:
-## Технічні деталі
+## Технічні деталі { #technical-details }
-/// tip | Підказка
+/// tip | Порада
-Якщо Ви вже використовуєте **FastAPI** версії **0.99.0 або вище**, Ви можете **пропустити** цей розділ.
+Якщо Ви вже використовуєте **FastAPI** версії **0.99.0 або вище**, Ви, ймовірно, можете **пропустити** ці технічні деталі.
-Він більш актуальний для старих версій, до появи OpenAPI 3.1.0.
+Вони більш актуальні для старих версій, до появи OpenAPI 3.1.0.
Можна вважати це коротким **історичним екскурсом** у OpenAPI та JSON Schema. 🤓
@@ -155,68 +135,68 @@ Swagger UI вже давно підтримує це поле `examples`. Том
Це дуже технічна інформація про стандарти **JSON Schema** і **OpenAPI**.
-Якщо вищезгадані ідеї вже працюють у Вас — можете не заглиблюватися в ці деталі.
+Якщо вищезгадані ідеї вже працюють у Вас, цього може бути достатньо, і Вам, ймовірно, не потрібні ці деталі — можете пропустити.
///
-До OpenAPI 3.1.0 специфікація використовувала стару та модифіковану версію **JSON Schema**.
+До OpenAPI 3.1.0 OpenAPI використовував стару та модифіковану версію **JSON Schema**.
-Оскільки JSON Schema раніше не підтримувала `examples`, OpenAPI додала власне поле `examples`.
+JSON Schema не мала `examples`, тож OpenAPI додала власне поле `example` до своєї модифікованої версії.
-OpenAPI також додала `example` і `examples` до інших частин специфікації:
+OpenAPI також додала поля `example` і `examples` до інших частин специфікації:
-* `Parameter Object` (в специфікації) використовується FastAPI для:
+* `Parameter Object` (в специфікації), який використовувався утилітами FastAPI:
* `Path()`
* `Query()`
* `Header()`
* `Cookie()`
-* `Request Body Object`, в полі `content`, в `Media Type Object` (в специфікації) використовується FastAPI для:
+* `Request Body Object`, у полі `content`, у `Media Type Object` (в специфікації), який використовувався утилітами FastAPI:
* `Body()`
* `File()`
* `Form()`
/// info | Інформація
-Цей старий параметр `examples`, специфічний для OpenAPI, тепер називається `openapi_examples`, починаючи з FastAPI версії `0.103.0`.
+Цей старий специфічний для OpenAPI параметр `examples` тепер називається `openapi_examples`, починаючи з FastAPI `0.103.0`.
///
-### Поле `examples` у JSON Schema
+### Поле `examples` у JSON Schema { #json-schemas-examples-field }
Пізніше JSON Schema додала поле `examples` у нову версію специфікації.
-І вже OpenAPI 3.1.0 базується на цій новій версії (JSON Schema 2020-12), яка включає поле `examples`.
+А потім новий OpenAPI 3.1.0 базувався на найновішій версії (JSON Schema 2020-12), яка включала це нове поле `examples`.
-Тепер це поле `examples` є пріоритетним і замінює старе (і кастомне) поле `example`, яке стало застарілим.
+І тепер це нове поле `examples` має вищий пріоритет за старе одиночне (і кастомне) поле `example`, яке тепер є застарілим.
-Нове поле `examples` у JSON Schema — це **просто список (`list`)** прикладів, без додаткових метаданих (на відміну від OpenAPI).
+Це нове поле `examples` у JSON Schema — це **просто `list`** прикладів, а не `dict` з додатковими метаданими, як в інших місцях OpenAPI (описаних вище).
/// info | Інформація
-Навіть після того, як з'явився OpenAPI 3.1.0, який підтримував examples у JSON Schema, інструмент Swagger UI ще деякий час не підтримував цю версію (підтримка з’явилась з версії 5.0.0 🎉).
+Навіть після релізу OpenAPI 3.1.0 з цією новою простішою інтеграцією з JSON Schema, протягом певного часу Swagger UI, інструмент, який надає автоматичну документацію, не підтримував OpenAPI 3.1.0 (тепер підтримує, починаючи з версії 5.0.0 🎉).
Через це версії FastAPI до 0.99.0 все ще використовували версії OpenAPI нижчі за 3.1.0.
///
-### `Examples` в Pydantic і FastAPI
+### `examples` у Pydantic і FastAPI { #pydantic-and-fastapi-examples }
-Коли Ви додаєте `examples` у модель Pydantic через `schema_extra` або `Field(examples=["something"])`, ці приклади додаються до **JSON Schema** цієї моделі.
+Коли Ви додаєте `examples` у модель Pydantic через `schema_extra` або `Field(examples=["something"])`, цей приклад додається до **JSON Schema** для цієї моделі Pydantic.
-І ця **JSON Schema** Pydantic-моделі включається до **OpenAPI** Вашого API, а потім використовується в UI документації (docs UI).
+І ця **JSON Schema** Pydantic-моделі включається до **OpenAPI** Вашого API, а потім використовується в 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 (0.99.0 і вище використовують новіший OpenAPI 3.1.0), коли Ви використовували `example` або `examples` з будь-якими іншими утилітами (`Query()`, `Body()` тощо), ці приклади не додавалися до JSON Schema, що описує ці дані (навіть не до власної версії JSON Schema в OpenAPI), натомість вони додавалися безпосередньо до декларації *операції шляху* в OpenAPI (поза межами частин OpenAPI, які використовують JSON Schema).
-Але тепер, коли FastAPI 0.99.0 і вище використовують OpenAPI 3.1.0, а той — JSON Schema 2020-12, разом із Swagger UI 5.0.0 і вище — все стало більш узгодженим, і examples тепер включаються до JSON Schema.
+Але тепер, коли FastAPI 0.99.0 і вище використовує OpenAPI 3.1.0, який використовує JSON Schema 2020-12, і Swagger UI 5.0.0 і вище, все стало більш узгодженим, і приклади включаються до JSON Schema.
-### Swagger UI та специфічні для OpenAPI `examples`
+### Swagger UI та специфічні для OpenAPI `examples` { #swagger-ui-and-openapi-specific-examples }
-Раніше (станом на 26 серпня 2023 року) Swagger UI не підтримував кілька прикладів у JSON Schema, тому користувачі не мали можливості показати декілька прикладів у документації.
+Оскільки Swagger UI не підтримував кілька прикладів JSON Schema (станом на 2023-08-26), користувачі не мали можливості показати кілька прикладів у документації.
-Щоб вирішити це, FastAPI починаючи з версії 0.103.0 **додав підтримку** старого **OpenAPI-специфічного** поля `examples` через новий параметр `openapi_examples`. 🤓
+Щоб вирішити це, FastAPI `0.103.0` **додав підтримку** оголошення того самого старого **OpenAPI-специфічного** поля `examples` через новий параметр `openapi_examples`. 🤓
-### Підсумок
+### Підсумок { #summary }
-Раніше я казав, що не люблю історію... а тепер ось я — розповідаю "технічні історичні" лекції. 😅
+Раніше я казав, що не дуже люблю історію... а тепер подивіться на мене — читаю «технічні історичні» лекції. 😅
Коротко: **оновіться до FastAPI 0.99.0 або вище** — і все стане значно **простішим, узгодженим та інтуїтивно зрозумілим**, і Вам не доведеться знати всі ці історичні деталі. 😎
diff --git a/docs/uk/docs/tutorial/security/index.md b/docs/uk/docs/tutorial/security/index.md
index c3d94be8d..f1fb25178 100644
--- a/docs/uk/docs/tutorial/security/index.md
+++ b/docs/uk/docs/tutorial/security/index.md
@@ -1,70 +1,72 @@
-# Безпека
+# Безпека { #security }
Існує багато способів реалізувати безпеку, автентифікацію та авторизацію.
-Це зазвичай складна і "непроста" тема.
+І зазвичай це складна і «непроста» тема.
-У багатьох фреймворках і системах забезпечення безпеки та автентифікації займає величезну частину зусиль і коду (іноді — понад 50% всього написаного коду).
+У багатьох фреймворках і системах лише обробка безпеки та автентифікації потребує великих зусиль і коду (у багатьох випадках це може бути 50% або більше від усього написаного коду).
-**FastAPI** надає кілька інструментів, які допоможуть Вам впоратися з **безпекою** легко, швидко, стандартним способом, без необхідності вивчати всі специфікації безпеки.
+**FastAPI** надає кілька інструментів, які допоможуть вам працювати з **безпекою** легко, швидко, стандартним способом, без необхідності вивчати всі специфікації безпеки.
-Але спочатку — кілька коротких понять.
+Але спочатку розгляньмо кілька невеликих понять.
-## Поспішаєте?
+## Поспішаєте? { #in-a-hurry }
-Якщо Вам не цікаві всі ці терміни й просто потрібно *швидко* додати автентифікацію за логіном і паролем — переходьте до наступних розділів.
+Якщо вам не цікаві всі ці терміни й вам просто потрібно додати безпеку з автентифікацією на основі імені користувача та пароля *прямо зараз*, переходьте до наступних розділів.
-## OAuth2
+## OAuth2 { #oauth2 }
-OAuth2 — це специфікація, що описує кілька способів обробки автентифікації та авторизації.
+OAuth2 — це специфікація, що визначає кілька способів обробки автентифікації та авторизації.
-Це досить об'ємна специфікація, яка охоплює складні випадки використання.
+Це досить об'ємна специфікація, яка охоплює кілька складних випадків використання.
-Вона включає способи автентифікації через "третю сторону".
+Вона включає способи автентифікації через «третю сторону».
-Саме це лежить в основі "входу через Google, Facebook, X (Twitter), GitHub" тощо.
+Саме це лежить в основі всіх систем із «увійти через Facebook, Google, X (Twitter), GitHub».
-### OAuth 1
+### OAuth 1 { #oauth-1 }
-Раніше існував OAuth 1, який значно відрізняється від OAuth2 і є складнішим, оскільки містив специфікації для шифрування комунікацій.
+Раніше існував OAuth 1, який значно відрізняється від OAuth2 і є складнішим, оскільки містив прямі специфікації щодо того, як шифрувати комунікацію.
-Зараз майже не використовується.
+Зараз він не дуже популярний або використовується.
-OAuth2 не вказує, як саме шифрувати з'єднання — воно очікує, що ваш застосунок працює через HTTPS.
+OAuth2 не вказує, як саме шифрувати комунікацію — він очікує, що ваш застосунок доступний через HTTPS.
/// tip | Порада
-У розділі про **деплой** Ви побачите, як налаштувати HTTPS безкоштовно з Traefik та Let's Encrypt.
+У розділі про **деплой** ви побачите, як налаштувати HTTPS безкоштовно з Traefik та Let's Encrypt.
///
-## OpenID Connect
+## OpenID Connect { #openid-connect }
OpenID Connect — ще одна специфікація, побудована на основі **OAuth2**.
-Вона розширює OAuth2, уточнюючи деякі неоднозначності для досягнення кращої сумісності.
+Вона просто розширює OAuth2, уточнюючи деякі відносно неоднозначні речі в OAuth2, щоб зробити його більш сумісним.
-Наприклад, вхід через Google використовує OpenID Connect (який базується на OAuth2).
+Наприклад, вхід через Google використовує OpenID Connect (який під капотом використовує OAuth2).
-Але вхід через Facebook — ні. Він має власну реалізацію на базі OAuth2.
+Але вхід через Facebook не підтримує OpenID Connect. Він має власний різновид OAuth2.
-### OpenID (не "OpenID Connect")
+### OpenID (не «OpenID Connect») { #openid-not-openid-connect }
-Існувала також специфікація "OpenID", яка намагалася розвʼязати ті самі задачі, що й **OpenID Connect**, але не базувалась на OAuth2.
+Існувала також специфікація «OpenID». Вона намагалася розвʼязати те саме, що й **OpenID Connect**, але не базувалась на OAuth2.
-Це була зовсім інша система, і сьогодні вона майже не використовується.
+Тож це була повністю додаткова система.
-## OpenAPI
+Зараз вона не дуже популярна або використовується.
-OpenAPI (раніше Swagger) — це специфікація для побудови API (тепер під егідою Linux Foundation).
+## OpenAPI { #openapi }
+
+OpenAPI (раніше відомий як Swagger) — це відкрита специфікація для побудови API (тепер частина Linux Foundation).
**FastAPI** базується на **OpenAPI**.
-Завдяки цьому Ви отримуєте автоматичну інтерактивну документацію, генерацію коду та багато іншого.
+Саме це робить можливими кілька автоматичних інтерактивних інтерфейсів документації, генерацію коду тощо.
-OpenAPI дозволяє описувати різні "схеми" безпеки.
+OpenAPI має спосіб визначати різні «схеми» безпеки.
-Використовуючи їх, Ви можете скористатися всіма цими інструментами, що базуються на стандартах, зокрема інтерактивними системами документації.
+Використовуючи їх, ви можете скористатися всіма цими інструментами, що базуються на стандартах, зокрема цими інтерактивними системами документації.
OpenAPI визначає такі схеми безпеки:
@@ -72,33 +74,33 @@ OpenAPI визначає такі схеми безпеки:
* Параметр запиту.
* Заголовок.
* Cookie.
-* `http`: стандартні методи HTTP-автентифікації, включаючи:
- * `bearer`: заголовок `Authorization` зі значенням `Bearer` та токеном. Це успадковано з OAuth2.
- * HTTP Basic автентифікація
- * HTTP Digest, тощо.
+* `http`: стандартні системи HTTP-автентифікації, включаючи:
+ * `bearer`: заголовок `Authorization` зі значенням `Bearer ` та токеном. Це успадковано з OAuth2.
+ * HTTP Basic автентифікацію.
+ * HTTP Digest тощо.
* `oauth2`: усі способи обробки безпеки за допомогою OAuth2 (так звані «потоки»).
- * Деякі з цих потоків підходять для створення власного провайдера автентифікації OAuth 2.0 (наприклад, Google, Facebook, X (Twitter), GitHub тощо):
- * `implicit`— неявний
- * `clientCredentials`— облікові дані клієнта
- * `authorizationCode` — код авторизації
- * Але є один окремий «потік», який ідеально підходить для реалізації автентифікації всередині одного додатку:
- * `password`: у наступних розділах буде приклад використання цього потоку.
-* `openIdConnect`: дозволяє автоматично виявляти параметри автентифікації OAuth2.
- * Це автоматичне виявлення визначається у специфікації OpenID Connect.
+ * Декілька з цих потоків підходять для створення провайдера автентифікації OAuth 2.0 (наприклад, Google, Facebook, X (Twitter), GitHub тощо):
+ * `implicit`
+ * `clientCredentials`
+ * `authorizationCode`
+ * Але є один окремий «потік», який можна ідеально використати для обробки автентифікації напряму в цьому ж застосунку:
+ * `password`: у кількох наступних розділах будуть приклади цього.
+* `openIdConnect`: має спосіб визначити, як автоматично виявляти дані автентифікації OAuth2.
+ * Саме це автоматичне виявлення визначено у специфікації OpenID Connect.
/// tip | Порада
-Інтеграція інших провайдерів автентифікації/авторизації, таких як Google, Facebook, X (Twitter), GitHub тощо — також можлива і відносно проста.
+Інтеграція інших провайдерів автентифікації/авторизації, таких як Google, Facebook, X (Twitter), GitHub тощо, також можлива і відносно проста.
-Найскладніше — це створити власного провайдера автентифікації/авторизації, як Google чи Facebook. Але **FastAPI** надає Вам інструменти, щоб зробити це легко, беручи на себе важку частину роботи.
+Найскладніше — це створити провайдера автентифікації/авторизації на кшталт таких, але **FastAPI** надає вам інструменти, щоб зробити це легко, виконуючи важку частину роботи за вас.
///
-## Інструменти **FastAPI**
+## Утиліти **FastAPI** { #fastapi-utilities }
-FastAPI надає кілька інструментів для кожної з описаних схем безпеки в модулі `fastapi.security`, які спрощують використання цих механізмів захисту.
+FastAPI надає кілька інструментів для кожної з описаних схем безпеки в модулі `fastapi.security`, які спрощують використання цих механізмів безпеки.
-У наступних розділах Ви побачите, як додати безпеку до свого API за допомогою цих інструментів **FastAPI**.
+У наступних розділах ви побачите, як додати безпеку до свого API за допомогою цих інструментів, які надає **FastAPI**.
-А також побачите, як вона автоматично інтегрується в інтерактивну документацію вашого API.
+А також побачите, як це автоматично інтегрується в інтерактивну систему документації.
diff --git a/docs/uk/docs/tutorial/static-files.md b/docs/uk/docs/tutorial/static-files.md
index a84782d8f..32ca1311d 100644
--- a/docs/uk/docs/tutorial/static-files.md
+++ b/docs/uk/docs/tutorial/static-files.md
@@ -1,13 +1,13 @@
-# Статичні файли
+# Статичні файли { #static-files }
Ви можете автоматично надавати статичні файли з каталогу, використовуючи `StaticFiles`.
-## Використання `StaticFiles`
+## Використання `StaticFiles` { #use-staticfiles }
* Імпортуйте `StaticFiles`.
-* "Під'єднати" екземпляр `StaticFiles()` з вказанням необхідного шляху.
+* «Під'єднати» екземпляр `StaticFiles()` з вказанням необхідного шляху.
-{* ../../docs_src/static_files/tutorial001.py hl[2,6] *}
+{* ../../docs_src/static_files/tutorial001_py39.py hl[2,6] *}
/// note | Технічні деталі
@@ -17,24 +17,24 @@
///
-### Що таке "Під'єднання"
+### Що таке «Під'єднання» { #what-is-mounting }
-"Під'єднання" означає додавання повноцінного "незалежного" застосунку за певним шляхом, який потім обробляє всі під шляхи.
+«Під'єднання» означає додавання повноцінного «незалежного» застосунку за певним шляхом, який потім обробляє всі під шляхи.
-Це відрізняється від використання `APIRouter`, оскільки під'єднаний застосунок є повністю незалежним. OpenAPI та документація вашого основного застосунку не будуть знати нічого про ваш під'єднаний застосунок.
+Це відрізняється від використання `APIRouter`, оскільки під'єднаний застосунок є повністю незалежним. OpenAPI та документація вашого основного застосунку не будуть знати нічого про ваш під'єднаний застосунок тощо.
Ви можете дізнатися більше про це в [Посібнику для просунутих користувачів](../advanced/index.md){.internal-link target=_blank}.
-## Деталі
+## Деталі { #details }
-Перше `"/static"` вказує на під шлях, за яким буде "під'єднано" цей новий "застосунок". Тому будь-який шлях, який починається з `"/static"`, буде оброблятися ним.
+Перше `"/static"` вказує на під шлях, за яким буде «під'єднано» цей новий «підзастосунок». Тому будь-який шлях, який починається з `"/static"`, буде оброблятися ним.
-`directory="static"` визначає каталог, що містить ваші статичні файли.
+`directory="static"` визначає назву каталогу, що містить ваші статичні файли.
`name="static"` це ім'я, яке можна використовувати всередині **FastAPI**.
-Усі ці параметри можуть бути змінені відповідно до потреб і особливостей вашого застосунку.
+Усі ці параметри можуть бути іншими за "`static`", налаштуйте їх відповідно до потреб і особливостей вашого застосунку.
-## Додаткова інформація
+## Додаткова інформація { #more-info }
-Детальніше про налаштування та можливості можна дізнатися в документації Starlette про статичні файли.
+Детальніше про налаштування та можливості можна дізнатися в документації Starlette про статичні файли.
diff --git a/docs/uk/docs/tutorial/testing.md b/docs/uk/docs/tutorial/testing.md
index 25fc370d6..462592829 100644
--- a/docs/uk/docs/tutorial/testing.md
+++ b/docs/uk/docs/tutorial/testing.md
@@ -1,17 +1,18 @@
-# Тестування
+# Тестування { #testing }
-Тестування **FastAPI** додатків є простим та ефективним завдяки бібліотеці Starlette, яка базується на HTTPX.
-Оскільки HTTPX розроблений на основі Requests, його API є інтуїтивно зрозумілим для тих, хто вже знайомий з Requests.
+Завдяки Starlette тестувати застосунки **FastAPI** просто й приємно.
-З його допомогою Ви можете використовувати pytest безпосередньо з **FastAPI**.
+Воно базується на HTTPX, який, своєю чергою, спроєктований на основі Requests, тож він дуже знайомий та інтуїтивно зрозумілий.
-## Використання `TestClient`
+З його допомогою ви можете використовувати pytest безпосередньо з **FastAPI**.
+
+## Використання `TestClient` { #using-testclient }
/// info | Інформація
Щоб використовувати `TestClient`, спочатку встановіть `httpx`.
-Переконайтеся, що Ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили саму бібліотеку, наприклад:
+Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його, а потім встановили `httpx`, наприклад:
```console
$ pip install httpx
@@ -21,7 +22,7 @@ $ pip install httpx
Імпортуйте `TestClient`.
-Створіть `TestClient`, передавши йому Ваш застосунок **FastAPI**.
+Створіть `TestClient`, передавши йому ваш застосунок **FastAPI**.
Створюйте функції з іменами, що починаються з `test_` (це стандартна угода для `pytest`).
@@ -29,8 +30,7 @@ $ pip install httpx
Записуйте прості `assert`-вирази зі стандартними виразами Python, які потрібно перевірити (це також стандарт для `pytest`).
-{* ../../docs_src/app_testing/tutorial001.py hl[2,12,15:18] *}
-
+{* ../../docs_src/app_testing/tutorial001_py39.py hl[2,12,15:18] *}
/// tip | Порада
@@ -46,25 +46,25 @@ $ pip install httpx
Ви також можете використовувати `from starlette.testclient import TestClient`.
-**FastAPI** надає той самий `starlette.testclient` під назвою `fastapi.testclient` для зручності розробників, але він безпосередньо походить із Starlette.
+**FastAPI** надає той самий `starlette.testclient` під назвою `fastapi.testclient` просто для зручності для вас, розробника. Але він безпосередньо походить із Starlette.
///
/// tip | Порада
-Якщо Вам потрібно викликати `async`-функції у ваших тестах, окрім відправлення запитів до FastAPI-застосунку (наприклад, асинхронні функції роботи з базою даних), перегляньте [Асинхронні тести](../advanced/async-tests.md){.internal-link target=_blank} у розширеному керівництві.
+Якщо ви хочете викликати `async`-функції у ваших тестах, окрім відправлення запитів до вашого застосунку FastAPI (наприклад, асинхронні функції роботи з базою даних), перегляньте [Async Tests](../advanced/async-tests.md){.internal-link target=_blank} у розширеному керівництві.
///
-## Розділення тестів
+## Розділення тестів { #separating-tests }
-У реальному застосунку Ваші тести, ймовірно, будуть в окремому файлі.
+У реальному застосунку ваші тести, ймовірно, будуть в окремому файлі.
-Також Ваш **FastAPI**-застосунок може складатися з кількох файлів або модулів тощо.
+Також ваш застосунок **FastAPI** може складатися з кількох файлів/модулів тощо.
-### Файл застосунку **FastAPI**
+### Файл застосунку **FastAPI** { #fastapi-app-file }
-Припустимо, у Вас є структура файлів, описана в розділі [Більші застосунки](bigger-applications.md){.internal-link target=_blank}:
+Припустимо, у вас є структура файлів, описана в розділі [Bigger Applications](bigger-applications.md){.internal-link target=_blank}:
```
.
@@ -72,14 +72,15 @@ $ pip install httpx
│ ├── __init__.py
│ └── main.py
```
-У файлі `main.py` знаходиться Ваш застосунок **FastAPI** :
-{* ../../docs_src/app_testing/main.py *}
+У файлі `main.py` знаходиться ваш застосунок **FastAPI**:
-### Файл тестування
-Ви можете створити файл `test_main.py` з Вашими тестами. Він може знаходитися в тому ж пакеті Python (у тій самій директорії з файлом `__init__.py`):
+{* ../../docs_src/app_testing/app_a_py39/main.py *}
+### Файл тестування { #testing-file }
+
+Ви можете створити файл `test_main.py` з вашими тестами. Він може знаходитися в тому ж пакеті Python (у тій самій директорії з файлом `__init__.py`):
``` hl_lines="5"
.
@@ -89,18 +90,18 @@ $ pip install httpx
│ └── test_main.py
```
-Оскільки цей файл знаходиться в тому ж пакеті, Ви можете використовувати відносний імпорт, щоб імпортувати об'єкт `app` із модуля `main` (`main.py`):
+Оскільки цей файл знаходиться в тому ж пакеті, ви можете використовувати відносний імпорт, щоб імпортувати об'єкт `app` із модуля `main` (`main.py`):
-{* ../../docs_src/app_testing/test_main.py hl[3] *}
+{* ../../docs_src/app_testing/app_a_py39/test_main.py hl[3] *}
...і написати код для тестів так само як і раніше.
-## Тестування: розширений приклад
+## Тестування: розширений приклад { #testing-extended-example }
Тепер розширимо цей приклад і додамо більше деталей, щоб побачити, як тестувати різні частини.
-### Розширений файл застосунку **FastAPI**
+### Розширений файл застосунку **FastAPI** { #extended-fastapi-app-file }
Залишимо ту саму структуру файлів:
@@ -112,75 +113,26 @@ $ pip install httpx
│ └── test_main.py
```
-Припустимо, що тепер файл `main.py` із Вашим **FastAPI**-застосунком містить додаткові операції шляху (**path operations**).
+Припустимо, що тепер файл `main.py` із вашим застосунком **FastAPI** містить інші **операції шляху**.
Він має `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
+Обидві *операції шляху* вимагають заголовок `X-Token`.
-/// tip | Порада
-
-Бажано використовувати версію з `Annotated`, якщо це можливо
-
-///
-
-```Python
-{!> ../../docs_src/app_testing/app_b_py310/main.py!}
-```
-
-////
-
-//// tab | Python 3.8+ non-Annotated
+{* ../../docs_src/app_testing/app_b_an_py310/main.py *}
-/// tip | Порада
-
-Бажано використовувати версію з `Annotated`, якщо це можливо
-
-///
+### Розширений тестовий файл { #extended-testing-file }
-```Python
-{!> ../../docs_src/app_testing/app_b/main.py!}
-```
-
-////
+Потім ви можете оновити `test_main.py`, додавши розширені тести:
-### Розширений тестовий файл
+{* ../../docs_src/app_testing/app_b_an_py310/test_main.py *}
-Потім Ви можете оновити `test_main.py`, додавши розширені тести:
-{* ../../docs_src/app_testing/app_b/test_main.py *}
+Коли вам потрібно передати клієнту інформацію в запиті, але ви не знаєте, як це зробити, ви можете пошукати (Google), як це зробити в `httpx`, або навіть як це зробити з `requests`, оскільки дизайн HTTPX базується на дизайні Requests.
-Коли Вам потрібно передати клієнту інформацію в запиті, але Ви не знаєте, як це зробити, Ви можете пошукати (наприклад, у Google) спосіб реалізації в `httpx`, або навіть у `requests`, оскільки HTTPX розроблений на основі дизайну Requests.
-
-Далі Ви просто повторюєте ці ж дії у ваших тестах.
+Далі ви просто повторюєте ці ж дії у ваших тестах.
Наприклад:
@@ -195,15 +147,16 @@ $ pip install httpx
/// info | Інформація
Зверніть увагу, що `TestClient` отримує дані, які можна конвертувати в JSON, а не Pydantic-моделі.
-Якщо у Вас є Pydantic-модель у тесті, і Ви хочете передати її дані в додаток під час тестування, Ви можете використати `jsonable_encoder`, описаний у розділі [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}.
+
+Якщо у вас є Pydantic-модель у тесті, і ви хочете передати її дані в застосунок під час тестування, ви можете використати `jsonable_encoder`, описаний у розділі [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}.
///
-## Запуск тестів
+## Запуск { #run-it }
Після цього вам потрібно встановити `pytest`.
-Переконайтеся, що Ви створили [віртуальне середовище]{.internal-link target=_blank}, активували його і встановили необхідні пакети, наприклад:
+Переконайтеся, що ви створили [віртуальне середовище](../virtual-environments.md){.internal-link target=_blank}, активували його і встановили необхідні пакети, наприклад:
-
-
- FastAPI framework, hiệu năng cao, dễ học, dễ code, sẵn sàng để tạo ra sản phẩm -
- - ---- - -**Tài liệu**: https://fastapi.tiangolo.com - -**Mã nguồn**: https://github.com/fastapi/fastapi - ---- - -FastAPI là một web framework hiện đại, hiệu năng cao để xây dựng web APIs với Python dựa trên tiêu chuẩn Python type hints. - -Những tính năng như: - -* **Nhanh**: Hiệu năng rất cao khi so sánh với **NodeJS** và **Go** (cảm ơn Starlette và Pydantic). [Một trong những Python framework nhanh nhất](#hieu-nang). -* **Code nhanh**: Tăng tốc độ phát triển tính năng từ 200% tới 300%. * -* **Ít lỗi hơn**: Giảm khoảng 40% những lỗi phát sinh bởi con người (nhà phát triển). * -* **Trực giác tốt hơn**: Được các trình soạn thảo hỗ tuyệt vời. Completion mọi nơi. Ít thời gian gỡ lỗi. -* **Dễ dàng**: Được thiết kế để dễ dàng học và sử dụng. Ít thời gian đọc tài liệu. -* **Ngắn**: Tối thiểu code bị trùng lặp. Nhiều tính năng được tích hợp khi định nghĩa tham số. Ít lỗi hơn. -* **Tăng tốc**: Có được sản phẩm cùng với tài liệu (được tự động tạo) có thể tương tác. -* **Được dựa trên các tiêu chuẩn**: Dựa trên (và hoàn toàn tương thích với) các tiêu chuẩn mở cho APIs : OpenAPI (trước đó được biết đến là Swagger) và JSON Schema. - -* ước tính được dựa trên những kiểm chứng trong nhóm phát triển nội bộ, xây dựng các ứng dụng sản phẩm. - -## Nhà tài trợ - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Nếu bạn đang xây dựng một CLI - ứng dụng được sử dụng trong giao diện dòng lệnh, xem về **Typer**.
-
-**Typer** là một người anh em của FastAPI. Và nó được dự định trở thành **giao diện dòng lệnh cho FastAPI**. ⌨️ 🚀
-
-## Yêu cầu
-
-FastAPI đứng trên vai những người khổng lồ:
-
-* Starlette cho phần web.
-* Pydantic cho phần data.
-
-## Cài đặt
-
-async def...uvicorn main:app --reload...email-validator - cho email validation.
-
-Sử dụng Starlette:
-
-* httpx - Bắt buộc nếu bạn muốn sử dụng `TestClient`.
-* jinja2 - Bắt buộc nếu bạn muốn sử dụng cấu hình template engine mặc định.
-* python-multipart - Bắt buộc nếu bạn muốn hỗ trợ "parsing", form với `request.form()`.
-* itsdangerous - Bắt buộc để hỗ trợ `SessionMiddleware`.
-* pyyaml - Bắt buộc để hỗ trợ `SchemaGenerator` cho Starlette (bạn có thể không cần nó trong FastAPI).
-
-Sử dụng bởi FastAPI / Starlette:
-
-* uvicorn - Server để chạy ứng dụng của bạn.
-* orjson - Bắt buộc nếu bạn muốn sử dụng `ORJSONResponse`.
-* ujson - Bắt buộc nếu bạn muốn sử dụng `UJSONResponse`.
-
-Bạn có thể cài đặt tất cả những dependency trên với `pip install "fastapi[all]"`.
-
-## Giấy phép
-
-Dự án này được cấp phép dưới những điều lệ của giấy phép MIT.
diff --git a/docs/vi/docs/python-types.md b/docs/vi/docs/python-types.md
deleted file mode 100644
index 403e89930..000000000
--- a/docs/vi/docs/python-types.md
+++ /dev/null
@@ -1,593 +0,0 @@
-# Giới thiệu kiểu dữ liệu Python
-
-Python hỗ trợ tùy chọn "type hints" (còn được gọi là "type annotations").
-
-Những **"type hints"** hay chú thích là một cú pháp đặc biệt cho phép khai báo kiểu dữ liệu của một biến.
-
-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 soạn thảo và các công cụ có thể hỗ trợ bạn tốt hơn.
-
-Đây chỉ là một **hướng dẫn nhanh** về gợi ý kiểu dữ liệu trong Python. Nó chỉ bao gồm những điều cần thiết tối thiểu để sử dụng chúng với **FastAPI**... đó thực sự là rất ít.
-
-**FastAPI** hoàn toàn được dựa trên những gợi ý kiểu dữ liệu, chúng mang đến nhiều ưu điểm và lợi ích.
-
-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.
-
-///
-
-## Động lực
-
-Hãy bắt đầu với một ví dụ đơn giản:
-
-{* ../../docs_src/python_types/tutorial001.py *}
-
-
-Kết quả khi gọi chương trình này:
-
-```
-John Doe
-```
-
-Hàm thực hiện như sau:
-
-* Lấy một `first_name` và `last_name`.
-* 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.
-
-{* ../../docs_src/python_types/tutorial001.py hl[2] *}
-
-
-### Sửa đổi
-
-Nó là một chương trình rất đơn giản.
-
-Nhưng bây giờ hình dung rằng bạn đang viết nó từ đầu.
-
-Tại một vài thời điểm, bạn sẽ bắt đầu định nghĩa hàm, bạn có các tham số...
-
-Nhưng sau đó bạn phải gọi "phương thức chuyển đổi kí tự đầu tiên sang kiểu chữ hoa".
-
-Có phải là `upper`? Có phải là `uppercase`? `first_uppercase`? `capitalize`?
-
-Sau đó, bạn thử hỏi người bạn cũ của mình, autocompletion của trình soạn thảo.
-
-Bạn gõ tham số đầu tiên của hàm, `first_name`, sau đó một dấu chấm (`.`) và sau đó ấn `Ctrl+Space` để kích hoạt bộ hoàn thành.
-
-Nhưng đáng buồn, bạn không nhận được điều gì hữu ích cả:
-
-
-
-### Thêm kiểu dữ liệu
-
-Hãy sửa một dòng từ phiên bản trước.
-
-Chúng ta sẽ thay đổi chính xác đoạn này, tham số của hàm, từ:
-
-```Python
- first_name, last_name
-```
-
-sang:
-
-```Python
- first_name: str, last_name: str
-```
-
-Chính là nó.
-
-Những thứ đó là "type hints":
-
-{* ../../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ư:
-
-```Python
- first_name="john", last_name="doe"
-```
-
-Nó là một thứ khác.
-
-Chúng ta sử dụng dấu hai chấm (`:`), không phải dấu bằng (`=`).
-
-Và việc thêm gợi ý kiểu dữ liệu không làm thay đổi những gì xảy ra so với khi chưa thêm chúng.
-
-But now, imagine you are again in the middle of creating that function, but with type hints.
-
-Tại cùng một điểm, bạn thử kích hoạt autocomplete với `Ctrl+Space` và bạn thấy:
-
-
-
-Với cái đó, bạn có thể cuộn, nhìn thấy các lựa chọn, cho đến khi bạn tìm thấy một "tiếng chuông":
-
-
-
-## Động lực nhiều hơn
-
-Kiểm tra hàm này, nó đã có gợi ý kiểu dữ liệu:
-
-{* ../../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:
-
-
-
-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)`:
-
-{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-
-
-## Khai báo các kiểu dữ liệu
-
-Bạn mới chỉ nhìn thấy những nơi chủ yếu để đặt khai báo kiểu dữ liệu. Như là các tham số của hàm.
-
-Đây cũng là nơi chủ yếu để bạn sử dụng chúng với **FastAPI**.
-
-### Kiểu dữ liệu đơn giản
-
-Bạn có thể khai báo tất cả các kiểu dữ liệu chuẩn của Python, không chỉ là `str`.
-
-Bạn có thể sử dụng, ví dụ:
-
-* `int`
-* `float`
-* `bool`
-* `bytes`
-
-{* ../../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
-
-Có một vài cấu trúc dữ liệu có thể chứa các giá trị khác nhau như `dict`, `list`, `set` và `tuple`. Và những giá trị nội tại cũng có thể có kiểu dữ liệu của chúng.
-
-Những kiểu dữ liệu nội bộ này được gọi là những kiểu dữ liệu "**tổng quát**". Và có khả năng khai báo chúng, thậm chí với các kiểu dữ liệu nội bộ của chúng.
-
-Để khai báo những kiểu dữ liệu và những kiểu dữ liệu nội bộ đó, bạn có thể sử dụng mô đun chuẩn của Python là `typing`. Nó có hỗ trợ những gợi ý kiểu dữ liệu này.
-
-#### Những phiên bản mới hơn của Python
-
-Cú pháp sử dụng `typing` **tương thích** với tất cả các phiên bản, từ Python 3.6 tới những phiên bản cuối cùng, bao gồm Python 3.9, Python 3.10,...
-
-As Python advances, **những phiên bản mới** mang tới sự hỗ trợ được cải tiến cho những chú thích kiểu dữ liệu và trong nhiều trường hợp bạn thậm chí sẽ không cần import và sử dụng mô đun `typing` để khai báo chú thích kiểu dữ liệu.
-
-Nếu bạn có thể chọn một phiên bản Python gần đây hơn cho dự án của bạn, ban sẽ có được những ưu điểm của những cải tiến đơn giản đó.
-
-Trong tất cả các tài liệu tồn tại những ví dụ tương thích với mỗi phiên bản Python (khi có một sự khác nhau).
-
-Cho ví dụ "**Python 3.6+**" có nghĩa là nó tương thích với Python 3.7 hoặc lớn hơn (bao gồm 3.7, 3.8, 3.9, 3.10,...). và "**Python 3.9+**" nghĩa là nó tương thích với Python 3.9 trở lên (bao gồm 3.10,...).
-
-Nếu bạn có thể sử dụng **phiên bản cuối cùng của Python**, sử dụng những ví dụ cho phiên bản cuối, những cái đó sẽ có **cú pháp đơn giản và tốt nhât**, ví dụ, "**Python 3.10+**".
-
-#### List
-
-Ví dụ, hãy định nghĩa một biến là `list` các `str`.
-
-//// tab | Python 3.9+
-
-Khai báo biến với cùng dấu hai chấm (`:`).
-
-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:
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-Từ `typing`, import `List` (với chữ cái `L` viết hoa):
-
-```Python hl_lines="1"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-Khai báo biến với cùng dấu hai chấm (`:`).
-
-Tương tự như kiểu dữ liệu, `List` bạn import từ `typing`.
-
-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:
-
-```Python hl_lines="4"
-{!> ../../docs_src/python_types/tutorial006.py!}
-```
-
-////
-
-/// 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ế.
-
-///
-
-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:
-
-
-
-Đa phần đều không thể đạt được nếu không có các kiểu dữ liệu.
-
-Chú ý rằng, biến `item` là một trong các phần tử trong danh sách `items`.
-
-Và do vậy, trình soạn thảo biết nó là một `str`, và cung cấp sự hỗ trợ cho nó.
-
-#### Tuple and Set
-
-Bạn sẽ làm điều tương tự để khai báo các `tuple` và các `set`:
-
-//// 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!}
-```
-
-////
-
-Điều này có nghĩa là:
-
-* Biến `items_t` là một `tuple` với 3 phần tử, một `int`, một `int` nữa, và một `str`.
-* Biến `items_s` là một `set`, và mỗi phần tử của nó có kiểu `bytes`.
-
-#### Dict
-
-Để định nghĩa một `dict`, bạn truyền 2 tham số kiểu dữ liệu, phân cách bởi dấu phẩy.
-
-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`.
-
-//// 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!}
-```
-
-////
-
-Điều này có nghĩa là:
-
-* Biến `prices` là một `dict`:
- * Khóa của `dict` này là kiểu `str` (đó là tên của mỗi vật phẩm).
- * Giá trị của `dict` này là kiểu `float` (đó là giá của mỗi vật phẩm).
-
-#### Union
-
-Bạn có thể khai báo rằng một biến có thể là **một vài kiểu dữ liệu" bất kì, ví dụ, một `int` hoặc một `str`.
-
-Trong Python 3.6 hoặc lớn hơn (bao gồm Python 3.10) bạn có thể sử dụng kiểu `Union` từ `typing` và đặt trong dấu ngoặc vuông những giá trị được chấp nhận.
-
-In Python 3.10 there's also a **new syntax** where you can put the possible types separated by a vertical bar (`|`).
-
-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 (`|`).
-
-
-//// 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!}
-```
-
-////
-
-Trong cả hai trường hợp có nghĩa là `item` có thể là một `int` hoặc `str`.
-
-#### Khả năng `None`
-
-Bạn có thể khai báo một giá trị có thể có một kiểu dữ liệu, giống như `str`, nhưng nó cũng có thể là `None`.
-
-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!}
-```
-
-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`.
-
-`Optional[Something]` là một cách viết ngắn gọn của `Union[Something, None]`, chúng là tương đương nhau.
-
-Điều này cũng có nghĩa là trong Python 3.10, bạn có thể sử dụng `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!}
-```
-
-////
-
-#### Sử dụng `Union` hay `Optional`
-
-If you are using a Python version below 3.10, here's a tip from my very **subjective** point of view:
-
-Nếu bạn đang sử dụng phiên bản Python dưới 3.10, đây là một mẹo từ ý kiến rất "chủ quan" của tôi:
-
-* 🚨 Tránh sử dụng `Optional[SomeType]`
-* Thay vào đó ✨ **sử dụng `Union[SomeType, None]`** ✨.
-
-Cả hai là tương đương và bên dưới chúng giống nhau, nhưng tôi sẽ đễ xuất `Union` thay cho `Optional` vì từ "**tùy chọn**" có vẻ ngầm định giá trị là tùy chọn, và nó thực sự có nghĩa rằng "nó có thể là `None`", do đó nó không phải là tùy chọn và nó vẫn được yêu cầu.
-
-Tôi nghĩ `Union[SomeType, None]` là rõ ràng hơn về ý nghĩa của nó.
-
-Nó chỉ là về các từ và tên. Nhưng những từ đó có thể ảnh hưởng cách bạn và những đồng đội của bạn suy nghĩ về code.
-
-Cho một ví dụ, hãy để ý hàm này:
-
-{* ../../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ố:
-
-```Python
-say_hi() # Oh, no, this throws an error! 😱
-```
-
-Tham số `name` **vẫn được yêu cầu** (không phải là *tùy chọn*) vì nó không có giá trị mặc định. Trong khi đó, `name` chấp nhận `None` như là giá trị:
-
-```Python
-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:
-
-{* ../../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`. 😎
-
-
-#### Những kiểu dữ liệu tổng quát
-
-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ụ:
-
-//// 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):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-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.
-
-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.
-
-////
-
-//// tab | 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):
-
-* `list`
-* `tuple`
-* `set`
-* `dict`
-
-Và tương tự với Python 3.6, từ mô đun `typing`:
-
-* `Union`
-* `Optional`
-* ...and others.
-
-////
-
-//// 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
-
-Bạn cũng có thể khai báo một lớp như là kiểu dữ liệu của một biến.
-
-Hãy nói rằng bạn muốn có một lớp `Person` với một tên:
-
-{* ../../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`:
-
-{* ../../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:
-
-
-
-Lưu ý rằng, điều này có nghĩa rằng "`one_person`" là một **thực thể** của lớp `Person`.
-
-Nó không có nghĩa "`one_person`" là một **lớp** gọi là `Person`.
-
-## Pydantic models
-
-Pydantic là một thư viện Python để validate dữ liệu hiệu năng cao.
-
-Bạn có thể khai báo "hình dạng" của dữa liệu như là các lớp với các thuộc tính.
-
-Và mỗi thuộc tính có một kiểu dữ liệu.
-
-Sau đó bạn tạo một thực thể của lớp đó với một vài giá trị và nó sẽ validate các giá trị, chuyển đổi chúng sang kiểu dữ liệu phù hợp (nếu đó là trường hợp) và cho bạn một object với toàn bộ dữ liệu.
-
-Và bạn nhận được tất cả sự hỗ trợ của trình soạn thảo với object kết quả đó.
-
-Một ví dụ từ tài liệu chính thức của Pydantic:
-
-//// 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
-
-Để 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.
-
-///
-
-## 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`.
-
-//// 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`.
-
-```Python hl_lines="1 4"
-{!> ../../docs_src/python_types/tutorial013_py39.py!}
-```
-
-////
-
-//// tab | Python 3.8+
-
-Ở phiên bản dưới Python 3.9, bạn import `Annotated` từ `typing_extensions`.
-
-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`.
-
-Nhưng bạn có thể sử dụng `Annotated` để cung cấp cho **FastAPI** metadata bổ sung về cách mà bạn muốn ứng dụng của bạn xử lí.
-
-Điều quan trọng cần nhớ là ***tham số kiểu dữ liệu* đầu tiên** bạn truyền tới `Annotated` là **kiểu giá trị thực sự**. Phần còn lại chỉ là metadata cho các công cụ khác.
-
-Bây giờ, bạn chỉ cần biết rằng `Annotated` tồn tại, và nó là tiêu chuẩn của Python. 😎
-
-
-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. ✨
-
-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**
-
-**FastAPI** lấy các ưu điểm của các gợi ý kiểu dữ liệu để thực hiện một số thứ.
-
-Với **FastAPI**, bạn khai báo các tham số với gợi ý kiểu và bạn có được:
-
-* **Sự hỗ trợ từ các trình soạn thảo**.
-* **Kiểm tra kiểu dữ liệu (type checking)**.
-
-...và **FastAPI** sử dụng các khia báo để:
-
-* **Định nghĩa các yêu cầu**: từ tham số đường dẫn của request, tham số query, headers, bodies, các phụ thuộc (dependencies),...
-* **Chuyển dổi dữ liệu*: từ request sang kiểu dữ liệu được yêu cầu.
-* **Kiểm tra tính đúng đắn của dữ liệu**: tới từ mỗi request:
- * Sinh **lỗi tự động** để trả về máy khác khi dữ liệu không hợp lệ.
-* **Tài liệu hóa** API sử dụng OpenAPI:
- * cái mà sau được được sử dụng bởi tài liệu tương tác người dùng.
-
-Điều này có thể nghe trừu tượng. Đừng lo lắng. Bạn sẽ thấy tất cả chúng trong [Hướng dẫn sử dụng](tutorial/index.md){.internal-link target=_blank}.
-
-Đ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`.
-
-///
diff --git a/docs/vi/docs/tutorial/first-steps.md b/docs/vi/docs/tutorial/first-steps.md
deleted file mode 100644
index 901c8fd59..000000000
--- a/docs/vi/docs/tutorial/first-steps.md
+++ /dev/null
@@ -1,335 +0,0 @@
-# Những bước đầu tiên
-
-Tệp tin FastAPI đơn giản nhất có thể trông như này:
-
-{* ../../docs_src/first_steps/tutorial001.py *}
-
-Sao chép sang một tệp tin `main.py`.
-
-Chạy live server:
-
-get
-
-/// info | Thông tin về "`@decorator`"
-
-Cú pháp `@something` trong Python được gọi là một "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).
-
-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ó.
-
-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:
-
-* `@app.post()`
-* `@app.put()`
-* `@app.delete()`
-
-Và nhiều hơn với các toán tử còn lại:
-
-* `@app.options()`
-* `@app.head()`
-* `@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.
-
-**FastAPI** không bắt buộc bất kì ý nghĩa cụ thể nào.
-
-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ử**
-
-Đây là "**hàm cho đường dẫn toán tử**":
-
-* **đường dẫn**: là `/`.
-* **toán tử**: là `get`.
-* **hàm**: là hàm bên dưới "decorator" (bên dưới `@app.get("/")`).
-
-{* ../../docs_src/first_steps/tutorial001.py hl[7] *}
-
-Đây là một hàm Python.
-
-Nó sẽ được gọi bởi **FastAPI** bất cứ khi nào nó nhận một request tới URL "`/`" sử dụng một toán tử `GET`.
-
-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`:
-
-{* ../../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}.
-
-///
-
-### Bước 5: Nội dung trả về
-
-{* ../../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`,...
-
-Bạn cũng có thể trả về Pydantic model (bạn sẽ thấy nhiều hơn về nó sau).
-
-Có nhiều object và model khác nhau sẽ được tự động chuyển đổi sang JSON (bao gồm cả ORM,...). Thử sử dụng loại ưa thích của bạn, nó có khả năng cao đã được hỗ trợ.
-
-## Tóm lại
-
-* Import `FastAPI`.
-* Tạo một `app` instance.
-* Viết một **decorator cho đường dẫn toán tử** (giống như `@app.get("/")`).
-* Viết một **hàm cho đường dẫn toán tử** (giống như `def root(): ...` ở trên).
-* Chạy server trong môi trường phát triển (giống như `uvicorn main:app --reload`).
diff --git a/docs/vi/docs/tutorial/index.md b/docs/vi/docs/tutorial/index.md
deleted file mode 100644
index dfeeed8c5..000000000
--- a/docs/vi/docs/tutorial/index.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Hướng dẫn sử dụng
-
-Hướng dẫn này cho bạn thấy từng bước cách sử dụng **FastAPI** đa số các tính năng của nó.
-
-Mỗi phần được xây dựng từ những phần trước đó, nhưng nó được cấu trúc thành các chủ đề riêng biệt, do đó bạn có thể xem trực tiếp từng phần cụ thể bất kì để giải quyết những API cụ thể mà bạn cần.
-
-Nó cũng được xây dựng để làm việc như một tham chiếu trong tương lai.
-
-Do đó bạn có thể quay lại và tìm chính xác những gì bạn cần.
-
-## Chạy mã
-
-Tất cả các code block có thể được sao chép và sử dụng trực tiếp (chúng thực chất là các tệp tin Python đã được kiểm thử).
-
-Để chạy bất kì ví dụ nào, sao chép code tới tệp tin `main.py`, và bắt đầu `uvicorn` với:
-
-
-
-
- Ìlànà wẹ́ẹ́bù FastAPI, iṣẹ́ gíga, ó rọrùn láti kọ̀, o yára láti kóòdù, ó sì ṣetán fún iṣelọpọ ní lílo -
- - ---- - -**Àkọsílẹ̀**: https://fastapi.tiangolo.com - -**Orisun Kóòdù**: https://github.com/fastapi/fastapi - ---- - -FastAPI jẹ́ ìgbàlódé, tí ó yára (iṣẹ-giga), ìlànà wẹ́ẹ́bù fún kikọ àwọn API pẹ̀lú Python èyí tí ó da lori àwọn ìtọ́kasí àmì irúfẹ́ Python. - -Àwọn ẹya pàtàkì ni: - -* **Ó yára**: Iṣẹ tí ó ga púpọ̀, tí ó wa ni ibamu pẹ̀lú **NodeJS** àti **Go** (ọpẹ si Starlette àti Pydantic). [Ọkan nínú àwọn ìlànà Python ti o yára jùlọ ti o wa](#isesi). -* **Ó yára láti kóòdù**: O mu iyara pọ si láti kọ àwọn ẹya tuntun kóòdù nipasẹ "Igba ìdá ọgọ́rùn-ún" (i.e. 200%) si "ọ̀ọ́dúrún ìdá ọgọ́rùn-ún" (i.e. 300%). -* **Àìtọ́ kékeré**: O n din aṣiṣe ku bi ọgbon ìdá ọgọ́rùn-ún (i.e. 40%) ti eda eniyan (oṣiṣẹ kóòdù) fa. * -* **Ọgbọ́n àti ìmọ̀**: Atilẹyin olootu nla. Ìparí nibi gbogbo. Àkókò díẹ̀ nipa wíwá ibi tí ìṣòro kóòdù wà. -* **Irọrun**: A kọ kí ó le rọrun láti lo àti láti kọ ẹkọ nínú rè. Ó máa fún ọ ní àkókò díẹ̀ látı ka àkọsílẹ. -* **Ó kúkurú ní kikọ**: Ó dín àtúnkọ àti àtúntò kóòdù kù. Ìkéde àṣàyàn kọ̀ọ̀kan nínú rẹ̀ ní ọ̀pọ̀lọpọ̀ àwọn ìlò. O ṣe iranlọwọ láti má ṣe ní ọ̀pọ̀lọpọ̀ àṣìṣe. -* **Ó lágbára**: Ó ń ṣe àgbéjáde kóòdù tí ó ṣetán fún ìṣelọ́pọ̀. Pẹ̀lú àkọsílẹ̀ tí ó máa ṣàlàyé ara rẹ̀ fún ẹ ní ìbáṣepọ̀ aládàáṣiṣẹ́ pẹ̀lú rè. -* **Ajohunše/Ìtọ́kasí**: Ó da lori (àti ibamu ni kikun pẹ̀lú) àwọn ìmọ ajohunše/ìtọ́kasí fún àwọn API: OpenAPI (èyí tí a mọ tẹlẹ si Swagger) àti JSON Schema. - -* iṣiro yi da lori àwọn idanwo tí ẹgbẹ ìdàgbàsókè FastAPI ṣe, nígbàtí wọn kọ àwọn ohun elo iṣelọpọ kóòdù pẹ̀lú rẹ. - -## Àwọn onígbọ̀wọ́ - - - -{% if sponsors %} -{% for sponsor in sponsors.gold -%} -
-
-Ti o ba n kọ ohun èlò CLI láti ṣeé lọ nínú ohun èlò lori ebute kọmputa dipo API, ṣayẹwo **Typer**.
-
-**Typer** jẹ́ àbúrò ìyá FastAPI kékeré. Àti pé wọ́n kọ́ láti jẹ́ **FastAPI ti CLIs**. ⌨️ 🚀
-
-## Èròjà
-
-FastAPI dúró lórí àwọn èjìká tí àwọn òmíràn:
-
-* Starlette fún àwọn ẹ̀yà ayélujára.
-* Pydantic fún àwọn ẹ̀yà àkójọf'áyẹ̀wò.
-
-## Fifi sórí ẹrọ
-
-async def...uvicorn main:app --reload...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.
-
-Èyí tí Starlette ń lò:
-
-* httpx - Nílò tí ó bá fẹ́ láti lọ `TestClient`.
-* jinja2 - Nílò tí ó bá fẹ́ láti lọ iṣeto awoṣe aiyipada.
-* python-multipart - Nílò tí ó bá fẹ́ láti ṣe àtìlẹ́yìn fún "àyẹ̀wò" fọọmu, pẹ̀lú `request.form()`.
-* itsdangerous - Nílò fún àtìlẹ́yìn `SessionMiddleware`.
-* pyyaml - Nílò fún àtìlẹ́yìn Starlette's `SchemaGenerator` (ó ṣe ṣe kí ó má nílò rẹ̀ fún FastAPI).
-
-Èyí tí FastAPI / Starlette ń lò:
-
-* uvicorn - Fún olupin tí yóò sẹ́ àmúyẹ àti tí yóò ṣe ìpèsè fún iṣẹ́ rẹ tàbí ohun èlò rẹ.
-* orjson - Nílò tí ó bá fẹ́ láti lọ `ORJSONResponse`.
-* ujson - Nílò tí ó bá fẹ́ láti lọ `UJSONResponse`.
-
-Ó lè fi gbogbo àwọn wọ̀nyí sórí ẹrọ pẹ̀lú `pip install "fastapi[all]"`.
-
-## Iwe-aṣẹ
-
-Iṣẹ́ yìí ni iwe-aṣẹ lábẹ́ àwọn òfin tí iwe-aṣẹ MIT.
diff --git a/docs/yo/mkdocs.yml b/docs/yo/mkdocs.yml
deleted file mode 100644
index de18856f4..000000000
--- a/docs/yo/mkdocs.yml
+++ /dev/null
@@ -1 +0,0 @@
-INHERIT: ../en/mkdocs.yml
diff --git a/docs/zh-hant/docs/fastapi-cli.md b/docs/zh-hant/docs/fastapi-cli.md
index 3c644ce46..b107e7e73 100644
--- a/docs/zh-hant/docs/fastapi-cli.md
+++ b/docs/zh-hant/docs/fastapi-cli.md
@@ -60,7 +60,7 @@ FastAPI CLI 接收你的 Python 程式路徑（例如 `main.py`），並自動
在生產環境，你應該使用 `fastapi run` 命令。 🚀
-**FastAPI CLI** 內部使用了 Uvicorn，這是一個高效能、適合生產環境的 ASGI 伺服器。 😎
+**FastAPI CLI** 內部使用了 Uvicorn，這是一個高效能、適合生產環境的 ASGI 伺服器。 😎
## `fastapi dev`
diff --git a/docs/zh-hant/docs/features.md b/docs/zh-hant/docs/features.md
index 3a1392b51..f44d28a7f 100644
--- a/docs/zh-hant/docs/features.md
+++ b/docs/zh-hant/docs/features.md
@@ -167,7 +167,7 @@ FastAPI 有一個使用簡單，但是非常強大的`dataclasses`）：
-{* ../../docs_src/dataclasses/tutorial001.py hl[1,7:12,19:20] *}
+{* ../../docs_src/dataclasses_/tutorial001.py hl[1,7:12,19:20] *}
这还是借助于 **Pydantic** 及其内置的 `dataclasses`。
@@ -32,7 +32,7 @@ FastAPI 基于 **Pydantic** 构建，前文已经介绍过如何使用 Pydantic
在 `response_model` 参数中使用 `dataclasses`：
-{* ../../docs_src/dataclasses/tutorial002.py hl[1,7:13,19] *}
+{* ../../docs_src/dataclasses_/tutorial002.py hl[1,7:13,19] *}
本例把数据类自动转换为 Pydantic 数据类。
@@ -49,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 5ade0f0ff..1ef6cdd3c 100644
--- a/docs/zh/docs/advanced/events.md
+++ b/docs/zh/docs/advanced/events.md
@@ -162,7 +162,7 @@ async with lifespan(app):
/// info | 说明
-有关事件处理器的详情，请参阅 Starlette 官档 - 事件。
+有关事件处理器的详情，请参阅 Starlette 官档 - 事件。
包括如何处理生命周期状态，这可以用于程序的其他部分。
diff --git a/docs/zh/docs/advanced/middleware.md b/docs/zh/docs/advanced/middleware.md
index c7b15b929..65e8c183f 100644
--- a/docs/zh/docs/advanced/middleware.md
+++ b/docs/zh/docs/advanced/middleware.md
@@ -92,4 +92,4 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow")
* Uvicorn 的 `ProxyHeadersMiddleware`
* MessagePack
-其它可用中间件详见 Starlette 官档 - 中间件 及 ASGI Awesome 列表。
+其它可用中间件详见 Starlette 官档 - 中间件 及 ASGI Awesome 列表。
diff --git a/docs/zh/docs/advanced/response-cookies.md b/docs/zh/docs/advanced/response-cookies.md
index d4b93d003..d5f2fe6fc 100644
--- a/docs/zh/docs/advanced/response-cookies.md
+++ b/docs/zh/docs/advanced/response-cookies.md
@@ -46,4 +46,4 @@
///
-如果你想查看所有可用的参数和选项，可以参考 Starlette帮助文档
+如果你想查看所有可用的参数和选项，可以参考 Starlette帮助文档
diff --git a/docs/zh/docs/advanced/response-headers.md b/docs/zh/docs/advanced/response-headers.md
index fe2cb0da8..5c6a62e93 100644
--- a/docs/zh/docs/advanced/response-headers.md
+++ b/docs/zh/docs/advanced/response-headers.md
@@ -36,4 +36,4 @@
请注意，可以使用'X-'前缀添加自定义专有头部。
-但是，如果你有自定义头部，你希望浏览器中的客户端能够看到它们，你需要将它们添加到你的CORS配置中（在[CORS（跨源资源共享）](../tutorial/cors.md){.internal-link target=_blank}中阅读更多），使用在Starlette的CORS文档中记录的`expose_headers`参数。
+但是，如果你有自定义头部，你希望浏览器中的客户端能够看到它们，你需要将它们添加到你的CORS配置中（在[CORS（跨源资源共享）](../tutorial/cors.md){.internal-link target=_blank}中阅读更多），使用在Starlette的CORS文档中记录的`expose_headers`参数。
diff --git a/docs/zh/docs/advanced/templates.md b/docs/zh/docs/advanced/templates.md
index 8b7019ede..e627eed98 100644
--- a/docs/zh/docs/advanced/templates.md
+++ b/docs/zh/docs/advanced/templates.md
@@ -122,4 +122,4 @@ Item ID: 42
## 更多说明
-包括测试模板等更多详情，请参阅 Starlette 官方文档 - 模板。
+包括测试模板等更多详情，请参阅 Starlette 官方文档 - 模板。
diff --git a/docs/zh/docs/advanced/testing-websockets.md b/docs/zh/docs/advanced/testing-websockets.md
index 5d713d5f7..b84647a3e 100644
--- a/docs/zh/docs/advanced/testing-websockets.md
+++ b/docs/zh/docs/advanced/testing-websockets.md
@@ -8,6 +8,6 @@
/// note | 笔记
-更多细节详见 Starlette 官档 - 测试 WebSockets。
+更多细节详见 Starlette 官档 - 测试 WebSockets。
///
diff --git a/docs/zh/docs/advanced/using-request-directly.md b/docs/zh/docs/advanced/using-request-directly.md
index db0fcafdf..a9658c034 100644
--- a/docs/zh/docs/advanced/using-request-directly.md
+++ b/docs/zh/docs/advanced/using-request-directly.md
@@ -15,7 +15,7 @@
## `Request` 对象的细节
-实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 `Request` 对象。
+实际上，**FastAPI** 的底层是 **Starlette**，**FastAPI** 只不过是在 **Starlette** 顶层提供了一些工具，所以能直接使用 Starlette 的 `Request` 对象。
但直接从 `Request` 对象提取数据时（例如，读取请求体），**FastAPI** 不会验证、转换和存档数据（为 API 文档使用 OpenAPI）。
@@ -45,7 +45,7 @@
## `Request` 文档
-更多细节详见 Starlette 官档 - `Request` 对象。
+更多细节详见 Starlette 官档 - `Request` 对象。
/// note | 技术细节
diff --git a/docs/zh/docs/advanced/websockets.md b/docs/zh/docs/advanced/websockets.md
index d91aacc03..005ed9242 100644
--- a/docs/zh/docs/advanced/websockets.md
+++ b/docs/zh/docs/advanced/websockets.md
@@ -172,5 +172,5 @@ Client #1596980209979 left the chat
要了解更多选项，请查看 Starlette 的文档：
-* [WebSocket 类](https://www.starlette.io/websockets/)
-* [基于类的 WebSocket 处理](https://www.starlette.io/endpoints/#websocketendpoint)。
+* [WebSocket 类](https://www.starlette.dev/websockets/)
+* [基于类的 WebSocket 处理](https://www.starlette.dev/endpoints/#websocketendpoint)。
diff --git a/docs/zh/docs/deployment/manually.md b/docs/zh/docs/deployment/manually.md
index 3dc5942e3..2c2784a64 100644
--- a/docs/zh/docs/deployment/manually.md
+++ b/docs/zh/docs/deployment/manually.md
@@ -52,7 +52,7 @@ FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称
除此之外，还有其他一些可选的 ASGI 服务器，例如：
-* Uvicorn：高性能 ASGI 服务器。
+* Uvicorn：高性能 ASGI 服务器。
* Hypercorn：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
* Daphne：为 Django Channels 构建的 ASGI 服务器。
* Granian：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
diff --git a/docs/zh/docs/fastapi-cli.md b/docs/zh/docs/fastapi-cli.md
index 8a70e1d80..3b67eb664 100644
--- a/docs/zh/docs/fastapi-cli.md
+++ b/docs/zh/docs/fastapi-cli.md
@@ -52,7 +52,7 @@ FastAPI CLI 接收你的 Python 程序路径，自动检测包含 FastAPI 的变
在生产环境中，你应该使用 `fastapi run` 命令。🚀
-在内部，**FastAPI CLI** 使用了 Uvicorn，这是一个高性能、适用于生产环境的 ASGI 服务器。😎
+在内部，**FastAPI CLI** 使用了 Uvicorn，这是一个高性能、适用于生产环境的 ASGI 服务器。😎
## `fastapi dev`
diff --git a/docs/zh/docs/features.md b/docs/zh/docs/features.md
index 24dc3e8ce..eaf8daff7 100644
--- a/docs/zh/docs/features.md
+++ b/docs/zh/docs/features.md
@@ -165,7 +165,7 @@ FastAPI 有一个使用非常简单，但是非常强大的.
+更多细节查看 Starlette's official docs for Background Tasks.
## 告诫
diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md
index 80a34116a..2d7c35c8c 100644
--- a/docs/zh/docs/tutorial/first-steps.md
+++ b/docs/zh/docs/tutorial/first-steps.md
@@ -155,7 +155,7 @@ OpenAPI 为你的 API 定义 API 模式。该模式中包含了你的 API 发送
`FastAPI` 是直接从 `Starlette` 继承的类。
-你可以通过 `FastAPI` 使用所有的 Starlette 的功能。
+你可以通过 `FastAPI` 使用所有的 Starlette 的功能。
///
diff --git a/docs/zh/docs/tutorial/handling-errors.md b/docs/zh/docs/tutorial/handling-errors.md
index 0b887c292..ae667b74a 100644
--- a/docs/zh/docs/tutorial/handling-errors.md
+++ b/docs/zh/docs/tutorial/handling-errors.md
@@ -83,7 +83,7 @@
## 安装自定义异常处理器
-添加自定义处理器，要使用 [Starlette 的异常工具](https://www.starlette.io/exceptions/)。
+添加自定义处理器，要使用 [Starlette 的异常工具](https://www.starlette.dev/exceptions/)。
假设要触发的自定义异常叫作 `UnicornException`。
diff --git a/docs/zh/docs/tutorial/middleware.md b/docs/zh/docs/tutorial/middleware.md
index 258ca7482..5608c4ee1 100644
--- a/docs/zh/docs/tutorial/middleware.md
+++ b/docs/zh/docs/tutorial/middleware.md
@@ -37,7 +37,7 @@
请记住可以 用'X-' 前缀添加专有自定义请求头.
-但是如果你想让浏览器中的客户端看到你的自定义请求头, 你需要把它们加到 CORS 配置 ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) 的 `expose_headers` 参数中,在 Starlette's CORS docs文档中.
+但是如果你想让浏览器中的客户端看到你的自定义请求头, 你需要把它们加到 CORS 配置 ([CORS (Cross-Origin Resource Sharing)](cors.md){.internal-link target=_blank}) 的 `expose_headers` 参数中,在 Starlette's CORS docs文档中.
///
diff --git a/docs/zh/docs/tutorial/static-files.md b/docs/zh/docs/tutorial/static-files.md
index c19079565..1a0d4504c 100644
--- a/docs/zh/docs/tutorial/static-files.md
+++ b/docs/zh/docs/tutorial/static-files.md
@@ -37,4 +37,4 @@
## 更多信息
-更多细节和选择查阅 Starlette's docs about Static Files.
+更多细节和选择查阅 Starlette's docs about Static Files.
diff --git a/docs/zh/docs/tutorial/testing.md b/docs/zh/docs/tutorial/testing.md
index 3e0c48caf..3877adbac 100644
--- a/docs/zh/docs/tutorial/testing.md
+++ b/docs/zh/docs/tutorial/testing.md
@@ -1,6 +1,6 @@
# 测试
-感谢 Starlette，测试**FastAPI** 应用轻松又愉快。
+感谢 Starlette，测试**FastAPI** 应用轻松又愉快。
它基于 HTTPX， 而HTTPX又是基于Requests设计的，所以很相似且易懂。
diff --git a/docs/zh/llm-prompt.md b/docs/zh/llm-prompt.md
new file mode 100644
index 000000000..7ce6f96a4
--- /dev/null
+++ b/docs/zh/llm-prompt.md
@@ -0,0 +1,46 @@
+### Target language
+
+Translate to Simplified Chinese (简体中文).
+
+Language code: zh.
+
+### Grammar and tone
+
+- Use clear, concise technical Chinese consistent with existing docs.
+- Address the reader naturally (commonly using “你/你的”).
+
+### Headings
+
+- Follow existing Simplified Chinese heading style (short and descriptive).
+- Do not add trailing punctuation to headings.
+- If a heading contains only the name of a FastAPI feature, do not translate it.
+
+### Quotes and punctuation
+
+- Keep punctuation style consistent with existing Simplified Chinese docs (they often mix English terms like “FastAPI” with Chinese text).
+- Never change punctuation inside inline code, code blocks, URLs, or file paths.
+
+### Ellipsis
+
+- Keep ellipsis style consistent within each document, prefer `...` over `……`.
+- Never change ellipsis in code, URLs, or CLI examples.
+
+### Preferred translations / glossary
+
+Use the following preferred translations when they apply in documentation prose:
+
+- request (HTTP): 请求
+- response (HTTP): 响应
+- path operation: 路径操作
+- path operation function: 路径操作函数
+
+### `///` admonitions
+
+- Keep the admonition keyword in English (do not translate `note`, `tip`, etc.).
+- If a title is present, prefer these canonical titles:
+
+- `/// tip | 提示`
+- `/// note | 注意`
+- `/// warning | 警告`
+- `/// info | 信息`
+- `/// danger | 危险`
diff --git a/docs_src/app_testing/app_b/__init__.py b/docs_src/additional_responses/__init__.py
similarity index 100%
rename from docs_src/app_testing/app_b/__init__.py
rename to docs_src/additional_responses/__init__.py
diff --git a/docs_src/additional_responses/tutorial001.py b/docs_src/additional_responses/tutorial001_py39.py
similarity index 100%
rename from docs_src/additional_responses/tutorial001.py
rename to docs_src/additional_responses/tutorial001_py39.py
diff --git a/docs_src/additional_responses/tutorial002_py310.py b/docs_src/additional_responses/tutorial002_py310.py
new file mode 100644
index 000000000..a94b740c9
--- /dev/null
+++ b/docs_src/additional_responses/tutorial002_py310.py
@@ -0,0 +1,28 @@
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ id: str
+ value: str
+
+
+app = FastAPI()
+
+
+@app.get(
+ "/items/{item_id}",
+ response_model=Item,
+ responses={
+ 200: {
+ "content": {"image/png": {}},
+ "description": "Return the JSON item or an image.",
+ }
+ },
+)
+async def read_item(item_id: str, img: bool | None = None):
+ if img:
+ return FileResponse("image.png", media_type="image/png")
+ else:
+ return {"id": "foo", "value": "there goes my hero"}
diff --git a/docs_src/additional_responses/tutorial002.py b/docs_src/additional_responses/tutorial002_py39.py
similarity index 100%
rename from docs_src/additional_responses/tutorial002.py
rename to docs_src/additional_responses/tutorial002_py39.py
diff --git a/docs_src/additional_responses/tutorial003.py b/docs_src/additional_responses/tutorial003_py39.py
similarity index 100%
rename from docs_src/additional_responses/tutorial003.py
rename to docs_src/additional_responses/tutorial003_py39.py
diff --git a/docs_src/additional_responses/tutorial004_py310.py b/docs_src/additional_responses/tutorial004_py310.py
new file mode 100644
index 000000000..65cbef634
--- /dev/null
+++ b/docs_src/additional_responses/tutorial004_py310.py
@@ -0,0 +1,30 @@
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ id: str
+ value: str
+
+
+responses = {
+ 404: {"description": "Item not found"},
+ 302: {"description": "The item was moved"},
+ 403: {"description": "Not enough privileges"},
+}
+
+
+app = FastAPI()
+
+
+@app.get(
+ "/items/{item_id}",
+ response_model=Item,
+ responses={**responses, 200: {"content": {"image/png": {}}}},
+)
+async def read_item(item_id: str, img: bool | None = None):
+ if img:
+ return FileResponse("image.png", media_type="image/png")
+ else:
+ return {"id": "foo", "value": "there goes my hero"}
diff --git a/docs_src/additional_responses/tutorial004.py b/docs_src/additional_responses/tutorial004_py39.py
similarity index 100%
rename from docs_src/additional_responses/tutorial004.py
rename to docs_src/additional_responses/tutorial004_py39.py
diff --git a/docs_src/app_testing/app_b_an/__init__.py b/docs_src/additional_status_codes/__init__.py
similarity index 100%
rename from docs_src/app_testing/app_b_an/__init__.py
rename to docs_src/additional_status_codes/__init__.py
diff --git a/docs_src/additional_status_codes/tutorial001_an.py b/docs_src/additional_status_codes/tutorial001_an.py
deleted file mode 100644
index b5ad6a16b..000000000
--- a/docs_src/additional_status_codes/tutorial001_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI, status
-from fastapi.responses import JSONResponse
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}
-
-
-@app.put("/items/{item_id}")
-async def upsert_item(
- item_id: str,
- name: Annotated[Union[str, None], Body()] = None,
- size: Annotated[Union[int, None], Body()] = None,
-):
- if item_id in items:
- item = items[item_id]
- item["name"] = name
- item["size"] = size
- return item
- else:
- item = {"name": name, "size": size}
- items[item_id] = item
- return JSONResponse(status_code=status.HTTP_201_CREATED, content=item)
diff --git a/docs_src/additional_status_codes/tutorial001.py b/docs_src/additional_status_codes/tutorial001_py39.py
similarity index 100%
rename from docs_src/additional_status_codes/tutorial001.py
rename to docs_src/additional_status_codes/tutorial001_py39.py
diff --git a/docs_src/bigger_applications/app/__init__.py b/docs_src/advanced_middleware/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app/__init__.py
rename to docs_src/advanced_middleware/__init__.py
diff --git a/docs_src/advanced_middleware/tutorial001.py b/docs_src/advanced_middleware/tutorial001_py39.py
similarity index 100%
rename from docs_src/advanced_middleware/tutorial001.py
rename to docs_src/advanced_middleware/tutorial001_py39.py
diff --git a/docs_src/advanced_middleware/tutorial002.py b/docs_src/advanced_middleware/tutorial002_py39.py
similarity index 100%
rename from docs_src/advanced_middleware/tutorial002.py
rename to docs_src/advanced_middleware/tutorial002_py39.py
diff --git a/docs_src/advanced_middleware/tutorial003.py b/docs_src/advanced_middleware/tutorial003_py39.py
similarity index 100%
rename from docs_src/advanced_middleware/tutorial003.py
rename to docs_src/advanced_middleware/tutorial003_py39.py
diff --git a/docs_src/bigger_applications/app/internal/__init__.py b/docs_src/app_testing/app_a_py39/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app/internal/__init__.py
rename to docs_src/app_testing/app_a_py39/__init__.py
diff --git a/docs_src/app_testing/main.py b/docs_src/app_testing/app_a_py39/main.py
similarity index 100%
rename from docs_src/app_testing/main.py
rename to docs_src/app_testing/app_a_py39/main.py
diff --git a/docs_src/app_testing/test_main.py b/docs_src/app_testing/app_a_py39/test_main.py
similarity index 100%
rename from docs_src/app_testing/test_main.py
rename to docs_src/app_testing/app_a_py39/test_main.py
diff --git a/docs_src/app_testing/app_b_an/main.py b/docs_src/app_testing/app_b_an/main.py
deleted file mode 100644
index c66278fdd..000000000
--- a/docs_src/app_testing/app_b_an/main.py
+++ /dev/null
@@ -1,39 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Header, HTTPException
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-fake_secret_token = "coneofsilence"
-
-fake_db = {
- "foo": {"id": "foo", "title": "Foo", "description": "There goes my hero"},
- "bar": {"id": "bar", "title": "Bar", "description": "The bartenders"},
-}
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- id: str
- title: str
- description: Union[str, None] = None
-
-
-@app.get("/items/{item_id}", response_model=Item)
-async def read_main(item_id: str, x_token: Annotated[str, Header()]):
- if x_token != fake_secret_token:
- raise HTTPException(status_code=400, detail="Invalid X-Token header")
- if item_id not in fake_db:
- raise HTTPException(status_code=404, detail="Item not found")
- return fake_db[item_id]
-
-
-@app.post("/items/", response_model=Item)
-async def create_item(item: Item, x_token: Annotated[str, Header()]):
- if x_token != fake_secret_token:
- raise HTTPException(status_code=400, detail="Invalid X-Token header")
- if item.id in fake_db:
- raise HTTPException(status_code=409, detail="Item already exists")
- fake_db[item.id] = item
- return item
diff --git a/docs_src/app_testing/app_b_an/test_main.py b/docs_src/app_testing/app_b_an/test_main.py
deleted file mode 100644
index 4e1c51ecc..000000000
--- a/docs_src/app_testing/app_b_an/test_main.py
+++ /dev/null
@@ -1,65 +0,0 @@
-from fastapi.testclient import TestClient
-
-from .main import app
-
-client = TestClient(app)
-
-
-def test_read_item():
- response = client.get("/items/foo", headers={"X-Token": "coneofsilence"})
- assert response.status_code == 200
- assert response.json() == {
- "id": "foo",
- "title": "Foo",
- "description": "There goes my hero",
- }
-
-
-def test_read_item_bad_token():
- response = client.get("/items/foo", headers={"X-Token": "hailhydra"})
- assert response.status_code == 400
- assert response.json() == {"detail": "Invalid X-Token header"}
-
-
-def test_read_nonexistent_item():
- response = client.get("/items/baz", headers={"X-Token": "coneofsilence"})
- assert response.status_code == 404
- assert response.json() == {"detail": "Item not found"}
-
-
-def test_create_item():
- response = client.post(
- "/items/",
- headers={"X-Token": "coneofsilence"},
- json={"id": "foobar", "title": "Foo Bar", "description": "The Foo Barters"},
- )
- assert response.status_code == 200
- assert response.json() == {
- "id": "foobar",
- "title": "Foo Bar",
- "description": "The Foo Barters",
- }
-
-
-def test_create_item_bad_token():
- response = client.post(
- "/items/",
- headers={"X-Token": "hailhydra"},
- json={"id": "bazz", "title": "Bazz", "description": "Drop the bazz"},
- )
- assert response.status_code == 400
- assert response.json() == {"detail": "Invalid X-Token header"}
-
-
-def test_create_existing_item():
- response = client.post(
- "/items/",
- headers={"X-Token": "coneofsilence"},
- json={
- "id": "foo",
- "title": "The Foo ID Stealers",
- "description": "There goes my stealer",
- },
- )
- assert response.status_code == 409
- assert response.json() == {"detail": "Item already exists"}
diff --git a/docs_src/bigger_applications/app/routers/__init__.py b/docs_src/app_testing/app_b_py39/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app/routers/__init__.py
rename to docs_src/app_testing/app_b_py39/__init__.py
diff --git a/docs_src/app_testing/app_b/main.py b/docs_src/app_testing/app_b_py39/main.py
similarity index 100%
rename from docs_src/app_testing/app_b/main.py
rename to docs_src/app_testing/app_b_py39/main.py
diff --git a/docs_src/app_testing/app_b/test_main.py b/docs_src/app_testing/app_b_py39/test_main.py
similarity index 100%
rename from docs_src/app_testing/app_b/test_main.py
rename to docs_src/app_testing/app_b_py39/test_main.py
diff --git a/docs_src/app_testing/tutorial001.py b/docs_src/app_testing/tutorial001_py39.py
similarity index 100%
rename from docs_src/app_testing/tutorial001.py
rename to docs_src/app_testing/tutorial001_py39.py
diff --git a/docs_src/app_testing/tutorial002.py b/docs_src/app_testing/tutorial002_py39.py
similarity index 100%
rename from docs_src/app_testing/tutorial002.py
rename to docs_src/app_testing/tutorial002_py39.py
diff --git a/docs_src/app_testing/tutorial003.py b/docs_src/app_testing/tutorial003_py39.py
similarity index 100%
rename from docs_src/app_testing/tutorial003.py
rename to docs_src/app_testing/tutorial003_py39.py
diff --git a/docs_src/app_testing/tutorial004.py b/docs_src/app_testing/tutorial004_py39.py
similarity index 100%
rename from docs_src/app_testing/tutorial004.py
rename to docs_src/app_testing/tutorial004_py39.py
diff --git a/docs_src/bigger_applications/app_an/__init__.py b/docs_src/async_tests/app_a_py39/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app_an/__init__.py
rename to docs_src/async_tests/app_a_py39/__init__.py
diff --git a/docs_src/async_tests/main.py b/docs_src/async_tests/app_a_py39/main.py
similarity index 100%
rename from docs_src/async_tests/main.py
rename to docs_src/async_tests/app_a_py39/main.py
diff --git a/docs_src/async_tests/test_main.py b/docs_src/async_tests/app_a_py39/test_main.py
similarity index 100%
rename from docs_src/async_tests/test_main.py
rename to docs_src/async_tests/app_a_py39/test_main.py
diff --git a/docs_src/bigger_applications/app_an/internal/__init__.py b/docs_src/authentication_error_status_code/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app_an/internal/__init__.py
rename to docs_src/authentication_error_status_code/__init__.py
diff --git a/docs_src/authentication_error_status_code/tutorial001_an_py39.py b/docs_src/authentication_error_status_code/tutorial001_an_py39.py
new file mode 100644
index 000000000..7bbc2f717
--- /dev/null
+++ b/docs_src/authentication_error_status_code/tutorial001_an_py39.py
@@ -0,0 +1,21 @@
+from typing import Annotated
+
+from fastapi import Depends, FastAPI, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+app = FastAPI()
+
+
+class HTTPBearer403(HTTPBearer):
+ def make_not_authenticated_error(self) -> HTTPException:
+ return HTTPException(
+ status_code=status.HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
+
+
+CredentialsDep = Annotated[HTTPAuthorizationCredentials, Depends(HTTPBearer403())]
+
+
+@app.get("/me")
+def read_me(credentials: CredentialsDep):
+ return {"message": "You are authenticated", "token": credentials.credentials}
diff --git a/docs_src/bigger_applications/app_an/routers/__init__.py b/docs_src/background_tasks/__init__.py
similarity index 100%
rename from docs_src/bigger_applications/app_an/routers/__init__.py
rename to docs_src/background_tasks/__init__.py
diff --git a/docs_src/background_tasks/tutorial001.py b/docs_src/background_tasks/tutorial001_py39.py
similarity index 100%
rename from docs_src/background_tasks/tutorial001.py
rename to docs_src/background_tasks/tutorial001_py39.py
diff --git a/docs_src/background_tasks/tutorial002_an.py b/docs_src/background_tasks/tutorial002_an.py
deleted file mode 100644
index f63502b09..000000000
--- a/docs_src/background_tasks/tutorial002_an.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from typing import Union
-
-from fastapi import BackgroundTasks, Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-def write_log(message: str):
- with open("log.txt", mode="a") as log:
- log.write(message)
-
-
-def get_query(background_tasks: BackgroundTasks, q: Union[str, None] = None):
- if q:
- message = f"found query: {q}\n"
- background_tasks.add_task(write_log, message)
- return q
-
-
-@app.post("/send-notification/{email}")
-async def send_notification(
- email: str, background_tasks: BackgroundTasks, q: Annotated[str, Depends(get_query)]
-):
- message = f"message to {email}\n"
- background_tasks.add_task(write_log, message)
- return {"message": "Message sent"}
diff --git a/docs_src/background_tasks/tutorial002.py b/docs_src/background_tasks/tutorial002_py39.py
similarity index 100%
rename from docs_src/background_tasks/tutorial002.py
rename to docs_src/background_tasks/tutorial002_py39.py
diff --git a/docs_src/settings/app01/__init__.py b/docs_src/behind_a_proxy/__init__.py
similarity index 100%
rename from docs_src/settings/app01/__init__.py
rename to docs_src/behind_a_proxy/__init__.py
diff --git a/docs_src/behind_a_proxy/tutorial001_01.py b/docs_src/behind_a_proxy/tutorial001_01_py39.py
similarity index 100%
rename from docs_src/behind_a_proxy/tutorial001_01.py
rename to docs_src/behind_a_proxy/tutorial001_01_py39.py
diff --git a/docs_src/behind_a_proxy/tutorial001.py b/docs_src/behind_a_proxy/tutorial001_py39.py
similarity index 100%
rename from docs_src/behind_a_proxy/tutorial001.py
rename to docs_src/behind_a_proxy/tutorial001_py39.py
diff --git a/docs_src/behind_a_proxy/tutorial002.py b/docs_src/behind_a_proxy/tutorial002_py39.py
similarity index 100%
rename from docs_src/behind_a_proxy/tutorial002.py
rename to docs_src/behind_a_proxy/tutorial002_py39.py
diff --git a/docs_src/behind_a_proxy/tutorial003.py b/docs_src/behind_a_proxy/tutorial003_py39.py
similarity index 100%
rename from docs_src/behind_a_proxy/tutorial003.py
rename to docs_src/behind_a_proxy/tutorial003_py39.py
diff --git a/docs_src/behind_a_proxy/tutorial004.py b/docs_src/behind_a_proxy/tutorial004_py39.py
similarity index 100%
rename from docs_src/behind_a_proxy/tutorial004.py
rename to docs_src/behind_a_proxy/tutorial004_py39.py
diff --git a/docs_src/bigger_applications/app_an/dependencies.py b/docs_src/bigger_applications/app_an/dependencies.py
deleted file mode 100644
index 1374c54b3..000000000
--- a/docs_src/bigger_applications/app_an/dependencies.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from fastapi import Header, HTTPException
-from typing_extensions import Annotated
-
-
-async def get_token_header(x_token: Annotated[str, Header()]):
- if x_token != "fake-super-secret-token":
- raise HTTPException(status_code=400, detail="X-Token header invalid")
-
-
-async def get_query_token(token: str):
- if token != "jessica":
- raise HTTPException(status_code=400, detail="No Jessica token provided")
diff --git a/docs_src/bigger_applications/app_an/internal/admin.py b/docs_src/bigger_applications/app_an/internal/admin.py
deleted file mode 100644
index 99d3da86b..000000000
--- a/docs_src/bigger_applications/app_an/internal/admin.py
+++ /dev/null
@@ -1,8 +0,0 @@
-from fastapi import APIRouter
-
-router = APIRouter()
-
-
-@router.post("/")
-async def update_admin():
- return {"message": "Admin getting schwifty"}
diff --git a/docs_src/bigger_applications/app_an/main.py b/docs_src/bigger_applications/app_an/main.py
deleted file mode 100644
index ae544a3aa..000000000
--- a/docs_src/bigger_applications/app_an/main.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from fastapi import Depends, FastAPI
-
-from .dependencies import get_query_token, get_token_header
-from .internal import admin
-from .routers import items, users
-
-app = FastAPI(dependencies=[Depends(get_query_token)])
-
-
-app.include_router(users.router)
-app.include_router(items.router)
-app.include_router(
- admin.router,
- prefix="/admin",
- tags=["admin"],
- dependencies=[Depends(get_token_header)],
- responses={418: {"description": "I'm a teapot"}},
-)
-
-
-@app.get("/")
-async def root():
- return {"message": "Hello Bigger Applications!"}
diff --git a/docs_src/bigger_applications/app_an/routers/items.py b/docs_src/bigger_applications/app_an/routers/items.py
deleted file mode 100644
index bde9ff4d5..000000000
--- a/docs_src/bigger_applications/app_an/routers/items.py
+++ /dev/null
@@ -1,38 +0,0 @@
-from fastapi import APIRouter, Depends, HTTPException
-
-from ..dependencies import get_token_header
-
-router = APIRouter(
- prefix="/items",
- tags=["items"],
- dependencies=[Depends(get_token_header)],
- responses={404: {"description": "Not found"}},
-)
-
-
-fake_items_db = {"plumbus": {"name": "Plumbus"}, "gun": {"name": "Portal Gun"}}
-
-
-@router.get("/")
-async def read_items():
- return fake_items_db
-
-
-@router.get("/{item_id}")
-async def read_item(item_id: str):
- if item_id not in fake_items_db:
- raise HTTPException(status_code=404, detail="Item not found")
- return {"name": fake_items_db[item_id]["name"], "item_id": item_id}
-
-
-@router.put(
- "/{item_id}",
- tags=["custom"],
- responses={403: {"description": "Operation forbidden"}},
-)
-async def update_item(item_id: str):
- if item_id != "plumbus":
- raise HTTPException(
- status_code=403, detail="You can only update the item: plumbus"
- )
- return {"item_id": item_id, "name": "The great Plumbus"}
diff --git a/docs_src/bigger_applications/app_an/routers/users.py b/docs_src/bigger_applications/app_an/routers/users.py
deleted file mode 100644
index 39b3d7e7c..000000000
--- a/docs_src/bigger_applications/app_an/routers/users.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from fastapi import APIRouter
-
-router = APIRouter()
-
-
-@router.get("/users/", tags=["users"])
-async def read_users():
- return [{"username": "Rick"}, {"username": "Morty"}]
-
-
-@router.get("/users/me", tags=["users"])
-async def read_user_me():
- return {"username": "fakecurrentuser"}
-
-
-@router.get("/users/{username}", tags=["users"])
-async def read_user(username: str):
- return {"username": username}
diff --git a/docs_src/settings/app02/__init__.py b/docs_src/bigger_applications/app_py39/__init__.py
similarity index 100%
rename from docs_src/settings/app02/__init__.py
rename to docs_src/bigger_applications/app_py39/__init__.py
diff --git a/docs_src/bigger_applications/app/dependencies.py b/docs_src/bigger_applications/app_py39/dependencies.py
similarity index 100%
rename from docs_src/bigger_applications/app/dependencies.py
rename to docs_src/bigger_applications/app_py39/dependencies.py
diff --git a/docs_src/settings/app02_an/__init__.py b/docs_src/bigger_applications/app_py39/internal/__init__.py
similarity index 100%
rename from docs_src/settings/app02_an/__init__.py
rename to docs_src/bigger_applications/app_py39/internal/__init__.py
diff --git a/docs_src/bigger_applications/app/internal/admin.py b/docs_src/bigger_applications/app_py39/internal/admin.py
similarity index 100%
rename from docs_src/bigger_applications/app/internal/admin.py
rename to docs_src/bigger_applications/app_py39/internal/admin.py
diff --git a/docs_src/bigger_applications/app/main.py b/docs_src/bigger_applications/app_py39/main.py
similarity index 100%
rename from docs_src/bigger_applications/app/main.py
rename to docs_src/bigger_applications/app_py39/main.py
diff --git a/docs_src/settings/app03/__init__.py b/docs_src/bigger_applications/app_py39/routers/__init__.py
similarity index 100%
rename from docs_src/settings/app03/__init__.py
rename to docs_src/bigger_applications/app_py39/routers/__init__.py
diff --git a/docs_src/bigger_applications/app/routers/items.py b/docs_src/bigger_applications/app_py39/routers/items.py
similarity index 100%
rename from docs_src/bigger_applications/app/routers/items.py
rename to docs_src/bigger_applications/app_py39/routers/items.py
diff --git a/docs_src/bigger_applications/app/routers/users.py b/docs_src/bigger_applications/app_py39/routers/users.py
similarity index 100%
rename from docs_src/bigger_applications/app/routers/users.py
rename to docs_src/bigger_applications/app_py39/routers/users.py
diff --git a/docs_src/settings/app03_an/__init__.py b/docs_src/body/__init__.py
similarity index 100%
rename from docs_src/settings/app03_an/__init__.py
rename to docs_src/body/__init__.py
diff --git a/docs_src/body/tutorial001.py b/docs_src/body/tutorial001_py39.py
similarity index 100%
rename from docs_src/body/tutorial001.py
rename to docs_src/body/tutorial001_py39.py
diff --git a/docs_src/body/tutorial002.py b/docs_src/body/tutorial002.py
deleted file mode 100644
index 5cd86216b..000000000
--- a/docs_src/body/tutorial002.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-app = FastAPI()
-
-
-@app.post("/items/")
-async def create_item(item: Item):
- item_dict = item.dict()
- if item.tax is not None:
- price_with_tax = item.price + item.tax
- item_dict.update({"price_with_tax": price_with_tax})
- return item_dict
diff --git a/docs_src/body/tutorial002_py310.py b/docs_src/body/tutorial002_py310.py
index 454c45c88..a829a4dc9 100644
--- a/docs_src/body/tutorial002_py310.py
+++ b/docs_src/body/tutorial002_py310.py
@@ -14,7 +14,7 @@ app = FastAPI()
@app.post("/items/")
async def create_item(item: Item):
- item_dict = item.dict()
+ item_dict = item.model_dump()
if item.tax is not None:
price_with_tax = item.price + item.tax
item_dict.update({"price_with_tax": price_with_tax})
diff --git a/docs_src/body/tutorial002_py39.py b/docs_src/body/tutorial002_py39.py
new file mode 100644
index 000000000..fb212e8e7
--- /dev/null
+++ b/docs_src/body/tutorial002_py39.py
@@ -0,0 +1,23 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ price: float
+ tax: Union[float, None] = None
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Item):
+ item_dict = item.model_dump()
+ if item.tax is not None:
+ price_with_tax = item.price + item.tax
+ item_dict.update({"price_with_tax": price_with_tax})
+ return item_dict
diff --git a/docs_src/body/tutorial003.py b/docs_src/body/tutorial003.py
deleted file mode 100644
index 2f33cc038..000000000
--- a/docs_src/body/tutorial003.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-app = FastAPI()
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- return {"item_id": item_id, **item.dict()}
diff --git a/docs_src/body/tutorial003_py310.py b/docs_src/body/tutorial003_py310.py
index 440b210e6..51ac8aafa 100644
--- a/docs_src/body/tutorial003_py310.py
+++ b/docs_src/body/tutorial003_py310.py
@@ -14,4 +14,4 @@ app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
- return {"item_id": item_id, **item.dict()}
+ return {"item_id": item_id, **item.model_dump()}
diff --git a/docs_src/body/tutorial003_py39.py b/docs_src/body/tutorial003_py39.py
new file mode 100644
index 000000000..636ba2275
--- /dev/null
+++ b/docs_src/body/tutorial003_py39.py
@@ -0,0 +1,19 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ price: float
+ tax: Union[float, None] = None
+
+
+app = FastAPI()
+
+
+@app.put("/items/{item_id}")
+async def update_item(item_id: int, item: Item):
+ return {"item_id": item_id, **item.model_dump()}
diff --git a/docs_src/body/tutorial004.py b/docs_src/body/tutorial004.py
deleted file mode 100644
index 0671e0a27..000000000
--- a/docs_src/body/tutorial004.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-app = FastAPI()
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item, q: Union[str, None] = None):
- result = {"item_id": item_id, **item.dict()}
- if q:
- result.update({"q": q})
- return result
diff --git a/docs_src/body/tutorial004_py310.py b/docs_src/body/tutorial004_py310.py
index b352b70ab..53b10d97b 100644
--- a/docs_src/body/tutorial004_py310.py
+++ b/docs_src/body/tutorial004_py310.py
@@ -14,7 +14,7 @@ app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
- result = {"item_id": item_id, **item.dict()}
+ result = {"item_id": item_id, **item.model_dump()}
if q:
result.update({"q": q})
return result
diff --git a/docs_src/body/tutorial004_py39.py b/docs_src/body/tutorial004_py39.py
new file mode 100644
index 000000000..2c157abfa
--- /dev/null
+++ b/docs_src/body/tutorial004_py39.py
@@ -0,0 +1,22 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ price: float
+ tax: Union[float, None] = None
+
+
+app = FastAPI()
+
+
+@app.put("/items/{item_id}")
+async def update_item(item_id: int, item: Item, q: Union[str, None] = None):
+ result = {"item_id": item_id, **item.model_dump()}
+ if q:
+ result.update({"q": q})
+ return result
diff --git a/tests/test_filter_pydantic_sub_model/__init__.py b/docs_src/body_fields/__init__.py
similarity index 100%
rename from tests/test_filter_pydantic_sub_model/__init__.py
rename to docs_src/body_fields/__init__.py
diff --git a/docs_src/body_fields/tutorial001_an.py b/docs_src/body_fields/tutorial001_an.py
deleted file mode 100644
index 15ea1b53d..000000000
--- a/docs_src/body_fields/tutorial001_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = Field(
- default=None, title="The description of the item", max_length=300
- )
- price: float = Field(gt=0, description="The price must be greater than zero")
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_fields/tutorial001.py b/docs_src/body_fields/tutorial001_py39.py
similarity index 100%
rename from docs_src/body_fields/tutorial001.py
rename to docs_src/body_fields/tutorial001_py39.py
diff --git a/docs/en/mkdocs.no-insiders.yml b/docs_src/body_multiple_params/__init__.py
similarity index 100%
rename from docs/en/mkdocs.no-insiders.yml
rename to docs_src/body_multiple_params/__init__.py
diff --git a/docs_src/body_multiple_params/tutorial001_an.py b/docs_src/body_multiple_params/tutorial001_an.py
deleted file mode 100644
index 308eee854..000000000
--- a/docs_src/body_multiple_params/tutorial001_an.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Path
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
- q: Union[str, None] = None,
- item: Union[Item, None] = None,
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- if item:
- results.update({"item": item})
- return results
diff --git a/docs_src/body_multiple_params/tutorial001.py b/docs_src/body_multiple_params/tutorial001_py39.py
similarity index 100%
rename from docs_src/body_multiple_params/tutorial001.py
rename to docs_src/body_multiple_params/tutorial001_py39.py
diff --git a/docs_src/body_multiple_params/tutorial002.py b/docs_src/body_multiple_params/tutorial002_py39.py
similarity index 100%
rename from docs_src/body_multiple_params/tutorial002.py
rename to docs_src/body_multiple_params/tutorial002_py39.py
diff --git a/docs_src/body_multiple_params/tutorial003_an.py b/docs_src/body_multiple_params/tutorial003_an.py
deleted file mode 100644
index 39ef7340a..000000000
--- a/docs_src/body_multiple_params/tutorial003_an.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-class User(BaseModel):
- username: str
- full_name: Union[str, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- item_id: int, item: Item, user: User, importance: Annotated[int, Body()]
-):
- results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
- return results
diff --git a/docs_src/body_multiple_params/tutorial003.py b/docs_src/body_multiple_params/tutorial003_py39.py
similarity index 100%
rename from docs_src/body_multiple_params/tutorial003.py
rename to docs_src/body_multiple_params/tutorial003_py39.py
diff --git a/docs_src/body_multiple_params/tutorial004_an.py b/docs_src/body_multiple_params/tutorial004_an.py
deleted file mode 100644
index f6830f392..000000000
--- a/docs_src/body_multiple_params/tutorial004_an.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-class User(BaseModel):
- username: str
- full_name: Union[str, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- *,
- item_id: int,
- item: Item,
- user: User,
- importance: Annotated[int, Body(gt=0)],
- q: Union[str, None] = None,
-):
- results = {"item_id": item_id, "item": item, "user": user, "importance": importance}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/body_multiple_params/tutorial004.py b/docs_src/body_multiple_params/tutorial004_py39.py
similarity index 100%
rename from docs_src/body_multiple_params/tutorial004.py
rename to docs_src/body_multiple_params/tutorial004_py39.py
diff --git a/docs_src/body_multiple_params/tutorial005_an.py b/docs_src/body_multiple_params/tutorial005_an.py
deleted file mode 100644
index dadde80b5..000000000
--- a/docs_src/body_multiple_params/tutorial005_an.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_multiple_params/tutorial005.py b/docs_src/body_multiple_params/tutorial005_py39.py
similarity index 100%
rename from docs_src/body_multiple_params/tutorial005.py
rename to docs_src/body_multiple_params/tutorial005_py39.py
diff --git a/docs_src/body_nested_models/__init__.py b/docs_src/body_nested_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/body_nested_models/tutorial001.py b/docs_src/body_nested_models/tutorial001_py39.py
similarity index 100%
rename from docs_src/body_nested_models/tutorial001.py
rename to docs_src/body_nested_models/tutorial001_py39.py
diff --git a/docs_src/body_nested_models/tutorial002.py b/docs_src/body_nested_models/tutorial002.py
deleted file mode 100644
index 155cff788..000000000
--- a/docs_src/body_nested_models/tutorial002.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: List[str] = []
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_nested_models/tutorial003.py b/docs_src/body_nested_models/tutorial003.py
deleted file mode 100644
index 84ed18bf4..000000000
--- a/docs_src/body_nested_models/tutorial003.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_nested_models/tutorial004.py b/docs_src/body_nested_models/tutorial004.py
deleted file mode 100644
index a07bfacac..000000000
--- a/docs_src/body_nested_models/tutorial004.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Image(BaseModel):
- url: str
- name: str
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
- image: Union[Image, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_nested_models/tutorial005.py b/docs_src/body_nested_models/tutorial005.py
deleted file mode 100644
index 5a01264ed..000000000
--- a/docs_src/body_nested_models/tutorial005.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel, HttpUrl
-
-app = FastAPI()
-
-
-class Image(BaseModel):
- url: HttpUrl
- name: str
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
- image: Union[Image, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_nested_models/tutorial006.py b/docs_src/body_nested_models/tutorial006.py
deleted file mode 100644
index 75f1f30e3..000000000
--- a/docs_src/body_nested_models/tutorial006.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import List, Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel, HttpUrl
-
-app = FastAPI()
-
-
-class Image(BaseModel):
- url: HttpUrl
- name: str
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
- images: Union[List[Image], None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/body_nested_models/tutorial007.py b/docs_src/body_nested_models/tutorial007.py
deleted file mode 100644
index 641f09dce..000000000
--- a/docs_src/body_nested_models/tutorial007.py
+++ /dev/null
@@ -1,32 +0,0 @@
-from typing import List, Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel, HttpUrl
-
-app = FastAPI()
-
-
-class Image(BaseModel):
- url: HttpUrl
- name: str
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
- images: Union[List[Image], None] = None
-
-
-class Offer(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- items: List[Item]
-
-
-@app.post("/offers/")
-async def create_offer(offer: Offer):
- return offer
diff --git a/docs_src/body_nested_models/tutorial008.py b/docs_src/body_nested_models/tutorial008.py
deleted file mode 100644
index 3431cc636..000000000
--- a/docs_src/body_nested_models/tutorial008.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI
-from pydantic import BaseModel, HttpUrl
-
-app = FastAPI()
-
-
-class Image(BaseModel):
- url: HttpUrl
- name: str
-
-
-@app.post("/images/multiple/")
-async def create_multiple_images(images: List[Image]):
- return images
diff --git a/docs_src/body_nested_models/tutorial009.py b/docs_src/body_nested_models/tutorial009.py
deleted file mode 100644
index 41dce946e..000000000
--- a/docs_src/body_nested_models/tutorial009.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from typing import Dict
-
-from fastapi import FastAPI
-
-app = FastAPI()
-
-
-@app.post("/index-weights/")
-async def create_index_weights(weights: Dict[int, float]):
- return weights
diff --git a/docs_src/body_updates/__init__.py b/docs_src/body_updates/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/body_updates/tutorial001.py b/docs_src/body_updates/tutorial001.py
deleted file mode 100644
index 4e65d77e2..000000000
--- a/docs_src/body_updates/tutorial001.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from fastapi.encoders import jsonable_encoder
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: Union[str, None] = None
- description: Union[str, None] = None
- price: Union[float, None] = None
- tax: float = 10.5
- tags: List[str] = []
-
-
-items = {
- "foo": {"name": "Foo", "price": 50.2},
- "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
- "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
-}
-
-
-@app.get("/items/{item_id}", response_model=Item)
-async def read_item(item_id: str):
- return items[item_id]
-
-
-@app.put("/items/{item_id}", response_model=Item)
-async def update_item(item_id: str, item: Item):
- update_item_encoded = jsonable_encoder(item)
- items[item_id] = update_item_encoded
- return update_item_encoded
diff --git a/docs_src/body_updates/tutorial002.py b/docs_src/body_updates/tutorial002.py
deleted file mode 100644
index c3a0fe79e..000000000
--- a/docs_src/body_updates/tutorial002.py
+++ /dev/null
@@ -1,37 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from fastapi.encoders import jsonable_encoder
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: Union[str, None] = None
- description: Union[str, None] = None
- price: Union[float, None] = None
- tax: float = 10.5
- tags: List[str] = []
-
-
-items = {
- "foo": {"name": "Foo", "price": 50.2},
- "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
- "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
-}
-
-
-@app.get("/items/{item_id}", response_model=Item)
-async def read_item(item_id: str):
- return items[item_id]
-
-
-@app.patch("/items/{item_id}", response_model=Item)
-async def update_item(item_id: str, item: Item):
- stored_item_data = items[item_id]
- stored_item_model = Item(**stored_item_data)
- update_data = item.dict(exclude_unset=True)
- updated_item = stored_item_model.copy(update=update_data)
- items[item_id] = jsonable_encoder(updated_item)
- return updated_item
diff --git a/docs_src/body_updates/tutorial002_py310.py b/docs_src/body_updates/tutorial002_py310.py
index 349841496..e5db71110 100644
--- a/docs_src/body_updates/tutorial002_py310.py
+++ b/docs_src/body_updates/tutorial002_py310.py
@@ -29,7 +29,7 @@ async def read_item(item_id: str):
async def update_item(item_id: str, item: Item):
stored_item_data = items[item_id]
stored_item_model = Item(**stored_item_data)
- update_data = item.dict(exclude_unset=True)
- updated_item = stored_item_model.copy(update=update_data)
+ update_data = item.model_dump(exclude_unset=True)
+ updated_item = stored_item_model.model_copy(update=update_data)
items[item_id] = jsonable_encoder(updated_item)
return updated_item
diff --git a/docs_src/body_updates/tutorial002_py39.py b/docs_src/body_updates/tutorial002_py39.py
index eb35b3521..eddd7af71 100644
--- a/docs_src/body_updates/tutorial002_py39.py
+++ b/docs_src/body_updates/tutorial002_py39.py
@@ -31,7 +31,7 @@ async def read_item(item_id: str):
async def update_item(item_id: str, item: Item):
stored_item_data = items[item_id]
stored_item_model = Item(**stored_item_data)
- update_data = item.dict(exclude_unset=True)
- updated_item = stored_item_model.copy(update=update_data)
+ update_data = item.model_dump(exclude_unset=True)
+ updated_item = stored_item_model.model_copy(update=update_data)
items[item_id] = jsonable_encoder(updated_item)
return updated_item
diff --git a/docs_src/conditional_openapi/__init__.py b/docs_src/conditional_openapi/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/conditional_openapi/tutorial001.py b/docs_src/conditional_openapi/tutorial001_py39.py
similarity index 100%
rename from docs_src/conditional_openapi/tutorial001.py
rename to docs_src/conditional_openapi/tutorial001_py39.py
diff --git a/docs_src/configure_swagger_ui/__init__.py b/docs_src/configure_swagger_ui/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/configure_swagger_ui/tutorial001.py b/docs_src/configure_swagger_ui/tutorial001_py39.py
similarity index 100%
rename from docs_src/configure_swagger_ui/tutorial001.py
rename to docs_src/configure_swagger_ui/tutorial001_py39.py
diff --git a/docs_src/configure_swagger_ui/tutorial002.py b/docs_src/configure_swagger_ui/tutorial002_py39.py
similarity index 100%
rename from docs_src/configure_swagger_ui/tutorial002.py
rename to docs_src/configure_swagger_ui/tutorial002_py39.py
diff --git a/docs_src/configure_swagger_ui/tutorial003.py b/docs_src/configure_swagger_ui/tutorial003_py39.py
similarity index 100%
rename from docs_src/configure_swagger_ui/tutorial003.py
rename to docs_src/configure_swagger_ui/tutorial003_py39.py
diff --git a/docs_src/cookie_param_models/__init__.py b/docs_src/cookie_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/cookie_param_models/tutorial001_an.py b/docs_src/cookie_param_models/tutorial001_an.py
deleted file mode 100644
index e5839ffd5..000000000
--- a/docs_src/cookie_param_models/tutorial001_an.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- session_id: str
- fatebook_tracker: Union[str, None] = None
- googall_tracker: Union[str, None] = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Annotated[Cookies, Cookie()]):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial001.py b/docs_src/cookie_param_models/tutorial001_py39.py
similarity index 100%
rename from docs_src/cookie_param_models/tutorial001.py
rename to docs_src/cookie_param_models/tutorial001_py39.py
diff --git a/docs_src/cookie_param_models/tutorial002_an.py b/docs_src/cookie_param_models/tutorial002_an.py
deleted file mode 100644
index ce5644b7b..000000000
--- a/docs_src/cookie_param_models/tutorial002_an.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- model_config = {"extra": "forbid"}
-
- session_id: str
- fatebook_tracker: Union[str, None] = None
- googall_tracker: Union[str, None] = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Annotated[Cookies, Cookie()]):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1.py b/docs_src/cookie_param_models/tutorial002_pv1.py
deleted file mode 100644
index 13f78b850..000000000
--- a/docs_src/cookie_param_models/tutorial002_pv1.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- class Config:
- extra = "forbid"
-
- session_id: str
- fatebook_tracker: Union[str, None] = None
- googall_tracker: Union[str, None] = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Cookies = Cookie()):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an.py b/docs_src/cookie_param_models/tutorial002_pv1_an.py
deleted file mode 100644
index ddfda9b6f..000000000
--- a/docs_src/cookie_param_models/tutorial002_pv1_an.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- class Config:
- extra = "forbid"
-
- session_id: str
- fatebook_tracker: Union[str, None] = None
- googall_tracker: Union[str, None] = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Annotated[Cookies, Cookie()]):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py b/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py
deleted file mode 100644
index ac00360b6..000000000
--- a/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Annotated
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- class Config:
- extra = "forbid"
-
- session_id: str
- fatebook_tracker: str | None = None
- googall_tracker: str | None = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Annotated[Cookies, Cookie()]):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py b/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py
deleted file mode 100644
index 573caea4b..000000000
--- a/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import Annotated, Union
-
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- class Config:
- extra = "forbid"
-
- session_id: str
- fatebook_tracker: Union[str, None] = None
- googall_tracker: Union[str, None] = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Annotated[Cookies, Cookie()]):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_py310.py b/docs_src/cookie_param_models/tutorial002_pv1_py310.py
deleted file mode 100644
index 2c59aad12..000000000
--- a/docs_src/cookie_param_models/tutorial002_pv1_py310.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from fastapi import Cookie, FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Cookies(BaseModel):
- class Config:
- extra = "forbid"
-
- session_id: str
- fatebook_tracker: str | None = None
- googall_tracker: str | None = None
-
-
-@app.get("/items/")
-async def read_items(cookies: Cookies = Cookie()):
- return cookies
diff --git a/docs_src/cookie_param_models/tutorial002.py b/docs_src/cookie_param_models/tutorial002_py39.py
similarity index 100%
rename from docs_src/cookie_param_models/tutorial002.py
rename to docs_src/cookie_param_models/tutorial002_py39.py
diff --git a/docs_src/cookie_params/__init__.py b/docs_src/cookie_params/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/cookie_params/tutorial001_an.py b/docs_src/cookie_params/tutorial001_an.py
deleted file mode 100644
index 6d5931229..000000000
--- a/docs_src/cookie_params/tutorial001_an.py
+++ /dev/null
@@ -1,11 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(ads_id: Annotated[Union[str, None], Cookie()] = None):
- return {"ads_id": ads_id}
diff --git a/docs_src/cookie_params/tutorial001.py b/docs_src/cookie_params/tutorial001_py39.py
similarity index 100%
rename from docs_src/cookie_params/tutorial001.py
rename to docs_src/cookie_params/tutorial001_py39.py
diff --git a/docs_src/cors/__init__.py b/docs_src/cors/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/cors/tutorial001.py b/docs_src/cors/tutorial001_py39.py
similarity index 100%
rename from docs_src/cors/tutorial001.py
rename to docs_src/cors/tutorial001_py39.py
diff --git a/docs_src/custom_docs_ui/__init__.py b/docs_src/custom_docs_ui/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/custom_docs_ui/tutorial001.py b/docs_src/custom_docs_ui/tutorial001_py39.py
similarity index 100%
rename from docs_src/custom_docs_ui/tutorial001.py
rename to docs_src/custom_docs_ui/tutorial001_py39.py
diff --git a/docs_src/custom_docs_ui/tutorial002.py b/docs_src/custom_docs_ui/tutorial002_py39.py
similarity index 100%
rename from docs_src/custom_docs_ui/tutorial002.py
rename to docs_src/custom_docs_ui/tutorial002_py39.py
diff --git a/docs_src/custom_request_and_route/__init__.py b/docs_src/custom_request_and_route/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/custom_request_and_route/tutorial001.py b/docs_src/custom_request_and_route/tutorial001.py
deleted file mode 100644
index 268ce9019..000000000
--- a/docs_src/custom_request_and_route/tutorial001.py
+++ /dev/null
@@ -1,35 +0,0 @@
-import gzip
-from typing import Callable, List
-
-from fastapi import Body, FastAPI, Request, Response
-from fastapi.routing import APIRoute
-
-
-class GzipRequest(Request):
- async def body(self) -> bytes:
- if not hasattr(self, "_body"):
- body = await super().body()
- if "gzip" in self.headers.getlist("Content-Encoding"):
- body = gzip.decompress(body)
- self._body = body
- return self._body
-
-
-class GzipRoute(APIRoute):
- def get_route_handler(self) -> Callable:
- original_route_handler = super().get_route_handler()
-
- async def custom_route_handler(request: Request) -> Response:
- request = GzipRequest(request.scope, request.receive)
- return await original_route_handler(request)
-
- return custom_route_handler
-
-
-app = FastAPI()
-app.router.route_class = GzipRoute
-
-
-@app.post("/sum")
-async def sum_numbers(numbers: List[int] = Body()):
- return {"sum": sum(numbers)}
diff --git a/docs_src/custom_request_and_route/tutorial001_an_py310.py b/docs_src/custom_request_and_route/tutorial001_an_py310.py
new file mode 100644
index 000000000..381bab6d8
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial001_an_py310.py
@@ -0,0 +1,36 @@
+import gzip
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import Body, FastAPI, Request, Response
+from fastapi.routing import APIRoute
+
+
+class GzipRequest(Request):
+ async def body(self) -> bytes:
+ if not hasattr(self, "_body"):
+ body = await super().body()
+ if "gzip" in self.headers.getlist("Content-Encoding"):
+ body = gzip.decompress(body)
+ self._body = body
+ return self._body
+
+
+class GzipRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ request = GzipRequest(request.scope, request.receive)
+ return await original_route_handler(request)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = GzipRoute
+
+
+@app.post("/sum")
+async def sum_numbers(numbers: Annotated[list[int], Body()]):
+ return {"sum": sum(numbers)}
diff --git a/docs_src/custom_request_and_route/tutorial001_an_py39.py b/docs_src/custom_request_and_route/tutorial001_an_py39.py
new file mode 100644
index 000000000..076727e64
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial001_an_py39.py
@@ -0,0 +1,35 @@
+import gzip
+from typing import Annotated, Callable
+
+from fastapi import Body, FastAPI, Request, Response
+from fastapi.routing import APIRoute
+
+
+class GzipRequest(Request):
+ async def body(self) -> bytes:
+ if not hasattr(self, "_body"):
+ body = await super().body()
+ if "gzip" in self.headers.getlist("Content-Encoding"):
+ body = gzip.decompress(body)
+ self._body = body
+ return self._body
+
+
+class GzipRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ request = GzipRequest(request.scope, request.receive)
+ return await original_route_handler(request)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = GzipRoute
+
+
+@app.post("/sum")
+async def sum_numbers(numbers: Annotated[list[int], Body()]):
+ return {"sum": sum(numbers)}
diff --git a/docs_src/custom_request_and_route/tutorial001_py310.py b/docs_src/custom_request_and_route/tutorial001_py310.py
new file mode 100644
index 000000000..c678088ce
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial001_py310.py
@@ -0,0 +1,35 @@
+import gzip
+from collections.abc import Callable
+
+from fastapi import Body, FastAPI, Request, Response
+from fastapi.routing import APIRoute
+
+
+class GzipRequest(Request):
+ async def body(self) -> bytes:
+ if not hasattr(self, "_body"):
+ body = await super().body()
+ if "gzip" in self.headers.getlist("Content-Encoding"):
+ body = gzip.decompress(body)
+ self._body = body
+ return self._body
+
+
+class GzipRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ request = GzipRequest(request.scope, request.receive)
+ return await original_route_handler(request)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = GzipRoute
+
+
+@app.post("/sum")
+async def sum_numbers(numbers: list[int] = Body()):
+ return {"sum": sum(numbers)}
diff --git a/docs_src/custom_request_and_route/tutorial001_py39.py b/docs_src/custom_request_and_route/tutorial001_py39.py
new file mode 100644
index 000000000..54b20b942
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial001_py39.py
@@ -0,0 +1,35 @@
+import gzip
+from typing import Callable
+
+from fastapi import Body, FastAPI, Request, Response
+from fastapi.routing import APIRoute
+
+
+class GzipRequest(Request):
+ async def body(self) -> bytes:
+ if not hasattr(self, "_body"):
+ body = await super().body()
+ if "gzip" in self.headers.getlist("Content-Encoding"):
+ body = gzip.decompress(body)
+ self._body = body
+ return self._body
+
+
+class GzipRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ request = GzipRequest(request.scope, request.receive)
+ return await original_route_handler(request)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = GzipRoute
+
+
+@app.post("/sum")
+async def sum_numbers(numbers: list[int] = Body()):
+ return {"sum": sum(numbers)}
diff --git a/docs_src/custom_request_and_route/tutorial002.py b/docs_src/custom_request_and_route/tutorial002.py
deleted file mode 100644
index cee4a95f0..000000000
--- a/docs_src/custom_request_and_route/tutorial002.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from typing import Callable, List
-
-from fastapi import Body, FastAPI, HTTPException, Request, Response
-from fastapi.exceptions import RequestValidationError
-from fastapi.routing import APIRoute
-
-
-class ValidationErrorLoggingRoute(APIRoute):
- def get_route_handler(self) -> Callable:
- original_route_handler = super().get_route_handler()
-
- async def custom_route_handler(request: Request) -> Response:
- try:
- return await original_route_handler(request)
- except RequestValidationError as exc:
- body = await request.body()
- detail = {"errors": exc.errors(), "body": body.decode()}
- raise HTTPException(status_code=422, detail=detail)
-
- return custom_route_handler
-
-
-app = FastAPI()
-app.router.route_class = ValidationErrorLoggingRoute
-
-
-@app.post("/")
-async def sum_numbers(numbers: List[int] = Body()):
- return sum(numbers)
diff --git a/docs_src/custom_request_and_route/tutorial002_an_py310.py b/docs_src/custom_request_and_route/tutorial002_an_py310.py
new file mode 100644
index 000000000..69b7de485
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial002_an_py310.py
@@ -0,0 +1,30 @@
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import Body, FastAPI, HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.routing import APIRoute
+
+
+class ValidationErrorLoggingRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ try:
+ return await original_route_handler(request)
+ except RequestValidationError as exc:
+ body = await request.body()
+ detail = {"errors": exc.errors(), "body": body.decode()}
+ raise HTTPException(status_code=422, detail=detail)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = ValidationErrorLoggingRoute
+
+
+@app.post("/")
+async def sum_numbers(numbers: Annotated[list[int], Body()]):
+ return sum(numbers)
diff --git a/docs_src/custom_request_and_route/tutorial002_an_py39.py b/docs_src/custom_request_and_route/tutorial002_an_py39.py
new file mode 100644
index 000000000..e7de09de4
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial002_an_py39.py
@@ -0,0 +1,29 @@
+from typing import Annotated, Callable
+
+from fastapi import Body, FastAPI, HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.routing import APIRoute
+
+
+class ValidationErrorLoggingRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ try:
+ return await original_route_handler(request)
+ except RequestValidationError as exc:
+ body = await request.body()
+ detail = {"errors": exc.errors(), "body": body.decode()}
+ raise HTTPException(status_code=422, detail=detail)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = ValidationErrorLoggingRoute
+
+
+@app.post("/")
+async def sum_numbers(numbers: Annotated[list[int], Body()]):
+ return sum(numbers)
diff --git a/docs_src/custom_request_and_route/tutorial002_py310.py b/docs_src/custom_request_and_route/tutorial002_py310.py
new file mode 100644
index 000000000..13a5ca542
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial002_py310.py
@@ -0,0 +1,29 @@
+from collections.abc import Callable
+
+from fastapi import Body, FastAPI, HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.routing import APIRoute
+
+
+class ValidationErrorLoggingRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ try:
+ return await original_route_handler(request)
+ except RequestValidationError as exc:
+ body = await request.body()
+ detail = {"errors": exc.errors(), "body": body.decode()}
+ raise HTTPException(status_code=422, detail=detail)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = ValidationErrorLoggingRoute
+
+
+@app.post("/")
+async def sum_numbers(numbers: list[int] = Body()):
+ return sum(numbers)
diff --git a/docs_src/custom_request_and_route/tutorial002_py39.py b/docs_src/custom_request_and_route/tutorial002_py39.py
new file mode 100644
index 000000000..c4e474828
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial002_py39.py
@@ -0,0 +1,29 @@
+from typing import Callable
+
+from fastapi import Body, FastAPI, HTTPException, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.routing import APIRoute
+
+
+class ValidationErrorLoggingRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ try:
+ return await original_route_handler(request)
+ except RequestValidationError as exc:
+ body = await request.body()
+ detail = {"errors": exc.errors(), "body": body.decode()}
+ raise HTTPException(status_code=422, detail=detail)
+
+ return custom_route_handler
+
+
+app = FastAPI()
+app.router.route_class = ValidationErrorLoggingRoute
+
+
+@app.post("/")
+async def sum_numbers(numbers: list[int] = Body()):
+ return sum(numbers)
diff --git a/docs_src/custom_request_and_route/tutorial003_py310.py b/docs_src/custom_request_and_route/tutorial003_py310.py
new file mode 100644
index 000000000..f4e60be61
--- /dev/null
+++ b/docs_src/custom_request_and_route/tutorial003_py310.py
@@ -0,0 +1,39 @@
+import time
+from collections.abc import Callable
+
+from fastapi import APIRouter, FastAPI, Request, Response
+from fastapi.routing import APIRoute
+
+
+class TimedRoute(APIRoute):
+ def get_route_handler(self) -> Callable:
+ original_route_handler = super().get_route_handler()
+
+ async def custom_route_handler(request: Request) -> Response:
+ before = time.time()
+ response: Response = await original_route_handler(request)
+ duration = time.time() - before
+ response.headers["X-Response-Time"] = str(duration)
+ print(f"route duration: {duration}")
+ print(f"route response: {response}")
+ print(f"route response headers: {response.headers}")
+ return response
+
+ return custom_route_handler
+
+
+app = FastAPI()
+router = APIRouter(route_class=TimedRoute)
+
+
+@app.get("/")
+async def not_timed():
+ return {"message": "Not timed"}
+
+
+@router.get("/timed")
+async def timed():
+ return {"message": "It's the time of my life"}
+
+
+app.include_router(router)
diff --git a/docs_src/custom_request_and_route/tutorial003.py b/docs_src/custom_request_and_route/tutorial003_py39.py
similarity index 100%
rename from docs_src/custom_request_and_route/tutorial003.py
rename to docs_src/custom_request_and_route/tutorial003_py39.py
diff --git a/docs_src/custom_response/__init__.py b/docs_src/custom_response/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/custom_response/tutorial001.py b/docs_src/custom_response/tutorial001_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial001.py
rename to docs_src/custom_response/tutorial001_py39.py
diff --git a/docs_src/custom_response/tutorial001b.py b/docs_src/custom_response/tutorial001b_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial001b.py
rename to docs_src/custom_response/tutorial001b_py39.py
diff --git a/docs_src/custom_response/tutorial002.py b/docs_src/custom_response/tutorial002_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial002.py
rename to docs_src/custom_response/tutorial002_py39.py
diff --git a/docs_src/custom_response/tutorial003.py b/docs_src/custom_response/tutorial003_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial003.py
rename to docs_src/custom_response/tutorial003_py39.py
diff --git a/docs_src/custom_response/tutorial004.py b/docs_src/custom_response/tutorial004_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial004.py
rename to docs_src/custom_response/tutorial004_py39.py
diff --git a/docs_src/custom_response/tutorial005.py b/docs_src/custom_response/tutorial005_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial005.py
rename to docs_src/custom_response/tutorial005_py39.py
diff --git a/docs_src/custom_response/tutorial006.py b/docs_src/custom_response/tutorial006_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial006.py
rename to docs_src/custom_response/tutorial006_py39.py
diff --git a/docs_src/custom_response/tutorial006b.py b/docs_src/custom_response/tutorial006b_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial006b.py
rename to docs_src/custom_response/tutorial006b_py39.py
diff --git a/docs_src/custom_response/tutorial006c.py b/docs_src/custom_response/tutorial006c_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial006c.py
rename to docs_src/custom_response/tutorial006c_py39.py
diff --git a/docs_src/custom_response/tutorial007.py b/docs_src/custom_response/tutorial007_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial007.py
rename to docs_src/custom_response/tutorial007_py39.py
diff --git a/docs_src/custom_response/tutorial008.py b/docs_src/custom_response/tutorial008_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial008.py
rename to docs_src/custom_response/tutorial008_py39.py
diff --git a/docs_src/custom_response/tutorial009.py b/docs_src/custom_response/tutorial009_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial009.py
rename to docs_src/custom_response/tutorial009_py39.py
diff --git a/docs_src/custom_response/tutorial009b.py b/docs_src/custom_response/tutorial009b_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial009b.py
rename to docs_src/custom_response/tutorial009b_py39.py
diff --git a/docs_src/custom_response/tutorial009c.py b/docs_src/custom_response/tutorial009c_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial009c.py
rename to docs_src/custom_response/tutorial009c_py39.py
diff --git a/docs_src/custom_response/tutorial010.py b/docs_src/custom_response/tutorial010_py39.py
similarity index 100%
rename from docs_src/custom_response/tutorial010.py
rename to docs_src/custom_response/tutorial010_py39.py
diff --git a/docs_src/dataclasses/tutorial002.py b/docs_src/dataclasses/tutorial002.py
deleted file mode 100644
index ece2f150c..000000000
--- a/docs_src/dataclasses/tutorial002.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from dataclasses import dataclass, field
-from typing import List, Union
-
-from fastapi import FastAPI
-
-
-@dataclass
-class Item:
- name: str
- price: float
- tags: List[str] = field(default_factory=list)
- description: Union[str, None] = None
- tax: Union[float, None] = None
-
-
-app = FastAPI()
-
-
-@app.get("/items/next", response_model=Item)
-async def read_next_item():
- return {
- "name": "Island In The Moon",
- "price": 12.99,
- "description": "A place to be playin' and havin' fun",
- "tags": ["breater"],
- }
diff --git a/docs_src/dataclasses/tutorial003.py b/docs_src/dataclasses/tutorial003.py
deleted file mode 100644
index c61315513..000000000
--- a/docs_src/dataclasses/tutorial003.py
+++ /dev/null
@@ -1,55 +0,0 @@
-from dataclasses import field # (1)
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic.dataclasses import dataclass # (2)
-
-
-@dataclass
-class Item:
- name: str
- description: Union[str, None] = None
-
-
-@dataclass
-class Author:
- name: str
- items: List[Item] = field(default_factory=list) # (3)
-
-
-app = FastAPI()
-
-
-@app.post("/authors/{author_id}/items/", response_model=Author) # (4)
-async def create_author_items(author_id: str, items: List[Item]): # (5)
- return {"name": author_id, "items": items} # (6)
-
-
-@app.get("/authors/", response_model=List[Author]) # (7)
-def get_authors(): # (8)
- return [ # (9)
- {
- "name": "Breaters",
- "items": [
- {
- "name": "Island In The Moon",
- "description": "A place to be playin' and havin' fun",
- },
- {"name": "Holy Buddies"},
- ],
- },
- {
- "name": "System of an Up",
- "items": [
- {
- "name": "Salt",
- "description": "The kombucha mushroom people's favorite",
- },
- {"name": "Pad Thai"},
- {
- "name": "Lonely Night",
- "description": "The mostests lonliest nightiest of allest",
- },
- ],
- },
- ]
diff --git a/docs_src/dataclasses_/__init__.py b/docs_src/dataclasses_/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/dataclasses_/tutorial001_py310.py b/docs_src/dataclasses_/tutorial001_py310.py
new file mode 100644
index 000000000..ab709a7c8
--- /dev/null
+++ b/docs_src/dataclasses_/tutorial001_py310.py
@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+from fastapi import FastAPI
+
+
+@dataclass
+class Item:
+ name: str
+ price: float
+ description: str | None = None
+ tax: float | None = None
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Item):
+ return item
diff --git a/docs_src/dataclasses/tutorial001.py b/docs_src/dataclasses_/tutorial001_py39.py
similarity index 100%
rename from docs_src/dataclasses/tutorial001.py
rename to docs_src/dataclasses_/tutorial001_py39.py
diff --git a/docs_src/dataclasses_/tutorial002_py310.py b/docs_src/dataclasses_/tutorial002_py310.py
new file mode 100644
index 000000000..e16249f1e
--- /dev/null
+++ b/docs_src/dataclasses_/tutorial002_py310.py
@@ -0,0 +1,25 @@
+from dataclasses import dataclass, field
+
+from fastapi import FastAPI
+
+
+@dataclass
+class Item:
+ name: str
+ price: float
+ tags: list[str] = field(default_factory=list)
+ description: str | None = None
+ tax: float | None = None
+
+
+app = FastAPI()
+
+
+@app.get("/items/next", response_model=Item)
+async def read_next_item():
+ return {
+ "name": "Island In The Moon",
+ "price": 12.99,
+ "description": "A place to be playin' and havin' fun",
+ "tags": ["breater"],
+ }
diff --git a/docs_src/dataclasses_/tutorial002_py39.py b/docs_src/dataclasses_/tutorial002_py39.py
new file mode 100644
index 000000000..0c23765d8
--- /dev/null
+++ b/docs_src/dataclasses_/tutorial002_py39.py
@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from typing import Union
+
+from fastapi import FastAPI
+
+
+@dataclass
+class Item:
+ name: str
+ price: float
+ tags: list[str] = field(default_factory=list)
+ description: Union[str, None] = None
+ tax: Union[float, None] = None
+
+
+app = FastAPI()
+
+
+@app.get("/items/next", response_model=Item)
+async def read_next_item():
+ return {
+ "name": "Island In The Moon",
+ "price": 12.99,
+ "description": "A place to be playin' and havin' fun",
+ "tags": ["breater"],
+ }
diff --git a/docs_src/dataclasses_/tutorial003_py310.py b/docs_src/dataclasses_/tutorial003_py310.py
new file mode 100644
index 000000000..9b9a3fd63
--- /dev/null
+++ b/docs_src/dataclasses_/tutorial003_py310.py
@@ -0,0 +1,54 @@
+from dataclasses import field # (1)
+
+from fastapi import FastAPI
+from pydantic.dataclasses import dataclass # (2)
+
+
+@dataclass
+class Item:
+ name: str
+ description: str | None = None
+
+
+@dataclass
+class Author:
+ name: str
+ items: list[Item] = field(default_factory=list) # (3)
+
+
+app = FastAPI()
+
+
+@app.post("/authors/{author_id}/items/", response_model=Author) # (4)
+async def create_author_items(author_id: str, items: list[Item]): # (5)
+ return {"name": author_id, "items": items} # (6)
+
+
+@app.get("/authors/", response_model=list[Author]) # (7)
+def get_authors(): # (8)
+ return [ # (9)
+ {
+ "name": "Breaters",
+ "items": [
+ {
+ "name": "Island In The Moon",
+ "description": "A place to be playin' and havin' fun",
+ },
+ {"name": "Holy Buddies"},
+ ],
+ },
+ {
+ "name": "System of an Up",
+ "items": [
+ {
+ "name": "Salt",
+ "description": "The kombucha mushroom people's favorite",
+ },
+ {"name": "Pad Thai"},
+ {
+ "name": "Lonely Night",
+ "description": "The mostests lonliest nightiest of allest",
+ },
+ ],
+ },
+ ]
diff --git a/docs_src/dataclasses_/tutorial003_py39.py b/docs_src/dataclasses_/tutorial003_py39.py
new file mode 100644
index 000000000..991708c00
--- /dev/null
+++ b/docs_src/dataclasses_/tutorial003_py39.py
@@ -0,0 +1,55 @@
+from dataclasses import field # (1)
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic.dataclasses import dataclass # (2)
+
+
+@dataclass
+class Item:
+ name: str
+ description: Union[str, None] = None
+
+
+@dataclass
+class Author:
+ name: str
+ items: list[Item] = field(default_factory=list) # (3)
+
+
+app = FastAPI()
+
+
+@app.post("/authors/{author_id}/items/", response_model=Author) # (4)
+async def create_author_items(author_id: str, items: list[Item]): # (5)
+ return {"name": author_id, "items": items} # (6)
+
+
+@app.get("/authors/", response_model=list[Author]) # (7)
+def get_authors(): # (8)
+ return [ # (9)
+ {
+ "name": "Breaters",
+ "items": [
+ {
+ "name": "Island In The Moon",
+ "description": "A place to be playin' and havin' fun",
+ },
+ {"name": "Holy Buddies"},
+ ],
+ },
+ {
+ "name": "System of an Up",
+ "items": [
+ {
+ "name": "Salt",
+ "description": "The kombucha mushroom people's favorite",
+ },
+ {"name": "Pad Thai"},
+ {
+ "name": "Lonely Night",
+ "description": "The mostests lonliest nightiest of allest",
+ },
+ ],
+ },
+ ]
diff --git a/docs_src/debugging/__init__.py b/docs_src/debugging/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/debugging/tutorial001.py b/docs_src/debugging/tutorial001_py39.py
similarity index 100%
rename from docs_src/debugging/tutorial001.py
rename to docs_src/debugging/tutorial001_py39.py
diff --git a/docs_src/dependencies/__init__.py b/docs_src/dependencies/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/dependencies/tutorial001_02_an.py b/docs_src/dependencies/tutorial001_02_an.py
deleted file mode 100644
index 455d60c82..000000000
--- a/docs_src/dependencies/tutorial001_02_an.py
+++ /dev/null
@@ -1,25 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-async def common_parameters(
- q: Union[str, None] = None, skip: int = 0, limit: int = 100
-):
- return {"q": q, "skip": skip, "limit": limit}
-
-
-CommonsDep = Annotated[dict, Depends(common_parameters)]
-
-
-@app.get("/items/")
-async def read_items(commons: CommonsDep):
- return commons
-
-
-@app.get("/users/")
-async def read_users(commons: CommonsDep):
- return commons
diff --git a/docs_src/dependencies/tutorial001_an.py b/docs_src/dependencies/tutorial001_an.py
deleted file mode 100644
index 81e24fe86..000000000
--- a/docs_src/dependencies/tutorial001_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-async def common_parameters(
- q: Union[str, None] = None, skip: int = 0, limit: int = 100
-):
- return {"q": q, "skip": skip, "limit": limit}
-
-
-@app.get("/items/")
-async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
- return commons
-
-
-@app.get("/users/")
-async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
- return commons
diff --git a/docs_src/dependencies/tutorial001.py b/docs_src/dependencies/tutorial001_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial001.py
rename to docs_src/dependencies/tutorial001_py39.py
diff --git a/docs_src/dependencies/tutorial002_an.py b/docs_src/dependencies/tutorial002_an.py
deleted file mode 100644
index 964ccf66c..000000000
--- a/docs_src/dependencies/tutorial002_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
-
-
-class CommonQueryParams:
- def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100):
- self.q = q
- self.skip = skip
- self.limit = limit
-
-
-@app.get("/items/")
-async def read_items(commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)]):
- response = {}
- if commons.q:
- response.update({"q": commons.q})
- items = fake_items_db[commons.skip : commons.skip + commons.limit]
- response.update({"items": items})
- return response
diff --git a/docs_src/dependencies/tutorial002.py b/docs_src/dependencies/tutorial002_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial002.py
rename to docs_src/dependencies/tutorial002_py39.py
diff --git a/docs_src/dependencies/tutorial003_an.py b/docs_src/dependencies/tutorial003_an.py
deleted file mode 100644
index ba8e9f717..000000000
--- a/docs_src/dependencies/tutorial003_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Any, Union
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
-
-
-class CommonQueryParams:
- def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100):
- self.q = q
- self.skip = skip
- self.limit = limit
-
-
-@app.get("/items/")
-async def read_items(commons: Annotated[Any, Depends(CommonQueryParams)]):
- response = {}
- if commons.q:
- response.update({"q": commons.q})
- items = fake_items_db[commons.skip : commons.skip + commons.limit]
- response.update({"items": items})
- return response
diff --git a/docs_src/dependencies/tutorial003.py b/docs_src/dependencies/tutorial003_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial003.py
rename to docs_src/dependencies/tutorial003_py39.py
diff --git a/docs_src/dependencies/tutorial004_an.py b/docs_src/dependencies/tutorial004_an.py
deleted file mode 100644
index 78881a354..000000000
--- a/docs_src/dependencies/tutorial004_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
-
-
-class CommonQueryParams:
- def __init__(self, q: Union[str, None] = None, skip: int = 0, limit: int = 100):
- self.q = q
- self.skip = skip
- self.limit = limit
-
-
-@app.get("/items/")
-async def read_items(commons: Annotated[CommonQueryParams, Depends()]):
- response = {}
- if commons.q:
- response.update({"q": commons.q})
- items = fake_items_db[commons.skip : commons.skip + commons.limit]
- response.update({"items": items})
- return response
diff --git a/docs_src/dependencies/tutorial004.py b/docs_src/dependencies/tutorial004_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial004.py
rename to docs_src/dependencies/tutorial004_py39.py
diff --git a/docs_src/dependencies/tutorial005_an.py b/docs_src/dependencies/tutorial005_an.py
deleted file mode 100644
index 1d78c17a2..000000000
--- a/docs_src/dependencies/tutorial005_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import Union
-
-from fastapi import Cookie, Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-def query_extractor(q: Union[str, None] = None):
- return q
-
-
-def query_or_cookie_extractor(
- q: Annotated[str, Depends(query_extractor)],
- last_query: Annotated[Union[str, None], Cookie()] = None,
-):
- if not q:
- return last_query
- return q
-
-
-@app.get("/items/")
-async def read_query(
- query_or_default: Annotated[str, Depends(query_or_cookie_extractor)],
-):
- return {"q_or_cookie": query_or_default}
diff --git a/docs_src/dependencies/tutorial005.py b/docs_src/dependencies/tutorial005_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial005.py
rename to docs_src/dependencies/tutorial005_py39.py
diff --git a/docs_src/dependencies/tutorial006_an.py b/docs_src/dependencies/tutorial006_an.py
deleted file mode 100644
index 5aaea04d1..000000000
--- a/docs_src/dependencies/tutorial006_an.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from fastapi import Depends, FastAPI, Header, HTTPException
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-async def verify_token(x_token: Annotated[str, Header()]):
- if x_token != "fake-super-secret-token":
- raise HTTPException(status_code=400, detail="X-Token header invalid")
-
-
-async def verify_key(x_key: Annotated[str, Header()]):
- if x_key != "fake-super-secret-key":
- raise HTTPException(status_code=400, detail="X-Key header invalid")
- return x_key
-
-
-@app.get("/items/", dependencies=[Depends(verify_token), Depends(verify_key)])
-async def read_items():
- return [{"item": "Foo"}, {"item": "Bar"}]
diff --git a/docs_src/dependencies/tutorial006.py b/docs_src/dependencies/tutorial006_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial006.py
rename to docs_src/dependencies/tutorial006_py39.py
diff --git a/docs_src/dependencies/tutorial007.py b/docs_src/dependencies/tutorial007_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial007.py
rename to docs_src/dependencies/tutorial007_py39.py
diff --git a/docs_src/dependencies/tutorial008_an.py b/docs_src/dependencies/tutorial008_an.py
deleted file mode 100644
index 2de86f042..000000000
--- a/docs_src/dependencies/tutorial008_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from fastapi import Depends
-from typing_extensions import Annotated
-
-
-async def dependency_a():
- dep_a = generate_dep_a()
- try:
- yield dep_a
- finally:
- dep_a.close()
-
-
-async def dependency_b(dep_a: Annotated[DepA, Depends(dependency_a)]):
- dep_b = generate_dep_b()
- try:
- yield dep_b
- finally:
- dep_b.close(dep_a)
-
-
-async def dependency_c(dep_b: Annotated[DepB, Depends(dependency_b)]):
- dep_c = generate_dep_c()
- try:
- yield dep_c
- finally:
- dep_c.close(dep_b)
diff --git a/docs_src/dependencies/tutorial008.py b/docs_src/dependencies/tutorial008_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial008.py
rename to docs_src/dependencies/tutorial008_py39.py
diff --git a/docs_src/dependencies/tutorial008b_an.py b/docs_src/dependencies/tutorial008b_an.py
deleted file mode 100644
index 84d8f12c1..000000000
--- a/docs_src/dependencies/tutorial008b_an.py
+++ /dev/null
@@ -1,31 +0,0 @@
-from fastapi import Depends, FastAPI, HTTPException
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-data = {
- "plumbus": {"description": "Freshly pickled plumbus", "owner": "Morty"},
- "portal-gun": {"description": "Gun to create portals", "owner": "Rick"},
-}
-
-
-class OwnerError(Exception):
- pass
-
-
-def get_username():
- try:
- yield "Rick"
- except OwnerError as e:
- raise HTTPException(status_code=400, detail=f"Owner error: {e}")
-
-
-@app.get("/items/{item_id}")
-def get_item(item_id: str, username: Annotated[str, Depends(get_username)]):
- if item_id not in data:
- raise HTTPException(status_code=404, detail="Item not found")
- item = data[item_id]
- if item["owner"] != username:
- raise OwnerError(username)
- return item
diff --git a/docs_src/dependencies/tutorial008b.py b/docs_src/dependencies/tutorial008b_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial008b.py
rename to docs_src/dependencies/tutorial008b_py39.py
diff --git a/docs_src/dependencies/tutorial008c_an.py b/docs_src/dependencies/tutorial008c_an.py
deleted file mode 100644
index 94f59f9aa..000000000
--- a/docs_src/dependencies/tutorial008c_an.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from fastapi import Depends, FastAPI, HTTPException
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class InternalError(Exception):
- pass
-
-
-def get_username():
- try:
- yield "Rick"
- except InternalError:
- print("Oops, we didn't raise again, Britney 😱")
-
-
-@app.get("/items/{item_id}")
-def get_item(item_id: str, username: Annotated[str, Depends(get_username)]):
- if item_id == "portal-gun":
- raise InternalError(
- f"The portal gun is too dangerous to be owned by {username}"
- )
- if item_id != "plumbus":
- raise HTTPException(
- status_code=404, detail="Item not found, there's only a plumbus here"
- )
- return item_id
diff --git a/docs_src/dependencies/tutorial008c.py b/docs_src/dependencies/tutorial008c_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial008c.py
rename to docs_src/dependencies/tutorial008c_py39.py
diff --git a/docs_src/dependencies/tutorial008d_an.py b/docs_src/dependencies/tutorial008d_an.py
deleted file mode 100644
index c35424574..000000000
--- a/docs_src/dependencies/tutorial008d_an.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from fastapi import Depends, FastAPI, HTTPException
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class InternalError(Exception):
- pass
-
-
-def get_username():
- try:
- yield "Rick"
- except InternalError:
- print("We don't swallow the internal error here, we raise again 😎")
- raise
-
-
-@app.get("/items/{item_id}")
-def get_item(item_id: str, username: Annotated[str, Depends(get_username)]):
- if item_id == "portal-gun":
- raise InternalError(
- f"The portal gun is too dangerous to be owned by {username}"
- )
- if item_id != "plumbus":
- raise HTTPException(
- status_code=404, detail="Item not found, there's only a plumbus here"
- )
- return item_id
diff --git a/docs_src/dependencies/tutorial008d.py b/docs_src/dependencies/tutorial008d_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial008d.py
rename to docs_src/dependencies/tutorial008d_py39.py
diff --git a/docs_src/dependencies/tutorial008e_an_py39.py b/docs_src/dependencies/tutorial008e_an_py39.py
new file mode 100644
index 000000000..80a44c7e2
--- /dev/null
+++ b/docs_src/dependencies/tutorial008e_an_py39.py
@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+app = FastAPI()
+
+
+def get_username():
+ try:
+ yield "Rick"
+ finally:
+ print("Cleanup up before response is sent")
+
+
+@app.get("/users/me")
+def get_user_me(username: Annotated[str, Depends(get_username, scope="function")]):
+ return username
diff --git a/docs_src/dependencies/tutorial008e_py39.py b/docs_src/dependencies/tutorial008e_py39.py
new file mode 100644
index 000000000..1ed056e91
--- /dev/null
+++ b/docs_src/dependencies/tutorial008e_py39.py
@@ -0,0 +1,15 @@
+from fastapi import Depends, FastAPI
+
+app = FastAPI()
+
+
+def get_username():
+ try:
+ yield "Rick"
+ finally:
+ print("Cleanup up before response is sent")
+
+
+@app.get("/users/me")
+def get_user_me(username: str = Depends(get_username, scope="function")):
+ return username
diff --git a/docs_src/dependencies/tutorial009.py b/docs_src/dependencies/tutorial009.py
deleted file mode 100644
index 8472f642d..000000000
--- a/docs_src/dependencies/tutorial009.py
+++ /dev/null
@@ -1,25 +0,0 @@
-from fastapi import Depends
-
-
-async def dependency_a():
- dep_a = generate_dep_a()
- try:
- yield dep_a
- finally:
- dep_a.close()
-
-
-async def dependency_b(dep_a=Depends(dependency_a)):
- dep_b = generate_dep_b()
- try:
- yield dep_b
- finally:
- dep_b.close(dep_a)
-
-
-async def dependency_c(dep_b=Depends(dependency_b)):
- dep_c = generate_dep_c()
- try:
- yield dep_c
- finally:
- dep_c.close(dep_b)
diff --git a/docs_src/dependencies/tutorial010.py b/docs_src/dependencies/tutorial010_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial010.py
rename to docs_src/dependencies/tutorial010_py39.py
diff --git a/docs_src/dependencies/tutorial011_an.py b/docs_src/dependencies/tutorial011_an.py
deleted file mode 100644
index 6c13d9033..000000000
--- a/docs_src/dependencies/tutorial011_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class FixedContentQueryChecker:
- def __init__(self, fixed_content: str):
- self.fixed_content = fixed_content
-
- def __call__(self, q: str = ""):
- if q:
- return self.fixed_content in q
- return False
-
-
-checker = FixedContentQueryChecker("bar")
-
-
-@app.get("/query-checker/")
-async def read_query_check(fixed_content_included: Annotated[bool, Depends(checker)]):
- return {"fixed_content_in_query": fixed_content_included}
diff --git a/docs_src/dependencies/tutorial011.py b/docs_src/dependencies/tutorial011_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial011.py
rename to docs_src/dependencies/tutorial011_py39.py
diff --git a/docs_src/dependencies/tutorial012_an.py b/docs_src/dependencies/tutorial012_an.py
deleted file mode 100644
index 7541e6bf4..000000000
--- a/docs_src/dependencies/tutorial012_an.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from fastapi import Depends, FastAPI, Header, HTTPException
-from typing_extensions import Annotated
-
-
-async def verify_token(x_token: Annotated[str, Header()]):
- if x_token != "fake-super-secret-token":
- raise HTTPException(status_code=400, detail="X-Token header invalid")
-
-
-async def verify_key(x_key: Annotated[str, Header()]):
- if x_key != "fake-super-secret-key":
- raise HTTPException(status_code=400, detail="X-Key header invalid")
- return x_key
-
-
-app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])
-
-
-@app.get("/items/")
-async def read_items():
- return [{"item": "Portal Gun"}, {"item": "Plumbus"}]
-
-
-@app.get("/users/")
-async def read_users():
- return [{"username": "Rick"}, {"username": "Morty"}]
diff --git a/docs_src/dependencies/tutorial012_an_py39.py b/docs_src/dependencies/tutorial012_an_py39.py
index 7541e6bf4..6503591fc 100644
--- a/docs_src/dependencies/tutorial012_an_py39.py
+++ b/docs_src/dependencies/tutorial012_an_py39.py
@@ -1,5 +1,6 @@
+from typing import Annotated
+
from fastapi import Depends, FastAPI, Header, HTTPException
-from typing_extensions import Annotated
async def verify_token(x_token: Annotated[str, Header()]):
diff --git a/docs_src/dependencies/tutorial012.py b/docs_src/dependencies/tutorial012_py39.py
similarity index 100%
rename from docs_src/dependencies/tutorial012.py
rename to docs_src/dependencies/tutorial012_py39.py
diff --git a/docs_src/dependency_testing/__init__.py b/docs_src/dependency_testing/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/dependency_testing/tutorial001_an.py b/docs_src/dependency_testing/tutorial001_an.py
deleted file mode 100644
index 4c76a87ff..000000000
--- a/docs_src/dependency_testing/tutorial001_an.py
+++ /dev/null
@@ -1,60 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from fastapi.testclient import TestClient
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-async def common_parameters(
- q: Union[str, None] = None, skip: int = 0, limit: int = 100
-):
- return {"q": q, "skip": skip, "limit": limit}
-
-
-@app.get("/items/")
-async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
- return {"message": "Hello Items!", "params": commons}
-
-
-@app.get("/users/")
-async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
- return {"message": "Hello Users!", "params": commons}
-
-
-client = TestClient(app)
-
-
-async def override_dependency(q: Union[str, None] = None):
- return {"q": q, "skip": 5, "limit": 10}
-
-
-app.dependency_overrides[common_parameters] = override_dependency
-
-
-def test_override_in_items():
- response = client.get("/items/")
- assert response.status_code == 200
- assert response.json() == {
- "message": "Hello Items!",
- "params": {"q": None, "skip": 5, "limit": 10},
- }
-
-
-def test_override_in_items_with_q():
- response = client.get("/items/?q=foo")
- assert response.status_code == 200
- assert response.json() == {
- "message": "Hello Items!",
- "params": {"q": "foo", "skip": 5, "limit": 10},
- }
-
-
-def test_override_in_items_with_params():
- response = client.get("/items/?q=foo&skip=100&limit=200")
- assert response.status_code == 200
- assert response.json() == {
- "message": "Hello Items!",
- "params": {"q": "foo", "skip": 5, "limit": 10},
- }
diff --git a/docs_src/dependency_testing/tutorial001.py b/docs_src/dependency_testing/tutorial001_py39.py
similarity index 100%
rename from docs_src/dependency_testing/tutorial001.py
rename to docs_src/dependency_testing/tutorial001_py39.py
diff --git a/docs_src/encoder/__init__.py b/docs_src/encoder/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/encoder/tutorial001.py b/docs_src/encoder/tutorial001_py39.py
similarity index 100%
rename from docs_src/encoder/tutorial001.py
rename to docs_src/encoder/tutorial001_py39.py
diff --git a/docs_src/events/__init__.py b/docs_src/events/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/events/tutorial001.py b/docs_src/events/tutorial001_py39.py
similarity index 100%
rename from docs_src/events/tutorial001.py
rename to docs_src/events/tutorial001_py39.py
diff --git a/docs_src/events/tutorial002.py b/docs_src/events/tutorial002_py39.py
similarity index 100%
rename from docs_src/events/tutorial002.py
rename to docs_src/events/tutorial002_py39.py
diff --git a/docs_src/events/tutorial003.py b/docs_src/events/tutorial003_py39.py
similarity index 100%
rename from docs_src/events/tutorial003.py
rename to docs_src/events/tutorial003_py39.py
diff --git a/docs_src/extending_openapi/__init__.py b/docs_src/extending_openapi/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/extending_openapi/tutorial001.py b/docs_src/extending_openapi/tutorial001_py39.py
similarity index 100%
rename from docs_src/extending_openapi/tutorial001.py
rename to docs_src/extending_openapi/tutorial001_py39.py
diff --git a/docs_src/extra_data_types/__init__.py b/docs_src/extra_data_types/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/extra_data_types/tutorial001_an.py b/docs_src/extra_data_types/tutorial001_an.py
deleted file mode 100644
index 257d0c7c8..000000000
--- a/docs_src/extra_data_types/tutorial001_an.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from datetime import datetime, time, timedelta
-from typing import Union
-from uuid import UUID
-
-from fastapi import Body, FastAPI
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.put("/items/{item_id}")
-async def read_items(
- item_id: UUID,
- start_datetime: Annotated[datetime, Body()],
- end_datetime: Annotated[datetime, Body()],
- process_after: Annotated[timedelta, Body()],
- repeat_at: Annotated[Union[time, None], Body()] = None,
-):
- start_process = start_datetime + process_after
- duration = end_datetime - start_process
- return {
- "item_id": item_id,
- "start_datetime": start_datetime,
- "end_datetime": end_datetime,
- "process_after": process_after,
- "repeat_at": repeat_at,
- "start_process": start_process,
- "duration": duration,
- }
diff --git a/docs_src/extra_data_types/tutorial001.py b/docs_src/extra_data_types/tutorial001_py39.py
similarity index 100%
rename from docs_src/extra_data_types/tutorial001.py
rename to docs_src/extra_data_types/tutorial001_py39.py
diff --git a/docs_src/extra_models/__init__.py b/docs_src/extra_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/extra_models/tutorial001.py b/docs_src/extra_models/tutorial001.py
deleted file mode 100644
index 4be56cd2a..000000000
--- a/docs_src/extra_models/tutorial001.py
+++ /dev/null
@@ -1,43 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel, EmailStr
-
-app = FastAPI()
-
-
-class UserIn(BaseModel):
- username: str
- password: str
- email: EmailStr
- full_name: Union[str, None] = None
-
-
-class UserOut(BaseModel):
- username: str
- email: EmailStr
- full_name: Union[str, None] = None
-
-
-class UserInDB(BaseModel):
- username: str
- hashed_password: str
- email: EmailStr
- full_name: Union[str, None] = None
-
-
-def fake_password_hasher(raw_password: str):
- return "supersecret" + raw_password
-
-
-def fake_save_user(user_in: UserIn):
- hashed_password = fake_password_hasher(user_in.password)
- user_in_db = UserInDB(**user_in.dict(), hashed_password=hashed_password)
- print("User saved! ..not really")
- return user_in_db
-
-
-@app.post("/user/", response_model=UserOut)
-async def create_user(user_in: UserIn):
- user_saved = fake_save_user(user_in)
- return user_saved
diff --git a/docs_src/extra_models/tutorial001_py310.py b/docs_src/extra_models/tutorial001_py310.py
index 669386ae6..cf39142e4 100644
--- a/docs_src/extra_models/tutorial001_py310.py
+++ b/docs_src/extra_models/tutorial001_py310.py
@@ -30,7 +30,7 @@ def fake_password_hasher(raw_password: str):
def fake_save_user(user_in: UserIn):
hashed_password = fake_password_hasher(user_in.password)
- user_in_db = UserInDB(**user_in.dict(), hashed_password=hashed_password)
+ user_in_db = UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
print("User saved! ..not really")
return user_in_db
diff --git a/docs_src/extra_models/tutorial001_py39.py b/docs_src/extra_models/tutorial001_py39.py
new file mode 100644
index 000000000..327ffcdf0
--- /dev/null
+++ b/docs_src/extra_models/tutorial001_py39.py
@@ -0,0 +1,43 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel, EmailStr
+
+app = FastAPI()
+
+
+class UserIn(BaseModel):
+ username: str
+ password: str
+ email: EmailStr
+ full_name: Union[str, None] = None
+
+
+class UserOut(BaseModel):
+ username: str
+ email: EmailStr
+ full_name: Union[str, None] = None
+
+
+class UserInDB(BaseModel):
+ username: str
+ hashed_password: str
+ email: EmailStr
+ full_name: Union[str, None] = None
+
+
+def fake_password_hasher(raw_password: str):
+ return "supersecret" + raw_password
+
+
+def fake_save_user(user_in: UserIn):
+ hashed_password = fake_password_hasher(user_in.password)
+ user_in_db = UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
+ print("User saved! ..not really")
+ return user_in_db
+
+
+@app.post("/user/", response_model=UserOut)
+async def create_user(user_in: UserIn):
+ user_saved = fake_save_user(user_in)
+ return user_saved
diff --git a/docs_src/extra_models/tutorial002.py b/docs_src/extra_models/tutorial002.py
deleted file mode 100644
index 70fa16441..000000000
--- a/docs_src/extra_models/tutorial002.py
+++ /dev/null
@@ -1,41 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel, EmailStr
-
-app = FastAPI()
-
-
-class UserBase(BaseModel):
- username: str
- email: EmailStr
- full_name: Union[str, None] = None
-
-
-class UserIn(UserBase):
- password: str
-
-
-class UserOut(UserBase):
- pass
-
-
-class UserInDB(UserBase):
- hashed_password: str
-
-
-def fake_password_hasher(raw_password: str):
- return "supersecret" + raw_password
-
-
-def fake_save_user(user_in: UserIn):
- hashed_password = fake_password_hasher(user_in.password)
- user_in_db = UserInDB(**user_in.dict(), hashed_password=hashed_password)
- print("User saved! ..not really")
- return user_in_db
-
-
-@app.post("/user/", response_model=UserOut)
-async def create_user(user_in: UserIn):
- user_saved = fake_save_user(user_in)
- return user_saved
diff --git a/docs_src/extra_models/tutorial002_py310.py b/docs_src/extra_models/tutorial002_py310.py
index 5b8ed7de3..e8a4f5f29 100644
--- a/docs_src/extra_models/tutorial002_py310.py
+++ b/docs_src/extra_models/tutorial002_py310.py
@@ -28,7 +28,7 @@ def fake_password_hasher(raw_password: str):
def fake_save_user(user_in: UserIn):
hashed_password = fake_password_hasher(user_in.password)
- user_in_db = UserInDB(**user_in.dict(), hashed_password=hashed_password)
+ user_in_db = UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
print("User saved! ..not really")
return user_in_db
diff --git a/docs_src/extra_models/tutorial002_py39.py b/docs_src/extra_models/tutorial002_py39.py
new file mode 100644
index 000000000..654379601
--- /dev/null
+++ b/docs_src/extra_models/tutorial002_py39.py
@@ -0,0 +1,41 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel, EmailStr
+
+app = FastAPI()
+
+
+class UserBase(BaseModel):
+ username: str
+ email: EmailStr
+ full_name: Union[str, None] = None
+
+
+class UserIn(UserBase):
+ password: str
+
+
+class UserOut(UserBase):
+ pass
+
+
+class UserInDB(UserBase):
+ hashed_password: str
+
+
+def fake_password_hasher(raw_password: str):
+ return "supersecret" + raw_password
+
+
+def fake_save_user(user_in: UserIn):
+ hashed_password = fake_password_hasher(user_in.password)
+ user_in_db = UserInDB(**user_in.model_dump(), hashed_password=hashed_password)
+ print("User saved! ..not really")
+ return user_in_db
+
+
+@app.post("/user/", response_model=UserOut)
+async def create_user(user_in: UserIn):
+ user_saved = fake_save_user(user_in)
+ return user_saved
diff --git a/docs_src/extra_models/tutorial003.py b/docs_src/extra_models/tutorial003_py39.py
similarity index 100%
rename from docs_src/extra_models/tutorial003.py
rename to docs_src/extra_models/tutorial003_py39.py
diff --git a/docs_src/extra_models/tutorial004.py b/docs_src/extra_models/tutorial004.py
deleted file mode 100644
index a8e0f7af5..000000000
--- a/docs_src/extra_models/tutorial004.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: str
-
-
-items = [
- {"name": "Foo", "description": "There comes my hero"},
- {"name": "Red", "description": "It's my aeroplane"},
-]
-
-
-@app.get("/items/", response_model=List[Item])
-async def read_items():
- return items
diff --git a/docs_src/extra_models/tutorial005.py b/docs_src/extra_models/tutorial005.py
deleted file mode 100644
index a81cbc2c5..000000000
--- a/docs_src/extra_models/tutorial005.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from typing import Dict
-
-from fastapi import FastAPI
-
-app = FastAPI()
-
-
-@app.get("/keyword-weights/", response_model=Dict[str, float])
-async def read_keyword_weights():
- return {"foo": 2.3, "bar": 3.4}
diff --git a/docs_src/first_steps/__init__.py b/docs_src/first_steps/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/first_steps/tutorial001.py b/docs_src/first_steps/tutorial001_py39.py
similarity index 100%
rename from docs_src/first_steps/tutorial001.py
rename to docs_src/first_steps/tutorial001_py39.py
diff --git a/docs_src/first_steps/tutorial002.py b/docs_src/first_steps/tutorial002.py
deleted file mode 100644
index ca7d48cff..000000000
--- a/docs_src/first_steps/tutorial002.py
+++ /dev/null
@@ -1,8 +0,0 @@
-from fastapi import FastAPI
-
-my_awesome_api = FastAPI()
-
-
-@my_awesome_api.get("/")
-async def root():
- return {"message": "Hello World"}
diff --git a/docs_src/first_steps/tutorial003.py b/docs_src/first_steps/tutorial003_py39.py
similarity index 100%
rename from docs_src/first_steps/tutorial003.py
rename to docs_src/first_steps/tutorial003_py39.py
diff --git a/docs_src/generate_clients/__init__.py b/docs_src/generate_clients/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/generate_clients/tutorial001.py b/docs_src/generate_clients/tutorial001.py
deleted file mode 100644
index 2d1f91bc6..000000000
--- a/docs_src/generate_clients/tutorial001.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- price: float
-
-
-class ResponseMessage(BaseModel):
- message: str
-
-
-@app.post("/items/", response_model=ResponseMessage)
-async def create_item(item: Item):
- return {"message": "item received"}
-
-
-@app.get("/items/", response_model=List[Item])
-async def get_items():
- return [
- {"name": "Plumbus", "price": 3},
- {"name": "Portal Gun", "price": 9001},
- ]
diff --git a/docs_src/generate_clients/tutorial002.py b/docs_src/generate_clients/tutorial002.py
deleted file mode 100644
index bd80449af..000000000
--- a/docs_src/generate_clients/tutorial002.py
+++ /dev/null
@@ -1,38 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- price: float
-
-
-class ResponseMessage(BaseModel):
- message: str
-
-
-class User(BaseModel):
- username: str
- email: str
-
-
-@app.post("/items/", response_model=ResponseMessage, tags=["items"])
-async def create_item(item: Item):
- return {"message": "Item received"}
-
-
-@app.get("/items/", response_model=List[Item], tags=["items"])
-async def get_items():
- return [
- {"name": "Plumbus", "price": 3},
- {"name": "Portal Gun", "price": 9001},
- ]
-
-
-@app.post("/users/", response_model=ResponseMessage, tags=["users"])
-async def create_user(user: User):
- return {"message": "User received"}
diff --git a/docs_src/generate_clients/tutorial003.py b/docs_src/generate_clients/tutorial003.py
deleted file mode 100644
index 49eab73a1..000000000
--- a/docs_src/generate_clients/tutorial003.py
+++ /dev/null
@@ -1,44 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI
-from fastapi.routing import APIRoute
-from pydantic import BaseModel
-
-
-def custom_generate_unique_id(route: APIRoute):
- return f"{route.tags[0]}-{route.name}"
-
-
-app = FastAPI(generate_unique_id_function=custom_generate_unique_id)
-
-
-class Item(BaseModel):
- name: str
- price: float
-
-
-class ResponseMessage(BaseModel):
- message: str
-
-
-class User(BaseModel):
- username: str
- email: str
-
-
-@app.post("/items/", response_model=ResponseMessage, tags=["items"])
-async def create_item(item: Item):
- return {"message": "Item received"}
-
-
-@app.get("/items/", response_model=List[Item], tags=["items"])
-async def get_items():
- return [
- {"name": "Plumbus", "price": 3},
- {"name": "Portal Gun", "price": 9001},
- ]
-
-
-@app.post("/users/", response_model=ResponseMessage, tags=["users"])
-async def create_user(user: User):
- return {"message": "User received"}
diff --git a/docs_src/generate_clients/tutorial004.py b/docs_src/generate_clients/tutorial004_py39.py
similarity index 100%
rename from docs_src/generate_clients/tutorial004.py
rename to docs_src/generate_clients/tutorial004_py39.py
diff --git a/docs_src/graphql_/__init__.py b/docs_src/graphql_/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/graphql/tutorial001.py b/docs_src/graphql_/tutorial001_py39.py
similarity index 100%
rename from docs_src/graphql/tutorial001.py
rename to docs_src/graphql_/tutorial001_py39.py
diff --git a/docs_src/handling_errors/__init__.py b/docs_src/handling_errors/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/handling_errors/tutorial001.py b/docs_src/handling_errors/tutorial001_py39.py
similarity index 100%
rename from docs_src/handling_errors/tutorial001.py
rename to docs_src/handling_errors/tutorial001_py39.py
diff --git a/docs_src/handling_errors/tutorial002.py b/docs_src/handling_errors/tutorial002_py39.py
similarity index 100%
rename from docs_src/handling_errors/tutorial002.py
rename to docs_src/handling_errors/tutorial002_py39.py
diff --git a/docs_src/handling_errors/tutorial003.py b/docs_src/handling_errors/tutorial003_py39.py
similarity index 100%
rename from docs_src/handling_errors/tutorial003.py
rename to docs_src/handling_errors/tutorial003_py39.py
diff --git a/docs_src/handling_errors/tutorial004.py b/docs_src/handling_errors/tutorial004.py
deleted file mode 100644
index 300a3834f..000000000
--- a/docs_src/handling_errors/tutorial004.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from fastapi import FastAPI, HTTPException
-from fastapi.exceptions import RequestValidationError
-from fastapi.responses import PlainTextResponse
-from starlette.exceptions import HTTPException as StarletteHTTPException
-
-app = FastAPI()
-
-
-@app.exception_handler(StarletteHTTPException)
-async def http_exception_handler(request, exc):
- return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
-
-
-@app.exception_handler(RequestValidationError)
-async def validation_exception_handler(request, exc):
- return PlainTextResponse(str(exc), status_code=400)
-
-
-@app.get("/items/{item_id}")
-async def read_item(item_id: int):
- if item_id == 3:
- raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
- return {"item_id": item_id}
diff --git a/docs_src/handling_errors/tutorial004_py39.py b/docs_src/handling_errors/tutorial004_py39.py
new file mode 100644
index 000000000..ae50807e9
--- /dev/null
+++ b/docs_src/handling_errors/tutorial004_py39.py
@@ -0,0 +1,26 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import PlainTextResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+app = FastAPI()
+
+
+@app.exception_handler(StarletteHTTPException)
+async def http_exception_handler(request, exc):
+ return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request, exc: RequestValidationError):
+ message = "Validation errors:"
+ for error in exc.errors():
+ message += f"\nField: {error['loc']}, Error: {error['msg']}"
+ return PlainTextResponse(message, status_code=400)
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int):
+ if item_id == 3:
+ raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
+ return {"item_id": item_id}
diff --git a/docs_src/handling_errors/tutorial005.py b/docs_src/handling_errors/tutorial005_py39.py
similarity index 100%
rename from docs_src/handling_errors/tutorial005.py
rename to docs_src/handling_errors/tutorial005_py39.py
diff --git a/docs_src/handling_errors/tutorial006.py b/docs_src/handling_errors/tutorial006_py39.py
similarity index 100%
rename from docs_src/handling_errors/tutorial006.py
rename to docs_src/handling_errors/tutorial006_py39.py
diff --git a/docs_src/header_param_models/__init__.py b/docs_src/header_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/header_param_models/tutorial001.py b/docs_src/header_param_models/tutorial001.py
deleted file mode 100644
index 4caaba87b..000000000
--- a/docs_src/header_param_models/tutorial001.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header()):
- return headers
diff --git a/docs_src/header_param_models/tutorial001_an.py b/docs_src/header_param_models/tutorial001_an.py
deleted file mode 100644
index b55c6b56b..000000000
--- a/docs_src/header_param_models/tutorial001_an.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: Annotated[CommonHeaders, Header()]):
- return headers
diff --git a/docs_src/header_param_models/tutorial002.py b/docs_src/header_param_models/tutorial002.py
deleted file mode 100644
index 3f9aac58d..000000000
--- a/docs_src/header_param_models/tutorial002.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- model_config = {"extra": "forbid"}
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header()):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_an.py b/docs_src/header_param_models/tutorial002_an.py
deleted file mode 100644
index 771135d77..000000000
--- a/docs_src/header_param_models/tutorial002_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- model_config = {"extra": "forbid"}
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: Annotated[CommonHeaders, Header()]):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1.py b/docs_src/header_param_models/tutorial002_pv1.py
deleted file mode 100644
index 7e56cd993..000000000
--- a/docs_src/header_param_models/tutorial002_pv1.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header()):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an.py b/docs_src/header_param_models/tutorial002_pv1_an.py
deleted file mode 100644
index 236778231..000000000
--- a/docs_src/header_param_models/tutorial002_pv1_an.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: Annotated[CommonHeaders, Header()]):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an_py310.py b/docs_src/header_param_models/tutorial002_pv1_an_py310.py
deleted file mode 100644
index e99e24ea5..000000000
--- a/docs_src/header_param_models/tutorial002_pv1_an_py310.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Annotated
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: str | None = None
- traceparent: str | None = None
- x_tag: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: Annotated[CommonHeaders, Header()]):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an_py39.py b/docs_src/header_param_models/tutorial002_pv1_an_py39.py
deleted file mode 100644
index 18398b726..000000000
--- a/docs_src/header_param_models/tutorial002_pv1_an_py39.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Annotated, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: Annotated[CommonHeaders, Header()]):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_py310.py b/docs_src/header_param_models/tutorial002_pv1_py310.py
deleted file mode 100644
index 3dbff9d7b..000000000
--- a/docs_src/header_param_models/tutorial002_pv1_py310.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: str | None = None
- traceparent: str | None = None
- x_tag: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header()):
- return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_py39.py b/docs_src/header_param_models/tutorial002_pv1_py39.py
deleted file mode 100644
index 86e19be0d..000000000
--- a/docs_src/header_param_models/tutorial002_pv1_py39.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- class Config:
- extra = "forbid"
-
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header()):
- return headers
diff --git a/docs_src/header_param_models/tutorial003.py b/docs_src/header_param_models/tutorial003.py
deleted file mode 100644
index dc2eb74bd..000000000
--- a/docs_src/header_param_models/tutorial003.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
- return headers
diff --git a/docs_src/header_param_models/tutorial003_an.py b/docs_src/header_param_models/tutorial003_an.py
deleted file mode 100644
index e3edb1189..000000000
--- a/docs_src/header_param_models/tutorial003_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class CommonHeaders(BaseModel):
- host: str
- save_data: bool
- if_modified_since: Union[str, None] = None
- traceparent: Union[str, None] = None
- x_tag: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(
- headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
-):
- return headers
diff --git a/docs_src/header_params/__init__.py b/docs_src/header_params/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/header_params/tutorial001_an.py b/docs_src/header_params/tutorial001_an.py
deleted file mode 100644
index 816c00086..000000000
--- a/docs_src/header_params/tutorial001_an.py
+++ /dev/null
@@ -1,11 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Header
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(user_agent: Annotated[Union[str, None], Header()] = None):
- return {"User-Agent": user_agent}
diff --git a/docs_src/header_params/tutorial001.py b/docs_src/header_params/tutorial001_py39.py
similarity index 100%
rename from docs_src/header_params/tutorial001.py
rename to docs_src/header_params/tutorial001_py39.py
diff --git a/docs_src/header_params/tutorial002_an.py b/docs_src/header_params/tutorial002_an.py
deleted file mode 100644
index 82fe49ba2..000000000
--- a/docs_src/header_params/tutorial002_an.py
+++ /dev/null
@@ -1,15 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Header
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- strange_header: Annotated[
- Union[str, None], Header(convert_underscores=False)
- ] = None,
-):
- return {"strange_header": strange_header}
diff --git a/docs_src/header_params/tutorial002.py b/docs_src/header_params/tutorial002_py39.py
similarity index 100%
rename from docs_src/header_params/tutorial002.py
rename to docs_src/header_params/tutorial002_py39.py
diff --git a/docs_src/header_params/tutorial003.py b/docs_src/header_params/tutorial003.py
deleted file mode 100644
index a61314aed..000000000
--- a/docs_src/header_params/tutorial003.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(x_token: Union[List[str], None] = Header(default=None)):
- return {"X-Token values": x_token}
diff --git a/docs_src/header_params/tutorial003_an.py b/docs_src/header_params/tutorial003_an.py
deleted file mode 100644
index 5406fd1f8..000000000
--- a/docs_src/header_params/tutorial003_an.py
+++ /dev/null
@@ -1,11 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Header
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
- return {"X-Token values": x_token}
diff --git a/docs_src/header_params/tutorial003_an_py39.py b/docs_src/header_params/tutorial003_an_py39.py
index c1dd49961..5aad89407 100644
--- a/docs_src/header_params/tutorial003_an_py39.py
+++ b/docs_src/header_params/tutorial003_an_py39.py
@@ -1,4 +1,4 @@
-from typing import Annotated, List, Union
+from typing import Annotated, Union
from fastapi import FastAPI, Header
@@ -6,5 +6,5 @@ app = FastAPI()
@app.get("/items/")
-async def read_items(x_token: Annotated[Union[List[str], None], Header()] = None):
+async def read_items(x_token: Annotated[Union[list[str], None], Header()] = None):
return {"X-Token values": x_token}
diff --git a/docs_src/metadata/__init__.py b/docs_src/metadata/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/metadata/tutorial001_1.py b/docs_src/metadata/tutorial001_1_py39.py
similarity index 100%
rename from docs_src/metadata/tutorial001_1.py
rename to docs_src/metadata/tutorial001_1_py39.py
diff --git a/docs_src/metadata/tutorial001.py b/docs_src/metadata/tutorial001_py39.py
similarity index 100%
rename from docs_src/metadata/tutorial001.py
rename to docs_src/metadata/tutorial001_py39.py
diff --git a/docs_src/metadata/tutorial002.py b/docs_src/metadata/tutorial002_py39.py
similarity index 100%
rename from docs_src/metadata/tutorial002.py
rename to docs_src/metadata/tutorial002_py39.py
diff --git a/docs_src/metadata/tutorial003.py b/docs_src/metadata/tutorial003_py39.py
similarity index 100%
rename from docs_src/metadata/tutorial003.py
rename to docs_src/metadata/tutorial003_py39.py
diff --git a/docs_src/metadata/tutorial004.py b/docs_src/metadata/tutorial004_py39.py
similarity index 100%
rename from docs_src/metadata/tutorial004.py
rename to docs_src/metadata/tutorial004_py39.py
diff --git a/docs_src/middleware/__init__.py b/docs_src/middleware/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/middleware/tutorial001.py b/docs_src/middleware/tutorial001_py39.py
similarity index 100%
rename from docs_src/middleware/tutorial001.py
rename to docs_src/middleware/tutorial001_py39.py
diff --git a/docs_src/openapi_callbacks/__init__.py b/docs_src/openapi_callbacks/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/openapi_callbacks/tutorial001_py310.py b/docs_src/openapi_callbacks/tutorial001_py310.py
new file mode 100644
index 000000000..3efe0ee25
--- /dev/null
+++ b/docs_src/openapi_callbacks/tutorial001_py310.py
@@ -0,0 +1,51 @@
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel, HttpUrl
+
+app = FastAPI()
+
+
+class Invoice(BaseModel):
+ id: str
+ title: str | None = None
+ customer: str
+ total: float
+
+
+class InvoiceEvent(BaseModel):
+ description: str
+ paid: bool
+
+
+class InvoiceEventReceived(BaseModel):
+ ok: bool
+
+
+invoices_callback_router = APIRouter()
+
+
+@invoices_callback_router.post(
+ "{$callback_url}/invoices/{$request.body.id}", response_model=InvoiceEventReceived
+)
+def invoice_notification(body: InvoiceEvent):
+ pass
+
+
+@app.post("/invoices/", callbacks=invoices_callback_router.routes)
+def create_invoice(invoice: Invoice, callback_url: HttpUrl | None = None):
+ """
+ Create an invoice.
+
+ This will (let's imagine) let the API user (some external developer) create an
+ invoice.
+
+ And this path operation will:
+
+ * Send the invoice to the client.
+ * Collect the money from the client.
+ * Send a notification back to the API user (the external developer), as a callback.
+ * At this point is that the API will somehow send a POST request to the
+ external API with the notification of the invoice event
+ (e.g. "payment successful").
+ """
+ # Send the invoice, collect the money, send the notification (the callback)
+ return {"msg": "Invoice received"}
diff --git a/docs_src/openapi_callbacks/tutorial001.py b/docs_src/openapi_callbacks/tutorial001_py39.py
similarity index 100%
rename from docs_src/openapi_callbacks/tutorial001.py
rename to docs_src/openapi_callbacks/tutorial001_py39.py
diff --git a/docs_src/openapi_webhooks/__init__.py b/docs_src/openapi_webhooks/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/openapi_webhooks/tutorial001.py b/docs_src/openapi_webhooks/tutorial001_py39.py
similarity index 100%
rename from docs_src/openapi_webhooks/tutorial001.py
rename to docs_src/openapi_webhooks/tutorial001_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/__init__.py b/docs_src/path_operation_advanced_configuration/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/path_operation_advanced_configuration/tutorial001.py b/docs_src/path_operation_advanced_configuration/tutorial001_py39.py
similarity index 100%
rename from docs_src/path_operation_advanced_configuration/tutorial001.py
rename to docs_src/path_operation_advanced_configuration/tutorial001_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/tutorial002.py b/docs_src/path_operation_advanced_configuration/tutorial002_py39.py
similarity index 100%
rename from docs_src/path_operation_advanced_configuration/tutorial002.py
rename to docs_src/path_operation_advanced_configuration/tutorial002_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/tutorial003.py b/docs_src/path_operation_advanced_configuration/tutorial003_py39.py
similarity index 100%
rename from docs_src/path_operation_advanced_configuration/tutorial003.py
rename to docs_src/path_operation_advanced_configuration/tutorial003_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/tutorial004.py b/docs_src/path_operation_advanced_configuration/tutorial004.py
deleted file mode 100644
index a3aad4ac4..000000000
--- a/docs_src/path_operation_advanced_configuration/tutorial004.py
+++ /dev/null
@@ -1,30 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post("/items/", response_model=Item, summary="Create an item")
-async def create_item(item: Item):
- """
- Create an item with all the information:
-
- - **name**: each item must have a name
- - **description**: a long description
- - **price**: required
- - **tax**: if the item doesn't have tax, you can omit this
- - **tags**: a set of unique tag strings for this item
- \f
- :param item: User input.
- """
- return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial004_py310.py b/docs_src/path_operation_advanced_configuration/tutorial004_py310.py
new file mode 100644
index 000000000..a815a564b
--- /dev/null
+++ b/docs_src/path_operation_advanced_configuration/tutorial004_py310.py
@@ -0,0 +1,28 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+ price: float
+ tax: float | None = None
+ tags: set[str] = set()
+
+
+@app.post("/items/", response_model=Item, summary="Create an item")
+async def create_item(item: Item):
+ """
+ Create an item with all the information:
+
+ - **name**: each item must have a name
+ - **description**: a long description
+ - **price**: required
+ - **tax**: if the item doesn't have tax, you can omit this
+ - **tags**: a set of unique tag strings for this item
+ \f
+ :param item: User input.
+ """
+ return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial004_py39.py b/docs_src/path_operation_advanced_configuration/tutorial004_py39.py
new file mode 100644
index 000000000..d5fe6705c
--- /dev/null
+++ b/docs_src/path_operation_advanced_configuration/tutorial004_py39.py
@@ -0,0 +1,30 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ price: float
+ tax: Union[float, None] = None
+ tags: set[str] = set()
+
+
+@app.post("/items/", response_model=Item, summary="Create an item")
+async def create_item(item: Item):
+ """
+ Create an item with all the information:
+
+ - **name**: each item must have a name
+ - **description**: a long description
+ - **price**: required
+ - **tax**: if the item doesn't have tax, you can omit this
+ - **tags**: a set of unique tag strings for this item
+ \f
+ :param item: User input.
+ """
+ return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial005.py b/docs_src/path_operation_advanced_configuration/tutorial005_py39.py
similarity index 100%
rename from docs_src/path_operation_advanced_configuration/tutorial005.py
rename to docs_src/path_operation_advanced_configuration/tutorial005_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/tutorial006.py b/docs_src/path_operation_advanced_configuration/tutorial006_py39.py
similarity index 100%
rename from docs_src/path_operation_advanced_configuration/tutorial006.py
rename to docs_src/path_operation_advanced_configuration/tutorial006_py39.py
diff --git a/docs_src/path_operation_advanced_configuration/tutorial007.py b/docs_src/path_operation_advanced_configuration/tutorial007.py
deleted file mode 100644
index 54e2e9399..000000000
--- a/docs_src/path_operation_advanced_configuration/tutorial007.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from typing import List
-
-import yaml
-from fastapi import FastAPI, HTTPException, Request
-from pydantic import BaseModel, ValidationError
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- tags: List[str]
-
-
-@app.post(
- "/items/",
- openapi_extra={
- "requestBody": {
- "content": {"application/x-yaml": {"schema": Item.model_json_schema()}},
- "required": True,
- },
- },
-)
-async def create_item(request: Request):
- raw_body = await request.body()
- try:
- data = yaml.safe_load(raw_body)
- except yaml.YAMLError:
- raise HTTPException(status_code=422, detail="Invalid YAML")
- try:
- item = Item.model_validate(data)
- except ValidationError as e:
- raise HTTPException(status_code=422, detail=e.errors(include_url=False))
- return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial007_pv1.py b/docs_src/path_operation_advanced_configuration/tutorial007_pv1.py
deleted file mode 100644
index d51752bb8..000000000
--- a/docs_src/path_operation_advanced_configuration/tutorial007_pv1.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from typing import List
-
-import yaml
-from fastapi import FastAPI, HTTPException, Request
-from pydantic import BaseModel, ValidationError
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- tags: List[str]
-
-
-@app.post(
- "/items/",
- openapi_extra={
- "requestBody": {
- "content": {"application/x-yaml": {"schema": Item.schema()}},
- "required": True,
- },
- },
-)
-async def create_item(request: Request):
- raw_body = await request.body()
- try:
- data = yaml.safe_load(raw_body)
- except yaml.YAMLError:
- raise HTTPException(status_code=422, detail="Invalid YAML")
- try:
- item = Item.parse_obj(data)
- except ValidationError as e:
- raise HTTPException(status_code=422, detail=e.errors())
- return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py b/docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py
new file mode 100644
index 000000000..849f648e1
--- /dev/null
+++ b/docs_src/path_operation_advanced_configuration/tutorial007_pv1_py39.py
@@ -0,0 +1,32 @@
+import yaml
+from fastapi import FastAPI, HTTPException, Request
+from pydantic.v1 import BaseModel, ValidationError
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ tags: list[str]
+
+
+@app.post(
+ "/items/",
+ openapi_extra={
+ "requestBody": {
+ "content": {"application/x-yaml": {"schema": Item.schema()}},
+ "required": True,
+ },
+ },
+)
+async def create_item(request: Request):
+ raw_body = await request.body()
+ try:
+ data = yaml.safe_load(raw_body)
+ except yaml.YAMLError:
+ raise HTTPException(status_code=422, detail="Invalid YAML")
+ try:
+ item = Item.parse_obj(data)
+ except ValidationError as e:
+ raise HTTPException(status_code=422, detail=e.errors())
+ return item
diff --git a/docs_src/path_operation_advanced_configuration/tutorial007_py39.py b/docs_src/path_operation_advanced_configuration/tutorial007_py39.py
new file mode 100644
index 000000000..ff64ef792
--- /dev/null
+++ b/docs_src/path_operation_advanced_configuration/tutorial007_py39.py
@@ -0,0 +1,32 @@
+import yaml
+from fastapi import FastAPI, HTTPException, Request
+from pydantic import BaseModel, ValidationError
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ tags: list[str]
+
+
+@app.post(
+ "/items/",
+ openapi_extra={
+ "requestBody": {
+ "content": {"application/x-yaml": {"schema": Item.model_json_schema()}},
+ "required": True,
+ },
+ },
+)
+async def create_item(request: Request):
+ raw_body = await request.body()
+ try:
+ data = yaml.safe_load(raw_body)
+ except yaml.YAMLError:
+ raise HTTPException(status_code=422, detail="Invalid YAML")
+ try:
+ item = Item.model_validate(data)
+ except ValidationError as e:
+ raise HTTPException(status_code=422, detail=e.errors(include_url=False))
+ return item
diff --git a/docs_src/path_operation_configuration/__init__.py b/docs_src/path_operation_configuration/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/path_operation_configuration/tutorial001.py b/docs_src/path_operation_configuration/tutorial001.py
deleted file mode 100644
index 83fd8377a..000000000
--- a/docs_src/path_operation_configuration/tutorial001.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI, status
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
-async def create_item(item: Item):
- return item
diff --git a/docs_src/path_operation_configuration/tutorial002.py b/docs_src/path_operation_configuration/tutorial002.py
deleted file mode 100644
index 798b0c231..000000000
--- a/docs_src/path_operation_configuration/tutorial002.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post("/items/", response_model=Item, tags=["items"])
-async def create_item(item: Item):
- return item
-
-
-@app.get("/items/", tags=["items"])
-async def read_items():
- return [{"name": "Foo", "price": 42}]
-
-
-@app.get("/users/", tags=["users"])
-async def read_users():
- return [{"username": "johndoe"}]
diff --git a/docs_src/path_operation_configuration/tutorial002b.py b/docs_src/path_operation_configuration/tutorial002b_py39.py
similarity index 100%
rename from docs_src/path_operation_configuration/tutorial002b.py
rename to docs_src/path_operation_configuration/tutorial002b_py39.py
diff --git a/docs_src/path_operation_configuration/tutorial003.py b/docs_src/path_operation_configuration/tutorial003.py
deleted file mode 100644
index 26bf7daba..000000000
--- a/docs_src/path_operation_configuration/tutorial003.py
+++ /dev/null
@@ -1,24 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post(
- "/items/",
- response_model=Item,
- summary="Create an item",
- description="Create an item with all the information, name, description, price, tax and a set of unique tags",
-)
-async def create_item(item: Item):
- return item
diff --git a/docs_src/path_operation_configuration/tutorial004.py b/docs_src/path_operation_configuration/tutorial004.py
deleted file mode 100644
index 8f865c58a..000000000
--- a/docs_src/path_operation_configuration/tutorial004.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post("/items/", response_model=Item, summary="Create an item")
-async def create_item(item: Item):
- """
- Create an item with all the information:
-
- - **name**: each item must have a name
- - **description**: a long description
- - **price**: required
- - **tax**: if the item doesn't have tax, you can omit this
- - **tags**: a set of unique tag strings for this item
- """
- return item
diff --git a/docs_src/path_operation_configuration/tutorial005.py b/docs_src/path_operation_configuration/tutorial005.py
deleted file mode 100644
index 2c1be4a34..000000000
--- a/docs_src/path_operation_configuration/tutorial005.py
+++ /dev/null
@@ -1,33 +0,0 @@
-from typing import Set, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: Set[str] = set()
-
-
-@app.post(
- "/items/",
- response_model=Item,
- summary="Create an item",
- response_description="The created item",
-)
-async def create_item(item: Item):
- """
- Create an item with all the information:
-
- - **name**: each item must have a name
- - **description**: a long description
- - **price**: required
- - **tax**: if the item doesn't have tax, you can omit this
- - **tags**: a set of unique tag strings for this item
- """
- return item
diff --git a/docs_src/path_operation_configuration/tutorial006.py b/docs_src/path_operation_configuration/tutorial006_py39.py
similarity index 100%
rename from docs_src/path_operation_configuration/tutorial006.py
rename to docs_src/path_operation_configuration/tutorial006_py39.py
diff --git a/docs_src/path_params/__init__.py b/docs_src/path_params/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/path_params/tutorial001.py b/docs_src/path_params/tutorial001_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial001.py
rename to docs_src/path_params/tutorial001_py39.py
diff --git a/docs_src/path_params/tutorial002.py b/docs_src/path_params/tutorial002_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial002.py
rename to docs_src/path_params/tutorial002_py39.py
diff --git a/docs_src/path_params/tutorial003.py b/docs_src/path_params/tutorial003_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial003.py
rename to docs_src/path_params/tutorial003_py39.py
diff --git a/docs_src/path_params/tutorial003b.py b/docs_src/path_params/tutorial003b_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial003b.py
rename to docs_src/path_params/tutorial003b_py39.py
diff --git a/docs_src/path_params/tutorial004.py b/docs_src/path_params/tutorial004_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial004.py
rename to docs_src/path_params/tutorial004_py39.py
diff --git a/docs_src/path_params/tutorial005.py b/docs_src/path_params/tutorial005_py39.py
similarity index 100%
rename from docs_src/path_params/tutorial005.py
rename to docs_src/path_params/tutorial005_py39.py
diff --git a/docs_src/path_params_numeric_validations/__init__.py b/docs_src/path_params_numeric_validations/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/path_params_numeric_validations/tutorial001_an.py b/docs_src/path_params_numeric_validations/tutorial001_an.py
deleted file mode 100644
index 621be7b04..000000000
--- a/docs_src/path_params_numeric_validations/tutorial001_an.py
+++ /dev/null
@@ -1,17 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Path, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- item_id: Annotated[int, Path(title="The ID of the item to get")],
- q: Annotated[Union[str, None], Query(alias="item-query")] = None,
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial001.py b/docs_src/path_params_numeric_validations/tutorial001_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial001.py
rename to docs_src/path_params_numeric_validations/tutorial001_py39.py
diff --git a/docs_src/path_params_numeric_validations/tutorial002_an.py b/docs_src/path_params_numeric_validations/tutorial002_an.py
deleted file mode 100644
index 322f8cf0b..000000000
--- a/docs_src/path_params_numeric_validations/tutorial002_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from fastapi import FastAPI, Path
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial002.py b/docs_src/path_params_numeric_validations/tutorial002_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial002.py
rename to docs_src/path_params_numeric_validations/tutorial002_py39.py
diff --git a/docs_src/path_params_numeric_validations/tutorial003_an.py b/docs_src/path_params_numeric_validations/tutorial003_an.py
deleted file mode 100644
index d0fa8b3db..000000000
--- a/docs_src/path_params_numeric_validations/tutorial003_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from fastapi import FastAPI, Path
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial003.py b/docs_src/path_params_numeric_validations/tutorial003_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial003.py
rename to docs_src/path_params_numeric_validations/tutorial003_py39.py
diff --git a/docs_src/path_params_numeric_validations/tutorial004_an.py b/docs_src/path_params_numeric_validations/tutorial004_an.py
deleted file mode 100644
index ffc50f6c5..000000000
--- a/docs_src/path_params_numeric_validations/tutorial004_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from fastapi import FastAPI, Path
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- item_id: Annotated[int, Path(title="The ID of the item to get", ge=1)], q: str
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial004.py b/docs_src/path_params_numeric_validations/tutorial004_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial004.py
rename to docs_src/path_params_numeric_validations/tutorial004_py39.py
diff --git a/docs_src/path_params_numeric_validations/tutorial005_an.py b/docs_src/path_params_numeric_validations/tutorial005_an.py
deleted file mode 100644
index 433c69129..000000000
--- a/docs_src/path_params_numeric_validations/tutorial005_an.py
+++ /dev/null
@@ -1,15 +0,0 @@
-from fastapi import FastAPI, Path
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- item_id: Annotated[int, Path(title="The ID of the item to get", gt=0, le=1000)],
- q: str,
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial005.py b/docs_src/path_params_numeric_validations/tutorial005_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial005.py
rename to docs_src/path_params_numeric_validations/tutorial005_py39.py
diff --git a/docs_src/path_params_numeric_validations/tutorial006_an.py b/docs_src/path_params_numeric_validations/tutorial006_an.py
deleted file mode 100644
index ac4732573..000000000
--- a/docs_src/path_params_numeric_validations/tutorial006_an.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from fastapi import FastAPI, Path, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_items(
- *,
- item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
- q: str,
- size: Annotated[float, Query(gt=0, lt=10.5)],
-):
- results = {"item_id": item_id}
- if q:
- results.update({"q": q})
- if size:
- results.update({"size": size})
- return results
diff --git a/docs_src/path_params_numeric_validations/tutorial006.py b/docs_src/path_params_numeric_validations/tutorial006_py39.py
similarity index 100%
rename from docs_src/path_params_numeric_validations/tutorial006.py
rename to docs_src/path_params_numeric_validations/tutorial006_py39.py
diff --git a/docs_src/pydantic_v1_in_v2/__init__.py b/docs_src/pydantic_v1_in_v2/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py b/docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py
new file mode 100644
index 000000000..a8ec729b3
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial001_an_py310.py
@@ -0,0 +1,7 @@
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+ size: float
diff --git a/docs_src/pydantic_v1_in_v2/tutorial001_an_py39.py b/docs_src/pydantic_v1_in_v2/tutorial001_an_py39.py
new file mode 100644
index 000000000..62a4b2c21
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial001_an_py39.py
@@ -0,0 +1,9 @@
+from typing import Union
+
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ size: float
diff --git a/docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py b/docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py
new file mode 100644
index 000000000..4934e7004
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial002_an_py310.py
@@ -0,0 +1,16 @@
+from fastapi import FastAPI
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Item) -> Item:
+ return item
diff --git a/docs_src/pydantic_v1_in_v2/tutorial002_an_py39.py b/docs_src/pydantic_v1_in_v2/tutorial002_an_py39.py
new file mode 100644
index 000000000..3c6a06080
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial002_an_py39.py
@@ -0,0 +1,18 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Item) -> Item:
+ return item
diff --git a/docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py b/docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py
new file mode 100644
index 000000000..6e3013644
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial003_an_py310.py
@@ -0,0 +1,23 @@
+from fastapi import FastAPI
+from pydantic import BaseModel as BaseModelV2
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+ size: float
+
+
+class ItemV2(BaseModelV2):
+ name: str
+ description: str | None = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/", response_model=ItemV2)
+async def create_item(item: Item):
+ return item
diff --git a/docs_src/pydantic_v1_in_v2/tutorial003_an_py39.py b/docs_src/pydantic_v1_in_v2/tutorial003_an_py39.py
new file mode 100644
index 000000000..117d6f7a4
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial003_an_py39.py
@@ -0,0 +1,25 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel as BaseModelV2
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ size: float
+
+
+class ItemV2(BaseModelV2):
+ name: str
+ description: Union[str, None] = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/", response_model=ItemV2)
+async def create_item(item: Item):
+ return item
diff --git a/docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py b/docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py
new file mode 100644
index 000000000..c251311e0
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial004_an_py310.py
@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from fastapi import FastAPI
+from fastapi.temp_pydantic_v1_params import Body
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: str | None = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Annotated[Item, Body(embed=True)]) -> Item:
+ return item
diff --git a/docs_src/pydantic_v1_in_v2/tutorial004_an_py39.py b/docs_src/pydantic_v1_in_v2/tutorial004_an_py39.py
new file mode 100644
index 000000000..150ab20ae
--- /dev/null
+++ b/docs_src/pydantic_v1_in_v2/tutorial004_an_py39.py
@@ -0,0 +1,19 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI
+from fastapi.temp_pydantic_v1_params import Body
+from pydantic.v1 import BaseModel
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ size: float
+
+
+app = FastAPI()
+
+
+@app.post("/items/")
+async def create_item(item: Annotated[Item, Body(embed=True)]) -> Item:
+ return item
diff --git a/docs_src/python_types/__init__.py b/docs_src/python_types/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/python_types/tutorial001.py b/docs_src/python_types/tutorial001_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial001.py
rename to docs_src/python_types/tutorial001_py39.py
diff --git a/docs_src/python_types/tutorial002.py b/docs_src/python_types/tutorial002_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial002.py
rename to docs_src/python_types/tutorial002_py39.py
diff --git a/docs_src/python_types/tutorial003.py b/docs_src/python_types/tutorial003_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial003.py
rename to docs_src/python_types/tutorial003_py39.py
diff --git a/docs_src/python_types/tutorial004.py b/docs_src/python_types/tutorial004_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial004.py
rename to docs_src/python_types/tutorial004_py39.py
diff --git a/docs_src/python_types/tutorial005.py b/docs_src/python_types/tutorial005.py
deleted file mode 100644
index 08ab44a94..000000000
--- a/docs_src/python_types/tutorial005.py
+++ /dev/null
@@ -1,2 +0,0 @@
-def get_items(item_a: str, item_b: int, item_c: float, item_d: bool, item_e: bytes):
- return item_a, item_b, item_c, item_d, item_d, item_e
diff --git a/docs_src/python_types/tutorial005_py39.py b/docs_src/python_types/tutorial005_py39.py
new file mode 100644
index 000000000..6c8edb0ec
--- /dev/null
+++ b/docs_src/python_types/tutorial005_py39.py
@@ -0,0 +1,2 @@
+def get_items(item_a: str, item_b: int, item_c: float, item_d: bool, item_e: bytes):
+ return item_a, item_b, item_c, item_d, item_e
diff --git a/docs_src/python_types/tutorial006.py b/docs_src/python_types/tutorial006.py
deleted file mode 100644
index 87394ecb0..000000000
--- a/docs_src/python_types/tutorial006.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from typing import List
-
-
-def process_items(items: List[str]):
- for item in items:
- print(item)
diff --git a/docs_src/python_types/tutorial007.py b/docs_src/python_types/tutorial007.py
deleted file mode 100644
index 5b13f1549..000000000
--- a/docs_src/python_types/tutorial007.py
+++ /dev/null
@@ -1,5 +0,0 @@
-from typing import Set, Tuple
-
-
-def process_items(items_t: Tuple[int, int, str], items_s: Set[bytes]):
- return items_t, items_s
diff --git a/docs_src/python_types/tutorial008.py b/docs_src/python_types/tutorial008.py
deleted file mode 100644
index 9fb1043bb..000000000
--- a/docs_src/python_types/tutorial008.py
+++ /dev/null
@@ -1,7 +0,0 @@
-from typing import Dict
-
-
-def process_items(prices: Dict[str, float]):
- for item_name, item_price in prices.items():
- print(item_name)
- print(item_price)
diff --git a/docs_src/python_types/tutorial008b.py b/docs_src/python_types/tutorial008b_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial008b.py
rename to docs_src/python_types/tutorial008b_py39.py
diff --git a/docs_src/python_types/tutorial009.py b/docs_src/python_types/tutorial009_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial009.py
rename to docs_src/python_types/tutorial009_py39.py
diff --git a/docs_src/python_types/tutorial009b.py b/docs_src/python_types/tutorial009b_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial009b.py
rename to docs_src/python_types/tutorial009b_py39.py
diff --git a/docs_src/python_types/tutorial009c.py b/docs_src/python_types/tutorial009c_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial009c.py
rename to docs_src/python_types/tutorial009c_py39.py
diff --git a/docs_src/python_types/tutorial010.py b/docs_src/python_types/tutorial010_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial010.py
rename to docs_src/python_types/tutorial010_py39.py
diff --git a/docs_src/python_types/tutorial011.py b/docs_src/python_types/tutorial011.py
deleted file mode 100644
index 297a84db6..000000000
--- a/docs_src/python_types/tutorial011.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from datetime import datetime
-from typing import List, Union
-
-from pydantic import BaseModel
-
-
-class User(BaseModel):
- id: int
- name: str = "John Doe"
- signup_ts: Union[datetime, None] = None
- friends: List[int] = []
-
-
-external_data = {
- "id": "123",
- "signup_ts": "2017-06-01 12:22",
- "friends": [1, "2", b"3"],
-}
-user = User(**external_data)
-print(user)
-# > User id=123 name='John Doe' signup_ts=datetime.datetime(2017, 6, 1, 12, 22) friends=[1, 2, 3]
-print(user.id)
-# > 123
diff --git a/docs_src/python_types/tutorial012.py b/docs_src/python_types/tutorial012_py39.py
similarity index 100%
rename from docs_src/python_types/tutorial012.py
rename to docs_src/python_types/tutorial012_py39.py
diff --git a/docs_src/python_types/tutorial013.py b/docs_src/python_types/tutorial013.py
deleted file mode 100644
index 0ec773519..000000000
--- a/docs_src/python_types/tutorial013.py
+++ /dev/null
@@ -1,5 +0,0 @@
-from typing_extensions import Annotated
-
-
-def say_hello(name: Annotated[str, "this is just metadata"]) -> str:
- return f"Hello {name}"
diff --git a/docs_src/query_param_models/__init__.py b/docs_src/query_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/query_param_models/tutorial001.py b/docs_src/query_param_models/tutorial001.py
deleted file mode 100644
index 0c0ab315e..000000000
--- a/docs_src/query_param_models/tutorial001.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: FilterParams = Query()):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial001_an.py b/docs_src/query_param_models/tutorial001_an.py
deleted file mode 100644
index 28375057c..000000000
--- a/docs_src/query_param_models/tutorial001_an.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: Annotated[FilterParams, Query()]):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial001_an_py39.py b/docs_src/query_param_models/tutorial001_an_py39.py
index ba690d3e3..71427acae 100644
--- a/docs_src/query_param_models/tutorial001_an_py39.py
+++ b/docs_src/query_param_models/tutorial001_an_py39.py
@@ -1,6 +1,7 @@
+from typing import Annotated, Literal
+
from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
app = FastAPI()
diff --git a/docs_src/query_param_models/tutorial001_py39.py b/docs_src/query_param_models/tutorial001_py39.py
index 54b52a054..3ebf9f4d7 100644
--- a/docs_src/query_param_models/tutorial001_py39.py
+++ b/docs_src/query_param_models/tutorial001_py39.py
@@ -1,6 +1,7 @@
+from typing import Literal
+
from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
-from typing_extensions import Literal
app = FastAPI()
diff --git a/docs_src/query_param_models/tutorial002.py b/docs_src/query_param_models/tutorial002.py
deleted file mode 100644
index 1633bc464..000000000
--- a/docs_src/query_param_models/tutorial002.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- model_config = {"extra": "forbid"}
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: FilterParams = Query()):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_an.py b/docs_src/query_param_models/tutorial002_an.py
deleted file mode 100644
index 69705d4b4..000000000
--- a/docs_src/query_param_models/tutorial002_an.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- model_config = {"extra": "forbid"}
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: Annotated[FilterParams, Query()]):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_an_py39.py b/docs_src/query_param_models/tutorial002_an_py39.py
index 2d4c1a62b..975956502 100644
--- a/docs_src/query_param_models/tutorial002_an_py39.py
+++ b/docs_src/query_param_models/tutorial002_an_py39.py
@@ -1,6 +1,7 @@
+from typing import Annotated, Literal
+
from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
app = FastAPI()
diff --git a/docs_src/query_param_models/tutorial002_pv1.py b/docs_src/query_param_models/tutorial002_pv1.py
deleted file mode 100644
index 71ccd961d..000000000
--- a/docs_src/query_param_models/tutorial002_pv1.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: FilterParams = Query()):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an.py b/docs_src/query_param_models/tutorial002_pv1_an.py
deleted file mode 100644
index 1dd29157a..000000000
--- a/docs_src/query_param_models/tutorial002_pv1_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: List[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: Annotated[FilterParams, Query()]):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an_py310.py b/docs_src/query_param_models/tutorial002_pv1_an_py310.py
deleted file mode 100644
index d635aae88..000000000
--- a/docs_src/query_param_models/tutorial002_pv1_an_py310.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import Annotated, Literal
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: Annotated[FilterParams, Query()]):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an_py39.py b/docs_src/query_param_models/tutorial002_pv1_an_py39.py
deleted file mode 100644
index 494fef11f..000000000
--- a/docs_src/query_param_models/tutorial002_pv1_an_py39.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Annotated, Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: Annotated[FilterParams, Query()]):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_py310.py b/docs_src/query_param_models/tutorial002_pv1_py310.py
deleted file mode 100644
index 9ffdeefc0..000000000
--- a/docs_src/query_param_models/tutorial002_pv1_py310.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from typing import Literal
-
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: FilterParams = Query()):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_py39.py b/docs_src/query_param_models/tutorial002_pv1_py39.py
deleted file mode 100644
index 7fa456a79..000000000
--- a/docs_src/query_param_models/tutorial002_pv1_py39.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from fastapi import FastAPI, Query
-from pydantic import BaseModel, Field
-from typing_extensions import Literal
-
-app = FastAPI()
-
-
-class FilterParams(BaseModel):
- class Config:
- extra = "forbid"
-
- limit: int = Field(100, gt=0, le=100)
- offset: int = Field(0, ge=0)
- order_by: Literal["created_at", "updated_at"] = "created_at"
- tags: list[str] = []
-
-
-@app.get("/items/")
-async def read_items(filter_query: FilterParams = Query()):
- return filter_query
diff --git a/docs_src/query_param_models/tutorial002_py39.py b/docs_src/query_param_models/tutorial002_py39.py
index f9bba028c..6ec418499 100644
--- a/docs_src/query_param_models/tutorial002_py39.py
+++ b/docs_src/query_param_models/tutorial002_py39.py
@@ -1,6 +1,7 @@
+from typing import Literal
+
from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
-from typing_extensions import Literal
app = FastAPI()
diff --git a/docs_src/query_params/__init__.py b/docs_src/query_params/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/query_params/tutorial001.py b/docs_src/query_params/tutorial001_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial001.py
rename to docs_src/query_params/tutorial001_py39.py
diff --git a/docs_src/query_params/tutorial002.py b/docs_src/query_params/tutorial002_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial002.py
rename to docs_src/query_params/tutorial002_py39.py
diff --git a/docs_src/query_params/tutorial003.py b/docs_src/query_params/tutorial003_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial003.py
rename to docs_src/query_params/tutorial003_py39.py
diff --git a/docs_src/query_params/tutorial004.py b/docs_src/query_params/tutorial004_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial004.py
rename to docs_src/query_params/tutorial004_py39.py
diff --git a/docs_src/query_params/tutorial005.py b/docs_src/query_params/tutorial005_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial005.py
rename to docs_src/query_params/tutorial005_py39.py
diff --git a/docs_src/query_params/tutorial006.py b/docs_src/query_params/tutorial006_py39.py
similarity index 100%
rename from docs_src/query_params/tutorial006.py
rename to docs_src/query_params/tutorial006_py39.py
diff --git a/docs_src/query_params/tutorial006b.py b/docs_src/query_params/tutorial006b.py
deleted file mode 100644
index f0dbfe08f..000000000
--- a/docs_src/query_params/tutorial006b.py
+++ /dev/null
@@ -1,13 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-
-app = FastAPI()
-
-
-@app.get("/items/{item_id}")
-async def read_user_item(
- item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
-):
- item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
- return item
diff --git a/docs_src/query_params_str_validations/__init__.py b/docs_src/query_params_str_validations/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/query_params_str_validations/tutorial001.py b/docs_src/query_params_str_validations/tutorial001_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial001.py
rename to docs_src/query_params_str_validations/tutorial001_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial002_an.py b/docs_src/query_params_str_validations/tutorial002_an.py
deleted file mode 100644
index cb1b38940..000000000
--- a/docs_src/query_params_str_validations/tutorial002_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial002_an_py39.py b/docs_src/query_params_str_validations/tutorial002_an_py39.py
new file mode 100644
index 000000000..2d8fc9798
--- /dev/null
+++ b/docs_src/query_params_str_validations/tutorial002_an_py39.py
@@ -0,0 +1,13 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+
+@app.get("/items/")
+async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
+ results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
+ if q:
+ results.update({"q": q})
+ return results
diff --git a/docs_src/query_params_str_validations/tutorial002.py b/docs_src/query_params_str_validations/tutorial002_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial002.py
rename to docs_src/query_params_str_validations/tutorial002_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial003_an.py b/docs_src/query_params_str_validations/tutorial003_an.py
deleted file mode 100644
index 0dd14086c..000000000
--- a/docs_src/query_params_str_validations/tutorial003_an.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- q: Annotated[Union[str, None], Query(min_length=3, max_length=50)] = None,
-):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial003.py b/docs_src/query_params_str_validations/tutorial003_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial003.py
rename to docs_src/query_params_str_validations/tutorial003_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial004_an.py b/docs_src/query_params_str_validations/tutorial004_an.py
deleted file mode 100644
index c75d45d63..000000000
--- a/docs_src/query_params_str_validations/tutorial004_an.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- q: Annotated[
- Union[str, None], Query(min_length=3, max_length=50, pattern="^fixedquery$")
- ] = None,
-):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial004.py b/docs_src/query_params_str_validations/tutorial004_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial004.py
rename to docs_src/query_params_str_validations/tutorial004_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial005_an.py b/docs_src/query_params_str_validations/tutorial005_an.py
deleted file mode 100644
index 452d4d38d..000000000
--- a/docs_src/query_params_str_validations/tutorial005_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[str, Query(min_length=3)] = "fixedquery"):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial005.py b/docs_src/query_params_str_validations/tutorial005_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial005.py
rename to docs_src/query_params_str_validations/tutorial005_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial006_an.py b/docs_src/query_params_str_validations/tutorial006_an.py
deleted file mode 100644
index 559480d2b..000000000
--- a/docs_src/query_params_str_validations/tutorial006_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[str, Query(min_length=3)]):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial006.py b/docs_src/query_params_str_validations/tutorial006_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial006.py
rename to docs_src/query_params_str_validations/tutorial006_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial006c_an.py b/docs_src/query_params_str_validations/tutorial006c_an.py
deleted file mode 100644
index 55c4f4adc..000000000
--- a/docs_src/query_params_str_validations/tutorial006c_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[Union[str, None], Query(min_length=3)]):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial006c.py b/docs_src/query_params_str_validations/tutorial006c_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial006c.py
rename to docs_src/query_params_str_validations/tutorial006c_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial007_an.py b/docs_src/query_params_str_validations/tutorial007_an.py
deleted file mode 100644
index 4b3c8de4b..000000000
--- a/docs_src/query_params_str_validations/tutorial007_an.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- q: Annotated[Union[str, None], Query(title="Query string", min_length=3)] = None,
-):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial007.py b/docs_src/query_params_str_validations/tutorial007_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial007.py
rename to docs_src/query_params_str_validations/tutorial007_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial008_an.py b/docs_src/query_params_str_validations/tutorial008_an.py
deleted file mode 100644
index 01606a920..000000000
--- a/docs_src/query_params_str_validations/tutorial008_an.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- q: Annotated[
- Union[str, None],
- Query(
- title="Query string",
- description="Query string for the items to search in the database that have a good match",
- min_length=3,
- ),
- ] = None,
-):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial008.py b/docs_src/query_params_str_validations/tutorial008_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial008.py
rename to docs_src/query_params_str_validations/tutorial008_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial009_an.py b/docs_src/query_params_str_validations/tutorial009_an.py
deleted file mode 100644
index 2894e2d51..000000000
--- a/docs_src/query_params_str_validations/tutorial009_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[Union[str, None], Query(alias="item-query")] = None):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial009.py b/docs_src/query_params_str_validations/tutorial009_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial009.py
rename to docs_src/query_params_str_validations/tutorial009_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial010_an.py b/docs_src/query_params_str_validations/tutorial010_an.py
deleted file mode 100644
index ed343230f..000000000
--- a/docs_src/query_params_str_validations/tutorial010_an.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- q: Annotated[
- Union[str, None],
- Query(
- alias="item-query",
- title="Query string",
- description="Query string for the items to search in the database that have a good match",
- min_length=3,
- max_length=50,
- pattern="^fixedquery$",
- deprecated=True,
- ),
- ] = None,
-):
- results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
- if q:
- results.update({"q": q})
- return results
diff --git a/docs_src/query_params_str_validations/tutorial010.py b/docs_src/query_params_str_validations/tutorial010_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial010.py
rename to docs_src/query_params_str_validations/tutorial010_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial011.py b/docs_src/query_params_str_validations/tutorial011.py
deleted file mode 100644
index 65bbce781..000000000
--- a/docs_src/query_params_str_validations/tutorial011.py
+++ /dev/null
@@ -1,11 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Query
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Union[List[str], None] = Query(default=None)):
- query_items = {"q": q}
- return query_items
diff --git a/docs_src/query_params_str_validations/tutorial011_an.py b/docs_src/query_params_str_validations/tutorial011_an.py
deleted file mode 100644
index 8ed699337..000000000
--- a/docs_src/query_params_str_validations/tutorial011_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[Union[List[str], None], Query()] = None):
- query_items = {"q": q}
- return query_items
diff --git a/docs_src/query_params_str_validations/tutorial012.py b/docs_src/query_params_str_validations/tutorial012.py
deleted file mode 100644
index e77d56974..000000000
--- a/docs_src/query_params_str_validations/tutorial012.py
+++ /dev/null
@@ -1,11 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: List[str] = Query(default=["foo", "bar"])):
- query_items = {"q": q}
- return query_items
diff --git a/docs_src/query_params_str_validations/tutorial012_an.py b/docs_src/query_params_str_validations/tutorial012_an.py
deleted file mode 100644
index 261af250a..000000000
--- a/docs_src/query_params_str_validations/tutorial012_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[List[str], Query()] = ["foo", "bar"]):
- query_items = {"q": q}
- return query_items
diff --git a/docs_src/query_params_str_validations/tutorial013_an.py b/docs_src/query_params_str_validations/tutorial013_an.py
deleted file mode 100644
index f12a25055..000000000
--- a/docs_src/query_params_str_validations/tutorial013_an.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(q: Annotated[list, Query()] = []):
- query_items = {"q": q}
- return query_items
diff --git a/docs_src/query_params_str_validations/tutorial013.py b/docs_src/query_params_str_validations/tutorial013_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial013.py
rename to docs_src/query_params_str_validations/tutorial013_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial014_an.py b/docs_src/query_params_str_validations/tutorial014_an.py
deleted file mode 100644
index 2eaa58540..000000000
--- a/docs_src/query_params_str_validations/tutorial014_an.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, Query
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.get("/items/")
-async def read_items(
- hidden_query: Annotated[Union[str, None], Query(include_in_schema=False)] = None,
-):
- if hidden_query:
- return {"hidden_query": hidden_query}
- else:
- return {"hidden_query": "Not found"}
diff --git a/docs_src/query_params_str_validations/tutorial014.py b/docs_src/query_params_str_validations/tutorial014_py39.py
similarity index 100%
rename from docs_src/query_params_str_validations/tutorial014.py
rename to docs_src/query_params_str_validations/tutorial014_py39.py
diff --git a/docs_src/query_params_str_validations/tutorial015_an.py b/docs_src/query_params_str_validations/tutorial015_an.py
deleted file mode 100644
index f2ec6db12..000000000
--- a/docs_src/query_params_str_validations/tutorial015_an.py
+++ /dev/null
@@ -1,31 +0,0 @@
-import random
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import AfterValidator
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-data = {
- "isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
- "imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
- "isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
-}
-
-
-def check_valid_id(id: str):
- if not id.startswith(("isbn-", "imdb-")):
- raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
- return id
-
-
-@app.get("/items/")
-async def read_items(
- id: Annotated[Union[str, None], AfterValidator(check_valid_id)] = None,
-):
- if id:
- item = data.get(id)
- else:
- id, item = random.choice(list(data.items()))
- return {"id": id, "name": item}
diff --git a/docs_src/request_files/__init__.py b/docs_src/request_files/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/request_files/tutorial001_02_an.py b/docs_src/request_files/tutorial001_02_an.py
deleted file mode 100644
index 5007fef15..000000000
--- a/docs_src/request_files/tutorial001_02_an.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI, File, UploadFile
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_file(file: Annotated[Union[bytes, None], File()] = None):
- if not file:
- return {"message": "No file sent"}
- else:
- return {"file_size": len(file)}
-
-
-@app.post("/uploadfile/")
-async def create_upload_file(file: Union[UploadFile, None] = None):
- if not file:
- return {"message": "No upload file sent"}
- else:
- return {"filename": file.filename}
diff --git a/docs_src/request_files/tutorial001_02.py b/docs_src/request_files/tutorial001_02_py39.py
similarity index 100%
rename from docs_src/request_files/tutorial001_02.py
rename to docs_src/request_files/tutorial001_02_py39.py
diff --git a/docs_src/request_files/tutorial001_03_an.py b/docs_src/request_files/tutorial001_03_an.py
deleted file mode 100644
index 8a6b0a245..000000000
--- a/docs_src/request_files/tutorial001_03_an.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from fastapi import FastAPI, File, UploadFile
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_file(file: Annotated[bytes, File(description="A file read as bytes")]):
- return {"file_size": len(file)}
-
-
-@app.post("/uploadfile/")
-async def create_upload_file(
- file: Annotated[UploadFile, File(description="A file read as UploadFile")],
-):
- return {"filename": file.filename}
diff --git a/docs_src/request_files/tutorial001_03.py b/docs_src/request_files/tutorial001_03_py39.py
similarity index 100%
rename from docs_src/request_files/tutorial001_03.py
rename to docs_src/request_files/tutorial001_03_py39.py
diff --git a/docs_src/request_files/tutorial001_an.py b/docs_src/request_files/tutorial001_an.py
deleted file mode 100644
index ca2f76d5c..000000000
--- a/docs_src/request_files/tutorial001_an.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from fastapi import FastAPI, File, UploadFile
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_file(file: Annotated[bytes, File()]):
- return {"file_size": len(file)}
-
-
-@app.post("/uploadfile/")
-async def create_upload_file(file: UploadFile):
- return {"filename": file.filename}
diff --git a/docs_src/request_files/tutorial001.py b/docs_src/request_files/tutorial001_py39.py
similarity index 100%
rename from docs_src/request_files/tutorial001.py
rename to docs_src/request_files/tutorial001_py39.py
diff --git a/docs_src/request_files/tutorial002.py b/docs_src/request_files/tutorial002.py
deleted file mode 100644
index b4d0acc68..000000000
--- a/docs_src/request_files/tutorial002.py
+++ /dev/null
@@ -1,33 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, File, UploadFile
-from fastapi.responses import HTMLResponse
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_files(files: List[bytes] = File()):
- return {"file_sizes": [len(file) for file in files]}
-
-
-@app.post("/uploadfiles/")
-async def create_upload_files(files: List[UploadFile]):
- return {"filenames": [file.filename for file in files]}
-
-
-@app.get("/")
-async def main():
- content = """
-
-
-
-
- """
- return HTMLResponse(content=content)
diff --git a/docs_src/request_files/tutorial002_an.py b/docs_src/request_files/tutorial002_an.py
deleted file mode 100644
index eaa90da2b..000000000
--- a/docs_src/request_files/tutorial002_an.py
+++ /dev/null
@@ -1,34 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, File, UploadFile
-from fastapi.responses import HTMLResponse
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_files(files: Annotated[List[bytes], File()]):
- return {"file_sizes": [len(file) for file in files]}
-
-
-@app.post("/uploadfiles/")
-async def create_upload_files(files: List[UploadFile]):
- return {"filenames": [file.filename for file in files]}
-
-
-@app.get("/")
-async def main():
- content = """
-
-
-
-
- """
- return HTMLResponse(content=content)
diff --git a/docs_src/request_files/tutorial003.py b/docs_src/request_files/tutorial003.py
deleted file mode 100644
index e3f805f60..000000000
--- a/docs_src/request_files/tutorial003.py
+++ /dev/null
@@ -1,37 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, File, UploadFile
-from fastapi.responses import HTMLResponse
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_files(
- files: List[bytes] = File(description="Multiple files as bytes"),
-):
- return {"file_sizes": [len(file) for file in files]}
-
-
-@app.post("/uploadfiles/")
-async def create_upload_files(
- files: List[UploadFile] = File(description="Multiple files as UploadFile"),
-):
- return {"filenames": [file.filename for file in files]}
-
-
-@app.get("/")
-async def main():
- content = """
-
-
-
-
- """
- return HTMLResponse(content=content)
diff --git a/docs_src/request_files/tutorial003_an.py b/docs_src/request_files/tutorial003_an.py
deleted file mode 100644
index 2238e3c94..000000000
--- a/docs_src/request_files/tutorial003_an.py
+++ /dev/null
@@ -1,40 +0,0 @@
-from typing import List
-
-from fastapi import FastAPI, File, UploadFile
-from fastapi.responses import HTMLResponse
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_files(
- files: Annotated[List[bytes], File(description="Multiple files as bytes")],
-):
- return {"file_sizes": [len(file) for file in files]}
-
-
-@app.post("/uploadfiles/")
-async def create_upload_files(
- files: Annotated[
- List[UploadFile], File(description="Multiple files as UploadFile")
- ],
-):
- return {"filenames": [file.filename for file in files]}
-
-
-@app.get("/")
-async def main():
- content = """
-
-
-
-
- """
- return HTMLResponse(content=content)
diff --git a/docs_src/request_form_models/__init__.py b/docs_src/request_form_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/request_form_models/tutorial001_an.py b/docs_src/request_form_models/tutorial001_an.py
deleted file mode 100644
index 30483d445..000000000
--- a/docs_src/request_form_models/tutorial001_an.py
+++ /dev/null
@@ -1,15 +0,0 @@
-from fastapi import FastAPI, Form
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class FormData(BaseModel):
- username: str
- password: str
-
-
-@app.post("/login/")
-async def login(data: Annotated[FormData, Form()]):
- return data
diff --git a/docs_src/request_form_models/tutorial001.py b/docs_src/request_form_models/tutorial001_py39.py
similarity index 100%
rename from docs_src/request_form_models/tutorial001.py
rename to docs_src/request_form_models/tutorial001_py39.py
diff --git a/docs_src/request_form_models/tutorial002_an.py b/docs_src/request_form_models/tutorial002_an.py
deleted file mode 100644
index bcb022795..000000000
--- a/docs_src/request_form_models/tutorial002_an.py
+++ /dev/null
@@ -1,16 +0,0 @@
-from fastapi import FastAPI, Form
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class FormData(BaseModel):
- username: str
- password: str
- model_config = {"extra": "forbid"}
-
-
-@app.post("/login/")
-async def login(data: Annotated[FormData, Form()]):
- return data
diff --git a/docs_src/request_form_models/tutorial002_pv1.py b/docs_src/request_form_models/tutorial002_pv1.py
deleted file mode 100644
index d5f7db2a6..000000000
--- a/docs_src/request_form_models/tutorial002_pv1.py
+++ /dev/null
@@ -1,17 +0,0 @@
-from fastapi import FastAPI, Form
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class FormData(BaseModel):
- username: str
- password: str
-
- class Config:
- extra = "forbid"
-
-
-@app.post("/login/")
-async def login(data: FormData = Form()):
- return data
diff --git a/docs_src/request_form_models/tutorial002_pv1_an.py b/docs_src/request_form_models/tutorial002_pv1_an.py
deleted file mode 100644
index fe9dbc344..000000000
--- a/docs_src/request_form_models/tutorial002_pv1_an.py
+++ /dev/null
@@ -1,18 +0,0 @@
-from fastapi import FastAPI, Form
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class FormData(BaseModel):
- username: str
- password: str
-
- class Config:
- extra = "forbid"
-
-
-@app.post("/login/")
-async def login(data: Annotated[FormData, Form()]):
- return data
diff --git a/docs_src/request_form_models/tutorial002_pv1_an_py39.py b/docs_src/request_form_models/tutorial002_pv1_an_py39.py
deleted file mode 100644
index 942d5d411..000000000
--- a/docs_src/request_form_models/tutorial002_pv1_an_py39.py
+++ /dev/null
@@ -1,19 +0,0 @@
-from typing import Annotated
-
-from fastapi import FastAPI, Form
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class FormData(BaseModel):
- username: str
- password: str
-
- class Config:
- extra = "forbid"
-
-
-@app.post("/login/")
-async def login(data: Annotated[FormData, Form()]):
- return data
diff --git a/docs_src/request_form_models/tutorial002.py b/docs_src/request_form_models/tutorial002_py39.py
similarity index 100%
rename from docs_src/request_form_models/tutorial002.py
rename to docs_src/request_form_models/tutorial002_py39.py
diff --git a/docs_src/request_forms/__init__.py b/docs_src/request_forms/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/request_forms/tutorial001_an.py b/docs_src/request_forms/tutorial001_an.py
deleted file mode 100644
index 677fbf2db..000000000
--- a/docs_src/request_forms/tutorial001_an.py
+++ /dev/null
@@ -1,9 +0,0 @@
-from fastapi import FastAPI, Form
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/login/")
-async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
- return {"username": username}
diff --git a/docs_src/request_forms/tutorial001.py b/docs_src/request_forms/tutorial001_py39.py
similarity index 100%
rename from docs_src/request_forms/tutorial001.py
rename to docs_src/request_forms/tutorial001_py39.py
diff --git a/docs_src/request_forms_and_files/__init__.py b/docs_src/request_forms_and_files/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/request_forms_and_files/tutorial001_an.py b/docs_src/request_forms_and_files/tutorial001_an.py
deleted file mode 100644
index 0ea285ac8..000000000
--- a/docs_src/request_forms_and_files/tutorial001_an.py
+++ /dev/null
@@ -1,17 +0,0 @@
-from fastapi import FastAPI, File, Form, UploadFile
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-@app.post("/files/")
-async def create_file(
- file: Annotated[bytes, File()],
- fileb: Annotated[UploadFile, File()],
- token: Annotated[str, Form()],
-):
- return {
- "file_size": len(file),
- "token": token,
- "fileb_content_type": fileb.content_type,
- }
diff --git a/docs_src/request_forms_and_files/tutorial001.py b/docs_src/request_forms_and_files/tutorial001_py39.py
similarity index 100%
rename from docs_src/request_forms_and_files/tutorial001.py
rename to docs_src/request_forms_and_files/tutorial001_py39.py
diff --git a/docs_src/response_change_status_code/__init__.py b/docs_src/response_change_status_code/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_change_status_code/tutorial001.py b/docs_src/response_change_status_code/tutorial001_py39.py
similarity index 100%
rename from docs_src/response_change_status_code/tutorial001.py
rename to docs_src/response_change_status_code/tutorial001_py39.py
diff --git a/docs_src/response_cookies/__init__.py b/docs_src/response_cookies/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_cookies/tutorial001.py b/docs_src/response_cookies/tutorial001_py39.py
similarity index 100%
rename from docs_src/response_cookies/tutorial001.py
rename to docs_src/response_cookies/tutorial001_py39.py
diff --git a/docs_src/response_cookies/tutorial002.py b/docs_src/response_cookies/tutorial002_py39.py
similarity index 100%
rename from docs_src/response_cookies/tutorial002.py
rename to docs_src/response_cookies/tutorial002_py39.py
diff --git a/docs_src/response_directly/__init__.py b/docs_src/response_directly/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_directly/tutorial001_py310.py b/docs_src/response_directly/tutorial001_py310.py
new file mode 100644
index 000000000..81e094dc6
--- /dev/null
+++ b/docs_src/response_directly/tutorial001_py310.py
@@ -0,0 +1,21 @@
+from datetime import datetime
+
+from fastapi import FastAPI
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+
+class Item(BaseModel):
+ title: str
+ timestamp: datetime
+ description: str | None = None
+
+
+app = FastAPI()
+
+
+@app.put("/items/{id}")
+def update_item(id: str, item: Item):
+ json_compatible_item_data = jsonable_encoder(item)
+ return JSONResponse(content=json_compatible_item_data)
diff --git a/docs_src/response_directly/tutorial001.py b/docs_src/response_directly/tutorial001_py39.py
similarity index 100%
rename from docs_src/response_directly/tutorial001.py
rename to docs_src/response_directly/tutorial001_py39.py
diff --git a/docs_src/response_directly/tutorial002.py b/docs_src/response_directly/tutorial002_py39.py
similarity index 100%
rename from docs_src/response_directly/tutorial002.py
rename to docs_src/response_directly/tutorial002_py39.py
diff --git a/docs_src/response_headers/__init__.py b/docs_src/response_headers/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_headers/tutorial001.py b/docs_src/response_headers/tutorial001_py39.py
similarity index 100%
rename from docs_src/response_headers/tutorial001.py
rename to docs_src/response_headers/tutorial001_py39.py
diff --git a/docs_src/response_headers/tutorial002.py b/docs_src/response_headers/tutorial002_py39.py
similarity index 100%
rename from docs_src/response_headers/tutorial002.py
rename to docs_src/response_headers/tutorial002_py39.py
diff --git a/docs_src/response_model/__init__.py b/docs_src/response_model/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_model/tutorial001.py b/docs_src/response_model/tutorial001.py
deleted file mode 100644
index fd1c902a5..000000000
--- a/docs_src/response_model/tutorial001.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from typing import Any, List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: List[str] = []
-
-
-@app.post("/items/", response_model=Item)
-async def create_item(item: Item) -> Any:
- return item
-
-
-@app.get("/items/", response_model=List[Item])
-async def read_items() -> Any:
- return [
- {"name": "Portal Gun", "price": 42.0},
- {"name": "Plumbus", "price": 32.0},
- ]
diff --git a/docs_src/response_model/tutorial001_01.py b/docs_src/response_model/tutorial001_01.py
deleted file mode 100644
index 98d30d540..000000000
--- a/docs_src/response_model/tutorial001_01.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
- tags: List[str] = []
-
-
-@app.post("/items/")
-async def create_item(item: Item) -> Item:
- return item
-
-
-@app.get("/items/")
-async def read_items() -> List[Item]:
- return [
- Item(name="Portal Gun", price=42.0),
- Item(name="Plumbus", price=32.0),
- ]
diff --git a/docs_src/response_model/tutorial002.py b/docs_src/response_model/tutorial002_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial002.py
rename to docs_src/response_model/tutorial002_py39.py
diff --git a/docs_src/response_model/tutorial003_01.py b/docs_src/response_model/tutorial003_01_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003_01.py
rename to docs_src/response_model/tutorial003_01_py39.py
diff --git a/docs_src/response_model/tutorial003_02.py b/docs_src/response_model/tutorial003_02_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003_02.py
rename to docs_src/response_model/tutorial003_02_py39.py
diff --git a/docs_src/response_model/tutorial003_03.py b/docs_src/response_model/tutorial003_03_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003_03.py
rename to docs_src/response_model/tutorial003_03_py39.py
diff --git a/docs_src/response_model/tutorial003_04.py b/docs_src/response_model/tutorial003_04_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003_04.py
rename to docs_src/response_model/tutorial003_04_py39.py
diff --git a/docs_src/response_model/tutorial003_05.py b/docs_src/response_model/tutorial003_05_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003_05.py
rename to docs_src/response_model/tutorial003_05_py39.py
diff --git a/docs_src/response_model/tutorial003.py b/docs_src/response_model/tutorial003_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial003.py
rename to docs_src/response_model/tutorial003_py39.py
diff --git a/docs_src/response_model/tutorial004.py b/docs_src/response_model/tutorial004.py
deleted file mode 100644
index 10b48039a..000000000
--- a/docs_src/response_model/tutorial004.py
+++ /dev/null
@@ -1,26 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: float = 10.5
- tags: List[str] = []
-
-
-items = {
- "foo": {"name": "Foo", "price": 50.2},
- "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
- "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
-}
-
-
-@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
-async def read_item(item_id: str):
- return items[item_id]
diff --git a/docs_src/response_model/tutorial005.py b/docs_src/response_model/tutorial005_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial005.py
rename to docs_src/response_model/tutorial005_py39.py
diff --git a/docs_src/response_model/tutorial006.py b/docs_src/response_model/tutorial006_py39.py
similarity index 100%
rename from docs_src/response_model/tutorial006.py
rename to docs_src/response_model/tutorial006_py39.py
diff --git a/docs_src/response_status_code/__init__.py b/docs_src/response_status_code/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/response_status_code/tutorial001.py b/docs_src/response_status_code/tutorial001_py39.py
similarity index 100%
rename from docs_src/response_status_code/tutorial001.py
rename to docs_src/response_status_code/tutorial001_py39.py
diff --git a/docs_src/response_status_code/tutorial002.py b/docs_src/response_status_code/tutorial002_py39.py
similarity index 100%
rename from docs_src/response_status_code/tutorial002.py
rename to docs_src/response_status_code/tutorial002_py39.py
diff --git a/docs_src/schema_extra_example/__init__.py b/docs_src/schema_extra_example/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/schema_extra_example/tutorial001_pv1.py b/docs_src/schema_extra_example/tutorial001_pv1.py
deleted file mode 100644
index 6ab96ff85..000000000
--- a/docs_src/schema_extra_example/tutorial001_pv1.py
+++ /dev/null
@@ -1,31 +0,0 @@
-from typing import Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
- class Config:
- schema_extra = {
- "examples": [
- {
- "name": "Foo",
- "description": "A very nice Item",
- "price": 35.4,
- "tax": 3.2,
- }
- ]
- }
-
-
-@app.put("/items/{item_id}")
-async def update_item(item_id: int, item: Item):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/schema_extra_example/tutorial001_pv1_py310.py b/docs_src/schema_extra_example/tutorial001_pv1_py310.py
index ec83f1112..b13b8a8c2 100644
--- a/docs_src/schema_extra_example/tutorial001_pv1_py310.py
+++ b/docs_src/schema_extra_example/tutorial001_pv1_py310.py
@@ -1,5 +1,5 @@
from fastapi import FastAPI
-from pydantic import BaseModel
+from pydantic.v1 import BaseModel
app = FastAPI()
diff --git a/docs_src/schema_extra_example/tutorial001_pv1_py39.py b/docs_src/schema_extra_example/tutorial001_pv1_py39.py
new file mode 100644
index 000000000..3240b35d6
--- /dev/null
+++ b/docs_src/schema_extra_example/tutorial001_pv1_py39.py
@@ -0,0 +1,31 @@
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic.v1 import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ description: Union[str, None] = None
+ price: float
+ tax: Union[float, None] = None
+
+ class Config:
+ schema_extra = {
+ "examples": [
+ {
+ "name": "Foo",
+ "description": "A very nice Item",
+ "price": 35.4,
+ "tax": 3.2,
+ }
+ ]
+ }
+
+
+@app.put("/items/{item_id}")
+async def update_item(item_id: int, item: Item):
+ results = {"item_id": item_id, "item": item}
+ return results
diff --git a/docs_src/schema_extra_example/tutorial001.py b/docs_src/schema_extra_example/tutorial001_py39.py
similarity index 100%
rename from docs_src/schema_extra_example/tutorial001.py
rename to docs_src/schema_extra_example/tutorial001_py39.py
diff --git a/docs_src/schema_extra_example/tutorial002.py b/docs_src/schema_extra_example/tutorial002_py39.py
similarity index 100%
rename from docs_src/schema_extra_example/tutorial002.py
rename to docs_src/schema_extra_example/tutorial002_py39.py
diff --git a/docs_src/schema_extra_example/tutorial003_an.py b/docs_src/schema_extra_example/tutorial003_an.py
deleted file mode 100644
index 23675aba1..000000000
--- a/docs_src/schema_extra_example/tutorial003_an.py
+++ /dev/null
@@ -1,35 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- item_id: int,
- item: Annotated[
- Item,
- Body(
- examples=[
- {
- "name": "Foo",
- "description": "A very nice Item",
- "price": 35.4,
- "tax": 3.2,
- }
- ],
- ),
- ],
-):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/schema_extra_example/tutorial003.py b/docs_src/schema_extra_example/tutorial003_py39.py
similarity index 100%
rename from docs_src/schema_extra_example/tutorial003.py
rename to docs_src/schema_extra_example/tutorial003_py39.py
diff --git a/docs_src/schema_extra_example/tutorial004_an.py b/docs_src/schema_extra_example/tutorial004_an.py
deleted file mode 100644
index e817302a2..000000000
--- a/docs_src/schema_extra_example/tutorial004_an.py
+++ /dev/null
@@ -1,44 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- *,
- item_id: int,
- item: Annotated[
- Item,
- Body(
- examples=[
- {
- "name": "Foo",
- "description": "A very nice Item",
- "price": 35.4,
- "tax": 3.2,
- },
- {
- "name": "Bar",
- "price": "35.4",
- },
- {
- "name": "Baz",
- "price": "thirty five point four",
- },
- ],
- ),
- ],
-):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/schema_extra_example/tutorial004.py b/docs_src/schema_extra_example/tutorial004_py39.py
similarity index 100%
rename from docs_src/schema_extra_example/tutorial004.py
rename to docs_src/schema_extra_example/tutorial004_py39.py
diff --git a/docs_src/schema_extra_example/tutorial005_an.py b/docs_src/schema_extra_example/tutorial005_an.py
deleted file mode 100644
index 4b2d9c662..000000000
--- a/docs_src/schema_extra_example/tutorial005_an.py
+++ /dev/null
@@ -1,55 +0,0 @@
-from typing import Union
-
-from fastapi import Body, FastAPI
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
- price: float
- tax: Union[float, None] = None
-
-
-@app.put("/items/{item_id}")
-async def update_item(
- *,
- item_id: int,
- item: Annotated[
- Item,
- Body(
- openapi_examples={
- "normal": {
- "summary": "A normal example",
- "description": "A **normal** item works correctly.",
- "value": {
- "name": "Foo",
- "description": "A very nice Item",
- "price": 35.4,
- "tax": 3.2,
- },
- },
- "converted": {
- "summary": "An example with converted data",
- "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
- "value": {
- "name": "Bar",
- "price": "35.4",
- },
- },
- "invalid": {
- "summary": "Invalid data is rejected with an error",
- "value": {
- "name": "Baz",
- "price": "thirty five point four",
- },
- },
- },
- ),
- ],
-):
- results = {"item_id": item_id, "item": item}
- return results
diff --git a/docs_src/schema_extra_example/tutorial005.py b/docs_src/schema_extra_example/tutorial005_py39.py
similarity index 100%
rename from docs_src/schema_extra_example/tutorial005.py
rename to docs_src/schema_extra_example/tutorial005_py39.py
diff --git a/docs_src/security/__init__.py b/docs_src/security/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/security/tutorial001_an.py b/docs_src/security/tutorial001_an.py
deleted file mode 100644
index dac915b7c..000000000
--- a/docs_src/security/tutorial001_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from fastapi import Depends, FastAPI
-from fastapi.security import OAuth2PasswordBearer
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-
-@app.get("/items/")
-async def read_items(token: Annotated[str, Depends(oauth2_scheme)]):
- return {"token": token}
diff --git a/docs_src/security/tutorial001.py b/docs_src/security/tutorial001_py39.py
similarity index 100%
rename from docs_src/security/tutorial001.py
rename to docs_src/security/tutorial001_py39.py
diff --git a/docs_src/security/tutorial002_an.py b/docs_src/security/tutorial002_an.py
deleted file mode 100644
index 291b3bf53..000000000
--- a/docs_src/security/tutorial002_an.py
+++ /dev/null
@@ -1,33 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI
-from fastapi.security import OAuth2PasswordBearer
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-def fake_decode_token(token):
- return User(
- username=token + "fakedecoded", email="john@example.com", full_name="John Doe"
- )
-
-
-async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
- user = fake_decode_token(token)
- return user
-
-
-@app.get("/users/me")
-async def read_users_me(current_user: Annotated[User, Depends(get_current_user)]):
- return current_user
diff --git a/docs_src/security/tutorial002.py b/docs_src/security/tutorial002_py39.py
similarity index 100%
rename from docs_src/security/tutorial002.py
rename to docs_src/security/tutorial002_py39.py
diff --git a/docs_src/security/tutorial003.py b/docs_src/security/tutorial003.py
deleted file mode 100644
index 4b324866f..000000000
--- a/docs_src/security/tutorial003.py
+++ /dev/null
@@ -1,90 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
-from pydantic import BaseModel
-
-fake_users_db = {
- "johndoe": {
- "username": "johndoe",
- "full_name": "John Doe",
- "email": "johndoe@example.com",
- "hashed_password": "fakehashedsecret",
- "disabled": False,
- },
- "alice": {
- "username": "alice",
- "full_name": "Alice Wonderson",
- "email": "alice@example.com",
- "hashed_password": "fakehashedsecret2",
- "disabled": True,
- },
-}
-
-app = FastAPI()
-
-
-def fake_hash_password(password: str):
- return "fakehashed" + password
-
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-class UserInDB(User):
- hashed_password: str
-
-
-def get_user(db, username: str):
- if username in db:
- user_dict = db[username]
- return UserInDB(**user_dict)
-
-
-def fake_decode_token(token):
- # This doesn't provide any security at all
- # Check the next version
- user = get_user(fake_users_db, token)
- return user
-
-
-async def get_current_user(token: str = Depends(oauth2_scheme)):
- user = fake_decode_token(token)
- if not user:
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Invalid authentication credentials",
- headers={"WWW-Authenticate": "Bearer"},
- )
- return user
-
-
-async def get_current_active_user(current_user: User = Depends(get_current_user)):
- if current_user.disabled:
- raise HTTPException(status_code=400, detail="Inactive user")
- return current_user
-
-
-@app.post("/token")
-async def login(form_data: OAuth2PasswordRequestForm = Depends()):
- user_dict = fake_users_db.get(form_data.username)
- if not user_dict:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
- user = UserInDB(**user_dict)
- hashed_password = fake_hash_password(form_data.password)
- if not hashed_password == user.hashed_password:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
-
- return {"access_token": user.username, "token_type": "bearer"}
-
-
-@app.get("/users/me")
-async def read_users_me(current_user: User = Depends(get_current_active_user)):
- return current_user
diff --git a/docs_src/security/tutorial003_an.py b/docs_src/security/tutorial003_an.py
deleted file mode 100644
index 8fb40dd4a..000000000
--- a/docs_src/security/tutorial003_an.py
+++ /dev/null
@@ -1,95 +0,0 @@
-from typing import Union
-
-from fastapi import Depends, FastAPI, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-fake_users_db = {
- "johndoe": {
- "username": "johndoe",
- "full_name": "John Doe",
- "email": "johndoe@example.com",
- "hashed_password": "fakehashedsecret",
- "disabled": False,
- },
- "alice": {
- "username": "alice",
- "full_name": "Alice Wonderson",
- "email": "alice@example.com",
- "hashed_password": "fakehashedsecret2",
- "disabled": True,
- },
-}
-
-app = FastAPI()
-
-
-def fake_hash_password(password: str):
- return "fakehashed" + password
-
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-class UserInDB(User):
- hashed_password: str
-
-
-def get_user(db, username: str):
- if username in db:
- user_dict = db[username]
- return UserInDB(**user_dict)
-
-
-def fake_decode_token(token):
- # This doesn't provide any security at all
- # Check the next version
- user = get_user(fake_users_db, token)
- return user
-
-
-async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
- user = fake_decode_token(token)
- if not user:
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Invalid authentication credentials",
- headers={"WWW-Authenticate": "Bearer"},
- )
- return user
-
-
-async def get_current_active_user(
- current_user: Annotated[User, Depends(get_current_user)],
-):
- if current_user.disabled:
- raise HTTPException(status_code=400, detail="Inactive user")
- return current_user
-
-
-@app.post("/token")
-async def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
- user_dict = fake_users_db.get(form_data.username)
- if not user_dict:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
- user = UserInDB(**user_dict)
- hashed_password = fake_hash_password(form_data.password)
- if not hashed_password == user.hashed_password:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
-
- return {"access_token": user.username, "token_type": "bearer"}
-
-
-@app.get("/users/me")
-async def read_users_me(
- current_user: Annotated[User, Depends(get_current_active_user)],
-):
- return current_user
diff --git a/docs_src/security/tutorial003_an_py310.py b/docs_src/security/tutorial003_an_py310.py
index ced4a2fbc..4a2743f6f 100644
--- a/docs_src/security/tutorial003_an_py310.py
+++ b/docs_src/security/tutorial003_an_py310.py
@@ -60,7 +60,7 @@ async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Invalid authentication credentials",
+ detail="Not authenticated",
headers={"WWW-Authenticate": "Bearer"},
)
return user
diff --git a/docs_src/security/tutorial003_an_py39.py b/docs_src/security/tutorial003_an_py39.py
index 068a3933e..b396210c8 100644
--- a/docs_src/security/tutorial003_an_py39.py
+++ b/docs_src/security/tutorial003_an_py39.py
@@ -60,7 +60,7 @@ async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Invalid authentication credentials",
+ detail="Not authenticated",
headers={"WWW-Authenticate": "Bearer"},
)
return user
diff --git a/docs_src/security/tutorial003_py310.py b/docs_src/security/tutorial003_py310.py
index af935e997..081259b31 100644
--- a/docs_src/security/tutorial003_py310.py
+++ b/docs_src/security/tutorial003_py310.py
@@ -58,7 +58,7 @@ async def get_current_user(token: str = Depends(oauth2_scheme)):
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Invalid authentication credentials",
+ detail="Not authenticated",
headers={"WWW-Authenticate": "Bearer"},
)
return user
diff --git a/docs_src/security/tutorial003_py39.py b/docs_src/security/tutorial003_py39.py
new file mode 100644
index 000000000..ce7a71b68
--- /dev/null
+++ b/docs_src/security/tutorial003_py39.py
@@ -0,0 +1,90 @@
+from typing import Union
+
+from fastapi import Depends, FastAPI, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from pydantic import BaseModel
+
+fake_users_db = {
+ "johndoe": {
+ "username": "johndoe",
+ "full_name": "John Doe",
+ "email": "johndoe@example.com",
+ "hashed_password": "fakehashedsecret",
+ "disabled": False,
+ },
+ "alice": {
+ "username": "alice",
+ "full_name": "Alice Wonderson",
+ "email": "alice@example.com",
+ "hashed_password": "fakehashedsecret2",
+ "disabled": True,
+ },
+}
+
+app = FastAPI()
+
+
+def fake_hash_password(password: str):
+ return "fakehashed" + password
+
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+
+class User(BaseModel):
+ username: str
+ email: Union[str, None] = None
+ full_name: Union[str, None] = None
+ disabled: Union[bool, None] = None
+
+
+class UserInDB(User):
+ hashed_password: str
+
+
+def get_user(db, username: str):
+ if username in db:
+ user_dict = db[username]
+ return UserInDB(**user_dict)
+
+
+def fake_decode_token(token):
+ # This doesn't provide any security at all
+ # Check the next version
+ user = get_user(fake_users_db, token)
+ return user
+
+
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+ user = fake_decode_token(token)
+ if not user:
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="Not authenticated",
+ headers={"WWW-Authenticate": "Bearer"},
+ )
+ return user
+
+
+async def get_current_active_user(current_user: User = Depends(get_current_user)):
+ if current_user.disabled:
+ raise HTTPException(status_code=400, detail="Inactive user")
+ return current_user
+
+
+@app.post("/token")
+async def login(form_data: OAuth2PasswordRequestForm = Depends()):
+ user_dict = fake_users_db.get(form_data.username)
+ if not user_dict:
+ raise HTTPException(status_code=400, detail="Incorrect username or password")
+ user = UserInDB(**user_dict)
+ hashed_password = fake_hash_password(form_data.password)
+ if not hashed_password == user.hashed_password:
+ raise HTTPException(status_code=400, detail="Incorrect username or password")
+
+ return {"access_token": user.username, "token_type": "bearer"}
+
+
+@app.get("/users/me")
+async def read_users_me(current_user: User = Depends(get_current_active_user)):
+ return current_user
diff --git a/docs_src/security/tutorial004_an.py b/docs_src/security/tutorial004_an.py
deleted file mode 100644
index 018234e30..000000000
--- a/docs_src/security/tutorial004_an.py
+++ /dev/null
@@ -1,148 +0,0 @@
-from datetime import datetime, timedelta, timezone
-from typing import Union
-
-import jwt
-from fastapi import Depends, FastAPI, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
-from jwt.exceptions import InvalidTokenError
-from pwdlib import PasswordHash
-from pydantic import BaseModel
-from typing_extensions import Annotated
-
-# to get a string like this run:
-# openssl rand -hex 32
-SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 30
-
-
-fake_users_db = {
- "johndoe": {
- "username": "johndoe",
- "full_name": "John Doe",
- "email": "johndoe@example.com",
- "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc",
- "disabled": False,
- }
-}
-
-
-class Token(BaseModel):
- access_token: str
- token_type: str
-
-
-class TokenData(BaseModel):
- username: Union[str, None] = None
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-class UserInDB(User):
- hashed_password: str
-
-
-password_hash = PasswordHash.recommended()
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-app = FastAPI()
-
-
-def verify_password(plain_password, hashed_password):
- return password_hash.verify(plain_password, hashed_password)
-
-
-def get_password_hash(password):
- return password_hash.hash(password)
-
-
-def get_user(db, username: str):
- if username in db:
- user_dict = db[username]
- return UserInDB(**user_dict)
-
-
-def authenticate_user(fake_db, username: str, password: str):
- user = get_user(fake_db, username)
- if not user:
- return False
- if not verify_password(password, user.hashed_password):
- return False
- return user
-
-
-def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None):
- to_encode = data.copy()
- if expires_delta:
- expire = datetime.now(timezone.utc) + expires_delta
- else:
- expire = datetime.now(timezone.utc) + timedelta(minutes=15)
- to_encode.update({"exp": expire})
- encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
- return encoded_jwt
-
-
-async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
- credentials_exception = HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Could not validate credentials",
- headers={"WWW-Authenticate": "Bearer"},
- )
- try:
- payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
- username = payload.get("sub")
- if username is None:
- raise credentials_exception
- token_data = TokenData(username=username)
- except InvalidTokenError:
- raise credentials_exception
- user = get_user(fake_users_db, username=token_data.username)
- if user is None:
- raise credentials_exception
- return user
-
-
-async def get_current_active_user(
- current_user: Annotated[User, Depends(get_current_user)],
-):
- if current_user.disabled:
- raise HTTPException(status_code=400, detail="Inactive user")
- return current_user
-
-
-@app.post("/token")
-async def login_for_access_token(
- form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
-) -> Token:
- user = authenticate_user(fake_users_db, form_data.username, form_data.password)
- if not user:
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Incorrect username or password",
- headers={"WWW-Authenticate": "Bearer"},
- )
- access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
- access_token = create_access_token(
- data={"sub": user.username}, expires_delta=access_token_expires
- )
- return Token(access_token=access_token, token_type="bearer")
-
-
-@app.get("/users/me/", response_model=User)
-async def read_users_me(
- current_user: Annotated[User, Depends(get_current_active_user)],
-):
- return current_user
-
-
-@app.get("/users/me/items/")
-async def read_own_items(
- current_user: Annotated[User, Depends(get_current_active_user)],
-):
- return [{"item_id": "Foo", "owner": current_user.username}]
diff --git a/docs_src/security/tutorial004.py b/docs_src/security/tutorial004_py39.py
similarity index 100%
rename from docs_src/security/tutorial004.py
rename to docs_src/security/tutorial004_py39.py
diff --git a/docs_src/security/tutorial005.py b/docs_src/security/tutorial005.py
deleted file mode 100644
index fdd73bcd8..000000000
--- a/docs_src/security/tutorial005.py
+++ /dev/null
@@ -1,177 +0,0 @@
-from datetime import datetime, timedelta, timezone
-from typing import List, Union
-
-import jwt
-from fastapi import Depends, FastAPI, HTTPException, Security, status
-from fastapi.security import (
- OAuth2PasswordBearer,
- OAuth2PasswordRequestForm,
- SecurityScopes,
-)
-from jwt.exceptions import InvalidTokenError
-from pwdlib import PasswordHash
-from pydantic import BaseModel, ValidationError
-
-# to get a string like this run:
-# openssl rand -hex 32
-SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 30
-
-
-fake_users_db = {
- "johndoe": {
- "username": "johndoe",
- "full_name": "John Doe",
- "email": "johndoe@example.com",
- "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc",
- "disabled": False,
- },
- "alice": {
- "username": "alice",
- "full_name": "Alice Chains",
- "email": "alicechains@example.com",
- "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$g2/AV1zwopqUntPKJavBFw$BwpRGDCyUHLvHICnwijyX8ROGoiUPwNKZ7915MeYfCE",
- "disabled": True,
- },
-}
-
-
-class Token(BaseModel):
- access_token: str
- token_type: str
-
-
-class TokenData(BaseModel):
- username: Union[str, None] = None
- scopes: List[str] = []
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-class UserInDB(User):
- hashed_password: str
-
-
-password_hash = PasswordHash.recommended()
-
-oauth2_scheme = OAuth2PasswordBearer(
- tokenUrl="token",
- scopes={"me": "Read information about the current user.", "items": "Read items."},
-)
-
-app = FastAPI()
-
-
-def verify_password(plain_password, hashed_password):
- return password_hash.verify(plain_password, hashed_password)
-
-
-def get_password_hash(password):
- return password_hash.hash(password)
-
-
-def get_user(db, username: str):
- if username in db:
- user_dict = db[username]
- return UserInDB(**user_dict)
-
-
-def authenticate_user(fake_db, username: str, password: str):
- user = get_user(fake_db, username)
- if not user:
- return False
- if not verify_password(password, user.hashed_password):
- return False
- return user
-
-
-def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None):
- to_encode = data.copy()
- if expires_delta:
- expire = datetime.now(timezone.utc) + expires_delta
- else:
- expire = datetime.now(timezone.utc) + timedelta(minutes=15)
- to_encode.update({"exp": expire})
- encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
- return encoded_jwt
-
-
-async def get_current_user(
- security_scopes: SecurityScopes, token: str = Depends(oauth2_scheme)
-):
- if security_scopes.scopes:
- authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
- else:
- authenticate_value = "Bearer"
- credentials_exception = HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Could not validate credentials",
- headers={"WWW-Authenticate": authenticate_value},
- )
- try:
- payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
- username: str = payload.get("sub")
- if username is None:
- raise credentials_exception
- scope: str = payload.get("scope", "")
- token_scopes = scope.split(" ")
- token_data = TokenData(scopes=token_scopes, username=username)
- except (InvalidTokenError, ValidationError):
- raise credentials_exception
- user = get_user(fake_users_db, username=token_data.username)
- if user is None:
- raise credentials_exception
- for scope in security_scopes.scopes:
- if scope not in token_data.scopes:
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Not enough permissions",
- headers={"WWW-Authenticate": authenticate_value},
- )
- return user
-
-
-async def get_current_active_user(
- current_user: User = Security(get_current_user, scopes=["me"]),
-):
- if current_user.disabled:
- raise HTTPException(status_code=400, detail="Inactive user")
- return current_user
-
-
-@app.post("/token")
-async def login_for_access_token(
- form_data: OAuth2PasswordRequestForm = Depends(),
-) -> Token:
- user = authenticate_user(fake_users_db, form_data.username, form_data.password)
- if not user:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
- access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
- access_token = create_access_token(
- data={"sub": user.username, "scope": " ".join(form_data.scopes)},
- expires_delta=access_token_expires,
- )
- return Token(access_token=access_token, token_type="bearer")
-
-
-@app.get("/users/me/", response_model=User)
-async def read_users_me(current_user: User = Depends(get_current_active_user)):
- return current_user
-
-
-@app.get("/users/me/items/")
-async def read_own_items(
- current_user: User = Security(get_current_active_user, scopes=["items"]),
-):
- return [{"item_id": "Foo", "owner": current_user.username}]
-
-
-@app.get("/status/")
-async def read_system_status(current_user: User = Depends(get_current_user)):
- return {"status": "ok"}
diff --git a/docs_src/security/tutorial005_an.py b/docs_src/security/tutorial005_an.py
deleted file mode 100644
index e1d7b4f62..000000000
--- a/docs_src/security/tutorial005_an.py
+++ /dev/null
@@ -1,180 +0,0 @@
-from datetime import datetime, timedelta, timezone
-from typing import List, Union
-
-import jwt
-from fastapi import Depends, FastAPI, HTTPException, Security, status
-from fastapi.security import (
- OAuth2PasswordBearer,
- OAuth2PasswordRequestForm,
- SecurityScopes,
-)
-from jwt.exceptions import InvalidTokenError
-from pwdlib import PasswordHash
-from pydantic import BaseModel, ValidationError
-from typing_extensions import Annotated
-
-# to get a string like this run:
-# openssl rand -hex 32
-SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 30
-
-
-fake_users_db = {
- "johndoe": {
- "username": "johndoe",
- "full_name": "John Doe",
- "email": "johndoe@example.com",
- "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$wagCPXjifgvUFBzq4hqe3w$CYaIb8sB+wtD+Vu/P4uod1+Qof8h+1g7bbDlBID48Rc",
- "disabled": False,
- },
- "alice": {
- "username": "alice",
- "full_name": "Alice Chains",
- "email": "alicechains@example.com",
- "hashed_password": "$argon2id$v=19$m=65536,t=3,p=4$g2/AV1zwopqUntPKJavBFw$BwpRGDCyUHLvHICnwijyX8ROGoiUPwNKZ7915MeYfCE",
- "disabled": True,
- },
-}
-
-
-class Token(BaseModel):
- access_token: str
- token_type: str
-
-
-class TokenData(BaseModel):
- username: Union[str, None] = None
- scopes: List[str] = []
-
-
-class User(BaseModel):
- username: str
- email: Union[str, None] = None
- full_name: Union[str, None] = None
- disabled: Union[bool, None] = None
-
-
-class UserInDB(User):
- hashed_password: str
-
-
-password_hash = PasswordHash.recommended()
-
-oauth2_scheme = OAuth2PasswordBearer(
- tokenUrl="token",
- scopes={"me": "Read information about the current user.", "items": "Read items."},
-)
-
-app = FastAPI()
-
-
-def verify_password(plain_password, hashed_password):
- return password_hash.verify(plain_password, hashed_password)
-
-
-def get_password_hash(password):
- return password_hash.hash(password)
-
-
-def get_user(db, username: str):
- if username in db:
- user_dict = db[username]
- return UserInDB(**user_dict)
-
-
-def authenticate_user(fake_db, username: str, password: str):
- user = get_user(fake_db, username)
- if not user:
- return False
- if not verify_password(password, user.hashed_password):
- return False
- return user
-
-
-def create_access_token(data: dict, expires_delta: Union[timedelta, None] = None):
- to_encode = data.copy()
- if expires_delta:
- expire = datetime.now(timezone.utc) + expires_delta
- else:
- expire = datetime.now(timezone.utc) + timedelta(minutes=15)
- to_encode.update({"exp": expire})
- encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
- return encoded_jwt
-
-
-async def get_current_user(
- security_scopes: SecurityScopes, token: Annotated[str, Depends(oauth2_scheme)]
-):
- if security_scopes.scopes:
- authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
- else:
- authenticate_value = "Bearer"
- credentials_exception = HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Could not validate credentials",
- headers={"WWW-Authenticate": authenticate_value},
- )
- try:
- payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
- username = payload.get("sub")
- if username is None:
- raise credentials_exception
- scope: str = payload.get("scope", "")
- token_scopes = scope.split(" ")
- token_data = TokenData(scopes=token_scopes, username=username)
- except (InvalidTokenError, ValidationError):
- raise credentials_exception
- user = get_user(fake_users_db, username=token_data.username)
- if user is None:
- raise credentials_exception
- for scope in security_scopes.scopes:
- if scope not in token_data.scopes:
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Not enough permissions",
- headers={"WWW-Authenticate": authenticate_value},
- )
- return user
-
-
-async def get_current_active_user(
- current_user: Annotated[User, Security(get_current_user, scopes=["me"])],
-):
- if current_user.disabled:
- raise HTTPException(status_code=400, detail="Inactive user")
- return current_user
-
-
-@app.post("/token")
-async def login_for_access_token(
- form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
-) -> Token:
- user = authenticate_user(fake_users_db, form_data.username, form_data.password)
- if not user:
- raise HTTPException(status_code=400, detail="Incorrect username or password")
- access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
- access_token = create_access_token(
- data={"sub": user.username, "scope": " ".join(form_data.scopes)},
- expires_delta=access_token_expires,
- )
- return Token(access_token=access_token, token_type="bearer")
-
-
-@app.get("/users/me/", response_model=User)
-async def read_users_me(
- current_user: Annotated[User, Depends(get_current_active_user)],
-):
- return current_user
-
-
-@app.get("/users/me/items/")
-async def read_own_items(
- current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])],
-):
- return [{"item_id": "Foo", "owner": current_user.username}]
-
-
-@app.get("/status/")
-async def read_system_status(current_user: Annotated[User, Depends(get_current_user)]):
- return {"status": "ok"}
diff --git a/docs_src/security/tutorial006_an.py b/docs_src/security/tutorial006_an.py
deleted file mode 100644
index 985e4b2ad..000000000
--- a/docs_src/security/tutorial006_an.py
+++ /dev/null
@@ -1,12 +0,0 @@
-from fastapi import Depends, FastAPI
-from fastapi.security import HTTPBasic, HTTPBasicCredentials
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-security = HTTPBasic()
-
-
-@app.get("/users/me")
-def read_current_user(credentials: Annotated[HTTPBasicCredentials, Depends(security)]):
- return {"username": credentials.username, "password": credentials.password}
diff --git a/docs_src/security/tutorial006.py b/docs_src/security/tutorial006_py39.py
similarity index 100%
rename from docs_src/security/tutorial006.py
rename to docs_src/security/tutorial006_py39.py
diff --git a/docs_src/security/tutorial007_an.py b/docs_src/security/tutorial007_an.py
deleted file mode 100644
index 0d211dfde..000000000
--- a/docs_src/security/tutorial007_an.py
+++ /dev/null
@@ -1,36 +0,0 @@
-import secrets
-
-from fastapi import Depends, FastAPI, HTTPException, status
-from fastapi.security import HTTPBasic, HTTPBasicCredentials
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-security = HTTPBasic()
-
-
-def get_current_username(
- credentials: Annotated[HTTPBasicCredentials, Depends(security)],
-):
- current_username_bytes = credentials.username.encode("utf8")
- correct_username_bytes = b"stanleyjobson"
- is_correct_username = secrets.compare_digest(
- current_username_bytes, correct_username_bytes
- )
- current_password_bytes = credentials.password.encode("utf8")
- correct_password_bytes = b"swordfish"
- is_correct_password = secrets.compare_digest(
- current_password_bytes, correct_password_bytes
- )
- if not (is_correct_username and is_correct_password):
- raise HTTPException(
- status_code=status.HTTP_401_UNAUTHORIZED,
- detail="Incorrect username or password",
- headers={"WWW-Authenticate": "Basic"},
- )
- return credentials.username
-
-
-@app.get("/users/me")
-def read_current_user(username: Annotated[str, Depends(get_current_username)]):
- return {"username": username}
diff --git a/docs_src/security/tutorial007.py b/docs_src/security/tutorial007_py39.py
similarity index 100%
rename from docs_src/security/tutorial007.py
rename to docs_src/security/tutorial007_py39.py
diff --git a/docs_src/separate_openapi_schemas/__init__.py b/docs_src/separate_openapi_schemas/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/separate_openapi_schemas/tutorial001.py b/docs_src/separate_openapi_schemas/tutorial001.py
deleted file mode 100644
index 415eef8e2..000000000
--- a/docs_src/separate_openapi_schemas/tutorial001.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
-
-
-app = FastAPI()
-
-
-@app.post("/items/")
-def create_item(item: Item):
- return item
-
-
-@app.get("/items/")
-def read_items() -> List[Item]:
- return [
- Item(
- name="Portal Gun",
- description="Device to travel through the multi-rick-verse",
- ),
- Item(name="Plumbus"),
- ]
diff --git a/docs_src/separate_openapi_schemas/tutorial002.py b/docs_src/separate_openapi_schemas/tutorial002.py
deleted file mode 100644
index 7df93783b..000000000
--- a/docs_src/separate_openapi_schemas/tutorial002.py
+++ /dev/null
@@ -1,28 +0,0 @@
-from typing import List, Union
-
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-
-class Item(BaseModel):
- name: str
- description: Union[str, None] = None
-
-
-app = FastAPI(separate_input_output_schemas=False)
-
-
-@app.post("/items/")
-def create_item(item: Item):
- return item
-
-
-@app.get("/items/")
-def read_items() -> List[Item]:
- return [
- Item(
- name="Portal Gun",
- description="Device to travel through the multi-rick-verse",
- ),
- Item(name="Plumbus"),
- ]
diff --git a/docs_src/settings/__init__.py b/docs_src/settings/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/settings/app01_py39/__init__.py b/docs_src/settings/app01_py39/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/settings/app01/config.py b/docs_src/settings/app01_py39/config.py
similarity index 100%
rename from docs_src/settings/app01/config.py
rename to docs_src/settings/app01_py39/config.py
diff --git a/docs_src/settings/app01/main.py b/docs_src/settings/app01_py39/main.py
similarity index 100%
rename from docs_src/settings/app01/main.py
rename to docs_src/settings/app01_py39/main.py
diff --git a/docs_src/settings/app02_an/config.py b/docs_src/settings/app02_an/config.py
deleted file mode 100644
index e17b5035d..000000000
--- a/docs_src/settings/app02_an/config.py
+++ /dev/null
@@ -1,7 +0,0 @@
-from pydantic_settings import BaseSettings
-
-
-class Settings(BaseSettings):
- app_name: str = "Awesome API"
- admin_email: str
- items_per_user: int = 50
diff --git a/docs_src/settings/app02_an/main.py b/docs_src/settings/app02_an/main.py
deleted file mode 100644
index 3a578cc33..000000000
--- a/docs_src/settings/app02_an/main.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from functools import lru_cache
-
-from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
-
-from .config import Settings
-
-app = FastAPI()
-
-
-@lru_cache
-def get_settings():
- return Settings()
-
-
-@app.get("/info")
-async def info(settings: Annotated[Settings, Depends(get_settings)]):
- return {
- "app_name": settings.app_name,
- "admin_email": settings.admin_email,
- "items_per_user": settings.items_per_user,
- }
diff --git a/docs_src/settings/app02_an/test_main.py b/docs_src/settings/app02_an/test_main.py
deleted file mode 100644
index 7a04d7e8e..000000000
--- a/docs_src/settings/app02_an/test_main.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from fastapi.testclient import TestClient
-
-from .config import Settings
-from .main import app, get_settings
-
-client = TestClient(app)
-
-
-def get_settings_override():
- return Settings(admin_email="testing_admin@example.com")
-
-
-app.dependency_overrides[get_settings] = get_settings_override
-
-
-def test_app():
- response = client.get("/info")
- data = response.json()
- assert data == {
- "app_name": "Awesome API",
- "admin_email": "testing_admin@example.com",
- "items_per_user": 50,
- }
diff --git a/docs_src/settings/app02_py39/__init__.py b/docs_src/settings/app02_py39/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/settings/app02/config.py b/docs_src/settings/app02_py39/config.py
similarity index 100%
rename from docs_src/settings/app02/config.py
rename to docs_src/settings/app02_py39/config.py
diff --git a/docs_src/settings/app02/main.py b/docs_src/settings/app02_py39/main.py
similarity index 100%
rename from docs_src/settings/app02/main.py
rename to docs_src/settings/app02_py39/main.py
diff --git a/docs_src/settings/app02/test_main.py b/docs_src/settings/app02_py39/test_main.py
similarity index 100%
rename from docs_src/settings/app02/test_main.py
rename to docs_src/settings/app02_py39/test_main.py
diff --git a/docs_src/settings/app03/config.py b/docs_src/settings/app03/config.py
deleted file mode 100644
index 942aea3e5..000000000
--- a/docs_src/settings/app03/config.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from pydantic_settings import BaseSettings
-
-
-class Settings(BaseSettings):
- app_name: str = "Awesome API"
- admin_email: str
- items_per_user: int = 50
-
- class Config:
- env_file = ".env"
diff --git a/docs_src/settings/app03_an/config_pv1.py b/docs_src/settings/app03_an/config_pv1.py
deleted file mode 100644
index e1c3ee300..000000000
--- a/docs_src/settings/app03_an/config_pv1.py
+++ /dev/null
@@ -1,10 +0,0 @@
-from pydantic import BaseSettings
-
-
-class Settings(BaseSettings):
- app_name: str = "Awesome API"
- admin_email: str
- items_per_user: int = 50
-
- class Config:
- env_file = ".env"
diff --git a/docs_src/settings/app03_an/main.py b/docs_src/settings/app03_an/main.py
deleted file mode 100644
index 2f64b9cd1..000000000
--- a/docs_src/settings/app03_an/main.py
+++ /dev/null
@@ -1,22 +0,0 @@
-from functools import lru_cache
-from typing import Annotated
-
-from fastapi import Depends, FastAPI
-
-from . import config
-
-app = FastAPI()
-
-
-@lru_cache
-def get_settings():
- return config.Settings()
-
-
-@app.get("/info")
-async def info(settings: Annotated[config.Settings, Depends(get_settings)]):
- return {
- "app_name": settings.app_name,
- "admin_email": settings.admin_email,
- "items_per_user": settings.items_per_user,
- }
diff --git a/docs_src/settings/app03_an_py39/config.py b/docs_src/settings/app03_an_py39/config.py
index 942aea3e5..08f8f88c2 100644
--- a/docs_src/settings/app03_an_py39/config.py
+++ b/docs_src/settings/app03_an_py39/config.py
@@ -1,4 +1,4 @@
-from pydantic_settings import BaseSettings
+from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
@@ -6,5 +6,4 @@ class Settings(BaseSettings):
admin_email: str
items_per_user: int = 50
- class Config:
- env_file = ".env"
+ model_config = SettingsConfigDict(env_file=".env")
diff --git a/docs_src/settings/app03_an_py39/config_pv1.py b/docs_src/settings/app03_an_py39/config_pv1.py
new file mode 100644
index 000000000..7ae66ef77
--- /dev/null
+++ b/docs_src/settings/app03_an_py39/config_pv1.py
@@ -0,0 +1,10 @@
+from pydantic.v1 import BaseSettings
+
+
+class Settings(BaseSettings):
+ app_name: str = "Awesome API"
+ admin_email: str
+ items_per_user: int = 50
+
+ class Config:
+ env_file = ".env"
diff --git a/docs_src/settings/app03_an_py39/main.py b/docs_src/settings/app03_an_py39/main.py
index 62f347639..2f64b9cd1 100644
--- a/docs_src/settings/app03_an_py39/main.py
+++ b/docs_src/settings/app03_an_py39/main.py
@@ -1,7 +1,7 @@
from functools import lru_cache
+from typing import Annotated
from fastapi import Depends, FastAPI
-from typing_extensions import Annotated
from . import config
diff --git a/docs_src/settings/app03_py39/__init__.py b/docs_src/settings/app03_py39/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/settings/app03_an/config.py b/docs_src/settings/app03_py39/config.py
similarity index 100%
rename from docs_src/settings/app03_an/config.py
rename to docs_src/settings/app03_py39/config.py
diff --git a/docs_src/settings/app03_py39/config_pv1.py b/docs_src/settings/app03_py39/config_pv1.py
new file mode 100644
index 000000000..7ae66ef77
--- /dev/null
+++ b/docs_src/settings/app03_py39/config_pv1.py
@@ -0,0 +1,10 @@
+from pydantic.v1 import BaseSettings
+
+
+class Settings(BaseSettings):
+ app_name: str = "Awesome API"
+ admin_email: str
+ items_per_user: int = 50
+
+ class Config:
+ env_file = ".env"
diff --git a/docs_src/settings/app03/main.py b/docs_src/settings/app03_py39/main.py
similarity index 100%
rename from docs_src/settings/app03/main.py
rename to docs_src/settings/app03_py39/main.py
diff --git a/docs_src/settings/tutorial001_pv1.py b/docs_src/settings/tutorial001_pv1.py
deleted file mode 100644
index 0cfd1b663..000000000
--- a/docs_src/settings/tutorial001_pv1.py
+++ /dev/null
@@ -1,21 +0,0 @@
-from fastapi import FastAPI
-from pydantic import BaseSettings
-
-
-class Settings(BaseSettings):
- app_name: str = "Awesome API"
- admin_email: str
- items_per_user: int = 50
-
-
-settings = Settings()
-app = FastAPI()
-
-
-@app.get("/info")
-async def info():
- return {
- "app_name": settings.app_name,
- "admin_email": settings.admin_email,
- "items_per_user": settings.items_per_user,
- }
diff --git a/docs_src/settings/tutorial001_pv1_py39.py b/docs_src/settings/tutorial001_pv1_py39.py
new file mode 100644
index 000000000..20ad2bbf6
--- /dev/null
+++ b/docs_src/settings/tutorial001_pv1_py39.py
@@ -0,0 +1,21 @@
+from fastapi import FastAPI
+from pydantic.v1 import BaseSettings
+
+
+class Settings(BaseSettings):
+ app_name: str = "Awesome API"
+ admin_email: str
+ items_per_user: int = 50
+
+
+settings = Settings()
+app = FastAPI()
+
+
+@app.get("/info")
+async def info():
+ return {
+ "app_name": settings.app_name,
+ "admin_email": settings.admin_email,
+ "items_per_user": settings.items_per_user,
+ }
diff --git a/docs_src/settings/tutorial001.py b/docs_src/settings/tutorial001_py39.py
similarity index 100%
rename from docs_src/settings/tutorial001.py
rename to docs_src/settings/tutorial001_py39.py
diff --git a/docs_src/sql_databases/tutorial001.py b/docs_src/sql_databases/tutorial001.py
deleted file mode 100644
index be86ec0ee..000000000
--- a/docs_src/sql_databases/tutorial001.py
+++ /dev/null
@@ -1,71 +0,0 @@
-from typing import List, Union
-
-from fastapi import Depends, FastAPI, HTTPException, Query
-from sqlmodel import Field, Session, SQLModel, create_engine, select
-
-
-class Hero(SQLModel, table=True):
- id: Union[int, None] = Field(default=None, primary_key=True)
- name: str = Field(index=True)
- age: Union[int, None] = Field(default=None, index=True)
- secret_name: str
-
-
-sqlite_file_name = "database.db"
-sqlite_url = f"sqlite:///{sqlite_file_name}"
-
-connect_args = {"check_same_thread": False}
-engine = create_engine(sqlite_url, connect_args=connect_args)
-
-
-def create_db_and_tables():
- SQLModel.metadata.create_all(engine)
-
-
-def get_session():
- with Session(engine) as session:
- yield session
-
-
-app = FastAPI()
-
-
-@app.on_event("startup")
-def on_startup():
- create_db_and_tables()
-
-
-@app.post("/heroes/")
-def create_hero(hero: Hero, session: Session = Depends(get_session)) -> Hero:
- session.add(hero)
- session.commit()
- session.refresh(hero)
- return hero
-
-
-@app.get("/heroes/")
-def read_heroes(
- session: Session = Depends(get_session),
- offset: int = 0,
- limit: int = Query(default=100, le=100),
-) -> List[Hero]:
- heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
- return heroes
-
-
-@app.get("/heroes/{hero_id}")
-def read_hero(hero_id: int, session: Session = Depends(get_session)) -> Hero:
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- return hero
-
-
-@app.delete("/heroes/{hero_id}")
-def delete_hero(hero_id: int, session: Session = Depends(get_session)):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- session.delete(hero)
- session.commit()
- return {"ok": True}
diff --git a/docs_src/sql_databases/tutorial001_an.py b/docs_src/sql_databases/tutorial001_an.py
deleted file mode 100644
index 8c000d31c..000000000
--- a/docs_src/sql_databases/tutorial001_an.py
+++ /dev/null
@@ -1,74 +0,0 @@
-from typing import List, Union
-
-from fastapi import Depends, FastAPI, HTTPException, Query
-from sqlmodel import Field, Session, SQLModel, create_engine, select
-from typing_extensions import Annotated
-
-
-class Hero(SQLModel, table=True):
- id: Union[int, None] = Field(default=None, primary_key=True)
- name: str = Field(index=True)
- age: Union[int, None] = Field(default=None, index=True)
- secret_name: str
-
-
-sqlite_file_name = "database.db"
-sqlite_url = f"sqlite:///{sqlite_file_name}"
-
-connect_args = {"check_same_thread": False}
-engine = create_engine(sqlite_url, connect_args=connect_args)
-
-
-def create_db_and_tables():
- SQLModel.metadata.create_all(engine)
-
-
-def get_session():
- with Session(engine) as session:
- yield session
-
-
-SessionDep = Annotated[Session, Depends(get_session)]
-
-app = FastAPI()
-
-
-@app.on_event("startup")
-def on_startup():
- create_db_and_tables()
-
-
-@app.post("/heroes/")
-def create_hero(hero: Hero, session: SessionDep) -> Hero:
- session.add(hero)
- session.commit()
- session.refresh(hero)
- return hero
-
-
-@app.get("/heroes/")
-def read_heroes(
- session: SessionDep,
- offset: int = 0,
- limit: Annotated[int, Query(le=100)] = 100,
-) -> List[Hero]:
- heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
- return heroes
-
-
-@app.get("/heroes/{hero_id}")
-def read_hero(hero_id: int, session: SessionDep) -> Hero:
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- return hero
-
-
-@app.delete("/heroes/{hero_id}")
-def delete_hero(hero_id: int, session: SessionDep):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- session.delete(hero)
- session.commit()
- return {"ok": True}
diff --git a/docs_src/sql_databases/tutorial002.py b/docs_src/sql_databases/tutorial002.py
deleted file mode 100644
index 4350d19c6..000000000
--- a/docs_src/sql_databases/tutorial002.py
+++ /dev/null
@@ -1,104 +0,0 @@
-from typing import List, Union
-
-from fastapi import Depends, FastAPI, HTTPException, Query
-from sqlmodel import Field, Session, SQLModel, create_engine, select
-
-
-class HeroBase(SQLModel):
- name: str = Field(index=True)
- age: Union[int, None] = Field(default=None, index=True)
-
-
-class Hero(HeroBase, table=True):
- id: Union[int, None] = Field(default=None, primary_key=True)
- secret_name: str
-
-
-class HeroPublic(HeroBase):
- id: int
-
-
-class HeroCreate(HeroBase):
- secret_name: str
-
-
-class HeroUpdate(HeroBase):
- name: Union[str, None] = None
- age: Union[int, None] = None
- secret_name: Union[str, None] = None
-
-
-sqlite_file_name = "database.db"
-sqlite_url = f"sqlite:///{sqlite_file_name}"
-
-connect_args = {"check_same_thread": False}
-engine = create_engine(sqlite_url, connect_args=connect_args)
-
-
-def create_db_and_tables():
- SQLModel.metadata.create_all(engine)
-
-
-def get_session():
- with Session(engine) as session:
- yield session
-
-
-app = FastAPI()
-
-
-@app.on_event("startup")
-def on_startup():
- create_db_and_tables()
-
-
-@app.post("/heroes/", response_model=HeroPublic)
-def create_hero(hero: HeroCreate, session: Session = Depends(get_session)):
- db_hero = Hero.model_validate(hero)
- session.add(db_hero)
- session.commit()
- session.refresh(db_hero)
- return db_hero
-
-
-@app.get("/heroes/", response_model=List[HeroPublic])
-def read_heroes(
- session: Session = Depends(get_session),
- offset: int = 0,
- limit: int = Query(default=100, le=100),
-):
- heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
- return heroes
-
-
-@app.get("/heroes/{hero_id}", response_model=HeroPublic)
-def read_hero(hero_id: int, session: Session = Depends(get_session)):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- return hero
-
-
-@app.patch("/heroes/{hero_id}", response_model=HeroPublic)
-def update_hero(
- hero_id: int, hero: HeroUpdate, session: Session = Depends(get_session)
-):
- hero_db = session.get(Hero, hero_id)
- if not hero_db:
- raise HTTPException(status_code=404, detail="Hero not found")
- hero_data = hero.model_dump(exclude_unset=True)
- hero_db.sqlmodel_update(hero_data)
- session.add(hero_db)
- session.commit()
- session.refresh(hero_db)
- return hero_db
-
-
-@app.delete("/heroes/{hero_id}")
-def delete_hero(hero_id: int, session: Session = Depends(get_session)):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- session.delete(hero)
- session.commit()
- return {"ok": True}
diff --git a/docs_src/sql_databases/tutorial002_an.py b/docs_src/sql_databases/tutorial002_an.py
deleted file mode 100644
index 15e3d7c3a..000000000
--- a/docs_src/sql_databases/tutorial002_an.py
+++ /dev/null
@@ -1,104 +0,0 @@
-from typing import List, Union
-
-from fastapi import Depends, FastAPI, HTTPException, Query
-from sqlmodel import Field, Session, SQLModel, create_engine, select
-from typing_extensions import Annotated
-
-
-class HeroBase(SQLModel):
- name: str = Field(index=True)
- age: Union[int, None] = Field(default=None, index=True)
-
-
-class Hero(HeroBase, table=True):
- id: Union[int, None] = Field(default=None, primary_key=True)
- secret_name: str
-
-
-class HeroPublic(HeroBase):
- id: int
-
-
-class HeroCreate(HeroBase):
- secret_name: str
-
-
-class HeroUpdate(HeroBase):
- name: Union[str, None] = None
- age: Union[int, None] = None
- secret_name: Union[str, None] = None
-
-
-sqlite_file_name = "database.db"
-sqlite_url = f"sqlite:///{sqlite_file_name}"
-
-connect_args = {"check_same_thread": False}
-engine = create_engine(sqlite_url, connect_args=connect_args)
-
-
-def create_db_and_tables():
- SQLModel.metadata.create_all(engine)
-
-
-def get_session():
- with Session(engine) as session:
- yield session
-
-
-SessionDep = Annotated[Session, Depends(get_session)]
-app = FastAPI()
-
-
-@app.on_event("startup")
-def on_startup():
- create_db_and_tables()
-
-
-@app.post("/heroes/", response_model=HeroPublic)
-def create_hero(hero: HeroCreate, session: SessionDep):
- db_hero = Hero.model_validate(hero)
- session.add(db_hero)
- session.commit()
- session.refresh(db_hero)
- return db_hero
-
-
-@app.get("/heroes/", response_model=List[HeroPublic])
-def read_heroes(
- session: SessionDep,
- offset: int = 0,
- limit: Annotated[int, Query(le=100)] = 100,
-):
- heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
- return heroes
-
-
-@app.get("/heroes/{hero_id}", response_model=HeroPublic)
-def read_hero(hero_id: int, session: SessionDep):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- return hero
-
-
-@app.patch("/heroes/{hero_id}", response_model=HeroPublic)
-def update_hero(hero_id: int, hero: HeroUpdate, session: SessionDep):
- hero_db = session.get(Hero, hero_id)
- if not hero_db:
- raise HTTPException(status_code=404, detail="Hero not found")
- hero_data = hero.model_dump(exclude_unset=True)
- hero_db.sqlmodel_update(hero_data)
- session.add(hero_db)
- session.commit()
- session.refresh(hero_db)
- return hero_db
-
-
-@app.delete("/heroes/{hero_id}")
-def delete_hero(hero_id: int, session: SessionDep):
- hero = session.get(Hero, hero_id)
- if not hero:
- raise HTTPException(status_code=404, detail="Hero not found")
- session.delete(hero)
- session.commit()
- return {"ok": True}
diff --git a/docs_src/static_files/__init__.py b/docs_src/static_files/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/static_files/tutorial001.py b/docs_src/static_files/tutorial001_py39.py
similarity index 100%
rename from docs_src/static_files/tutorial001.py
rename to docs_src/static_files/tutorial001_py39.py
diff --git a/docs_src/sub_applications/__init__.py b/docs_src/sub_applications/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/sub_applications/tutorial001.py b/docs_src/sub_applications/tutorial001_py39.py
similarity index 100%
rename from docs_src/sub_applications/tutorial001.py
rename to docs_src/sub_applications/tutorial001_py39.py
diff --git a/docs_src/templates/__init__.py b/docs_src/templates/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/templates/static/__init__.py b/docs_src/templates/static/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/templates/templates/__init__.py b/docs_src/templates/templates/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/templates/tutorial001.py b/docs_src/templates/tutorial001_py39.py
similarity index 100%
rename from docs_src/templates/tutorial001.py
rename to docs_src/templates/tutorial001_py39.py
diff --git a/docs_src/using_request_directly/__init__.py b/docs_src/using_request_directly/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs_src/using_request_directly/tutorial001.py b/docs_src/using_request_directly/tutorial001_py39.py
similarity index 100%
rename from docs_src/using_request_directly/tutorial001.py
rename to docs_src/using_request_directly/tutorial001_py39.py
diff --git a/docs_src/websockets/tutorial001.py b/docs_src/websockets/tutorial001_py39.py
similarity index 100%
rename from docs_src/websockets/tutorial001.py
rename to docs_src/websockets/tutorial001_py39.py
diff --git a/docs_src/websockets/tutorial002_an.py b/docs_src/websockets/tutorial002_an.py
deleted file mode 100644
index c838fbd30..000000000
--- a/docs_src/websockets/tutorial002_an.py
+++ /dev/null
@@ -1,93 +0,0 @@
-from typing import Union
-
-from fastapi import (
- Cookie,
- Depends,
- FastAPI,
- Query,
- WebSocket,
- WebSocketException,
- status,
-)
-from fastapi.responses import HTMLResponse
-from typing_extensions import Annotated
-
-app = FastAPI()
-
-html = """
-
-
-
-