diff --git a/.gitignore b/.gitignore index ef6364a9a..9275cde9c 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,7 @@ archive.zip # macOS .DS_Store + +# PDM additional files +.pdm-python +pdm.lock diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 8a5ea13e0..f81a935dd 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -341,6 +341,8 @@ extra: name: uk - українська мова - link: /ur/ name: ur - اردو + - link: /uz/ + name: uz - Ўзбек - link: /vi/ name: vi - Tiếng Việt - link: /yo/ diff --git a/docs/uz/docs/index.md b/docs/uz/docs/index.md new file mode 100644 index 000000000..c67519a2c --- /dev/null +++ b/docs/uz/docs/index.md @@ -0,0 +1,495 @@ +# FastAPI + + + +

+ FastAPI +

+

+ FastAPI frameworki, juda tez, o‘qish oson, tez kod yozish, production ga tayyor +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**Hujjatlar**: https://fastapi.tiangolo.com + +**Manba kodi**: https://github.com/fastapi/fastapi + +--- + +FastAPI — bu zamonaviy, tez (yuqori samaradorlikka ega), Python uchun API yaratishda ishlatiladigan web-framework bo‘lib, standart Python tip ko‘rsatkichlariga asoslanadi (type hintlar). + +Asosiy xususiyatlari: + +* **Tez**: Juda yuqori samaradorlik, **NodeJS** va **Go** bilan teng (Starlette va Pydantic tufayli). [Python uchun eng tez frameworklardan biri](#performance). +* **Tez kod yozish**: Funksiyalarni ishlab chiqish tezligini taxminan 200% dan 300% gacha oshiradi. * +* **Kamroq xatolik**: Inson (dasturchi) tomonidan yuzaga keladigan xatolarni taxminan 40% ga kamaytiradi. * +* **Intuitiv**: Ajoyib muharrir yordami. To‘ldirish har yerda. Kamroq vaqtni nosozliklarni tuzatishga sarflaysiz. +* **Oson**: Foydalanish va o‘rganish uchun qulay. Kamroq vaqt hujjatlarni o‘qishga ketadi. +* **Qisqa**: Kodni takrorlashni minimallashtiradi. Har bir parametr e’lonidan bir nechta imkoniyatlar. Kamroq xatolik. +* **Barqaror**: Ishlab chiqarishga tayyor kodga ega bo‘lasiz. Avtomatik interaktiv hujjatlar bilan. +* **Standartlarga asoslangan**: API uchun ochiq standartlarga asoslangan (va to‘liq mos): OpenAPI (ilgari Swagger nomi bilan tanilgan) va JSON Schema. + +* ishlab chiqarish ilovalarini yaratishda ichki dasturchilar jamoasida o‘tkazilgan testlar asosida baholangan. + +## Homiylar + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +Boshqa homiylar + +## Fikrlar + +"_[...] Men hozirda **FastAPI** dan juda ko‘p foydalanmoqdaman. [...] Aslida, uni jamoamdagi barcha **ML xizmatlari** uchun ishlatishni rejalashtiryapman. Ularning ba’zilari asosiy **Windows** mahsulotiga va ba’zilari **Office** mahsulotlariga integratsiya qilinmoqda._" + +
Kabir Khan - Microsoft (manba)
+ +--- + +"_Biz **FastAPI** kutubxonasini **REST** serverini ishga tushirish uchun qabul qildik, u orqali **bashoratlar** olish mumkin. [Ludwig uchun]_" + +
Piero Molino, Yaroslav Dudin va Sai Sumanth Miryala - Uber (manba)
+ +--- + +"_**Netflix** o‘zining **inqiroz boshqaruvi** orkestratsiya frameworki: **Dispatch** ni ochiq manba sifatida chiqarganini mamnuniyat bilan e’lon qiladi! [**FastAPI** yordamida yaratilgan]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (manba)
+ +--- + +"_Men **FastAPI** dan juda hayajondaman. Bu juda qiziqarli!_" + +
Brian Okken - Python Bytes podkast boshlovchisi (manba)
+ +--- + +"_Rostini aytsam, siz yaratgan narsa juda mustahkam va sayqallangan ko‘rinadi. Ko‘p jihatdan, bu men **Hug** bo‘lishini istagan narsam edi — kimdir bunday narsani yaratganini ko‘rib, ilhomlanaman._" + +
Timothy Crosley - Hug yaratuvchisi (manba)
+ +--- + +"_Agar siz **REST API** lar qurish uchun zamonaviy framework o‘rganmoqchi bo‘lsangiz, **FastAPI** ga qarang [...] Bu tez, ishlatish va o‘rganish oson [...]_" + +"_Biz **API** larimiz uchun **FastAPI** ga o‘tdik [...] Sizga yoqadi deb o‘ylayman [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI asoschilari - spaCy yaratuvchilari (manba) - (manba)
+ +--- + +"_Agar kimdir ishlab chiqarish uchun Python API yaratmoqchi bo‘lsa, men **FastAPI** ni tavsiya qilaman. Bu **chiroyli ishlab chiqilgan**, **foydalanish uchun oddiy** va **juda kengaytiriladigan** framework, u bizning API birinchi rivojlanish strategiyamizda asosiy komponentga aylandi va ko‘plab avtomatlashtirishlar va xizmatlarni, jumladan Virtual TAC Engineer’imizni boshqaradi._" + +
Deon Pillsbury - Cisco (manba)
+ +--- + +## **Typer**, CLI lar uchun FastAPI + + + +Agar siz web API o‘rniga terminalda ishlatiladigan CLI dastur yaratmoqchi bo‘lsangiz, **Typer** ga e’tibor bering. + +**Typer** — bu FastAPI ning kichik ukasi. U aynan **CLI lar uchun FastAPI** bo‘lishi uchun yaratilgan. ⌨️ 🚀 + +## Talablar + +FastAPI ulkanlar yelkasida turadi: + +* Starlette web tomoni uchun. +* Pydantic data part uchun. + +## O‘rnatish + +Virtual atrofni yarating va faollashtiring, so‘ng FastAPI ni o‘rnating: + +
+ +```console +$ pip install "fastapi[standard]" + +---> 100% +``` + +
+ +**Eslatma**: `"fastapi[standard]"` ni qo‘shtirnoq ichida yozing, shunda barcha terminallarda to‘g‘ri ishlaydi. + +## Misol + +### Yarating + +`main.py` fayl ni yarating pastdagi kod bilan: + +```Python +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+Yoki async def... ni ishlating. + +Agar sizni kodiz `async` / `await` asosiy so‘zlarni ishlatsa, `async def` ni ishlating: + +```Python hl_lines="9 14" +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +**E’tibor bering**: +Agar bilmasangiz, hujjatlardagi `async` va `await` haqida "Shoshilinchmisiz?" bo‘limiga qarang. + +
+ +### Uni ishga tushirish + +Serverni ishga tushirish uchun: + +
+ +```console +$ fastapi dev main.py + + ╭────────── 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 [2248755] using WatchFiles +INFO: Started server process [2248757] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` + +
+ +
+fastapi dev main.py... komanda haqida + +`fastapi dev` buyrug‘i sizning `main.py` faylingizni o‘qiydi, undagi **FastAPI** ilovasini aniqlaydi va Uvicorn yordamida serverni ishga tushiradi. + +Standart holatda, `fastapi dev` lokal ishlab chiqish uchun avtomatik qayta yuklash (auto-reload) rejimida ishga tushadi. + +Bu haqda batafsil ma’lumotni FastAPI CLI hujjatlarida o‘qishingiz mumkin. + +
+ +### Tekshirish + +Browser da http://127.0.0.1:8000/items/5?q=somequery ni oching. + +Shunga o'xshagan JSON javob ko'rasiz: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +Siz allaqachon quyidagi API ni yaratdingiz: + +* HTTP so‘rovlarini quyidagi _yo‘llar_ da qabul qiladi: `/` va `/items/{item_id}`. +* Har ikkala _yo‘l_ ham `GET` operatsiyalarini (HTTP _usullari_ deb ham ataladi) qabul qiladi. +* `/items/{item_id}` _yo‘li_ da `item_id` nomli _yo‘l parametri_ bor va u `int` bo‘lishi kerak. +* `/items/{item_id}` _yo‘li_ da ixtiyoriy `str` tipidagi _so‘rov parametri_ `q` mavjud. + +### Interaktiv API hujjatlar + +Endi http://127.0.0.1:8000/docs manziliga o'ting. + +Siz avtomatik interaktiv API hujjatlarini ( Swagger UI tomonidan taqdim etilgan) ko'rasiz: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Muqobil API hujjatlari + +Endi http://127.0.0.1:8000/redoc manziliga o'ting. + +Siz muqobil avtomatik hujjatlarni ( ReDoc tomonidan taqdim etilgan) ko'rasiz: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## Misolni yangilash + +Endi `main.py` faylini `PUT` so‘rovlaridan body (tanani) qabul qiladigan qilib o‘zgartiring. + +Body ni Pydantic yordamida, standart Python tiplari orqali e’lon qiling. + +```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} +``` + +`fastapi dev` serveri avtomatik tarzda qayta yuklanadi. + +### Interaktiv API hujjatlarini yangilash + +Endi http://127.0.0.1:8000/docs manziliga o'ting. + +* Interaktiv API hujjatlari avtomatik tarzda yangilanadi, yangi body ham ko‘rsatiladi: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* "Try it out" tugmasini bosing, bu sizga parametrlarni to‘ldirish va API bilan bevosita ishlash imkonini beradi: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* Keyin "Execute" tugmasini bosing, foydalanuvchi interfeysi sizning API’ga so‘rov yuboradi, parametrlarni jo‘natadi, natijalarni oladi va ekranda ko‘rsatadi: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### Muqobil API hujjatlarini yangilash + +Endi http://127.0.0.1:8000/redoc manziliga o'ting. + +* Muqobil hujjatlar ham yangi so‘rov parametri va body ni aks ettiradi: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Qisqacha takrorlash + +Xulosa qilib aytganda, siz **bir marta** parametrlar, body va boshqalar uchun turlarni funksiya parametrlarida e’lon qilasiz. + +Buni zamonaviy Python tiplari yordamida qilasiz. + +Yangi sintaksis, maxsus kutubxona metodlari yoki klasslarini o‘rganishingiz shart emas. + +Faqat oddiy **Python**. + +Masalan, `int` uchun: + +```Python +item_id: int +``` + +yoki qiyinroq `Item` model uchun: + +```Python +item: Item +``` + +...va o‘sha bitta bayonot bilan siz quyidagilarni olasiz: + +* Muharrir (editor) yordami, jumladan: + * Avto-to‘ldirish (completion). + * Tiplarni tekshirish (type checks). +* Ma’lumotlarni tekshirish (validation): + * Ma’lumotlar noto‘g‘ri bo‘lsa, avtomatik va aniq xatoliklar. + * Hattoki chuqur joylashgan (deeply nested) JSON obyektlari uchun ham tekshiruv. +* Kiruvchi ma’lumotlarni konvertatsiya qilish: tarmoqdan Python ma’lumotlari va turlariga o‘tkazish. Quyidagilardan o‘qish: + * JSON. + * Yo‘l (path) parametrlari. + * So‘rov (query) parametrlari. + * Cookies. + * Sarlavhalar (headers). + * Formalar. + * Fayllar. +* Chiquvchi ma’lumotlarni konvertatsiya qilish: Python ma’lumotlari va turlaridan tarmoq ma’lumotlariga (JSON ko‘rinishida) o‘tkazish: + * Python turlarini (`str`, `int`, `float`, `bool`, `list` va boshqalar) konvertatsiya qilish. + * `datetime` obyektlari. + * `UUID` obyektlari. + * Ma’lumotlar bazasi modellari. + * ...va yana ko‘plab turlar. +* Avtomatik interaktiv API hujjatlari, 2 ta muqobil foydalanuvchi interfeysi bilan: + * Swagger UI. + * ReDoc. + +--- + +Oldingi kod namunasi bo‘yicha, **FastAPI** quyidagilarni amalga oshiradi: + +* `GET` va `PUT` so‘rovlari uchun yo‘lda `item_id` mavjudligini tekshiradi. +* `GET` va `PUT` so‘rovlari uchun `item_id` ning turi `int` ekanligini tekshiradi. + * Agar u int bo‘lmasa, mijozga aniq va tushunarli xatolik ko‘rsatiladi. +* `GET` so‘rovlari uchun `q` nomli ixtiyoriy so‘rov parametrining mavjudligini tekshiradi (masalan, `http://127.0.0.1:8000/items/foo?q=somequery`). + * `q` parametri `= None` bilan e’lon qilinganligi sababli, u ixtiyoriy hisoblanadi. + * Agar `None` bo‘lmasa, u majburiy bo‘lardi (xuddi `PUT` da body majburiy bo‘lgani kabi). +* `/items/{item_id}` ga `PUT` so‘rovlari uchun body ni JSON sifatida o‘qiydi: + * Unda majburiy `name` atributi borligini va u `str` bo‘lishi kerakligini tekshiradi. + * Majburiy `price` atributi borligini va u `float` bo‘lishi kerakligini tekshiradi. + * Ixtiyoriy `is_offer` atributi borligini va u (agar mavjud bo‘lsa) `bool` bo‘lishi kerakligini tekshiradi. + * Bularning barchasi chuqur joylashgan (deeply nested) JSON obyektlari uchun ham ishlaydi. +* Avtomatik tarzda JSON ga va JSON dan konvertatsiya qiladi. +* Hammasini OpenAPI yordamida hujjatlashtiradi, bu quyidagilar uchun ishlatilishi mumkin: + * Interaktiv hujjatlash tizimlari. + * Ko‘plab dasturlash tillari uchun avtomatik mijoz kodi generatsiyasi tizimlari. +* To‘g‘ridan-to‘g‘ri 2 ta interaktiv hujjatlash web interfeysini taqdim etadi. + +--- + +Biz faqat yuzaki ko‘rib chiqdik, lekin siz allaqachon hammasi qanday ishlashini tushundingiz. + +Quyidagi qatorni o‘zgartirib ko‘ring: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...bu joyni: + +```Python + ... "item_name": item.name ... +``` + +...quyidagiga o‘zgartiring: + +```Python + ... "item_price": item.price ... +``` + +...va muharriringiz atributlarni avtomatik to‘ldirishini va ularning turlarini bilishini ko‘ring: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +Ko‘proq imkoniyatlarni o‘z ichiga olgan to‘liqroq misol uchun Tutorial - User Guide bo‘limiga qarang. + +**Ogohlantirish (spoiler)**: tutorial - foydalanuvchi qo‘llanmasida quyidagilar mavjud: + +* **Parametrlarni** boshqa joylardan e’lon qilish: **headerlar**, **cookie**lar, **forma maydonlari** va **fayllar**. +* **Validatsiya cheklovlarini** o‘rnatish, masalan: `maximum_length` yoki `regex`. +* Juda qulay va kuchli **Dependency Injection** tizimi. +* Xavfsizlik va autentifikatsiya, jumladan **OAuth2** va **JWT tokenlar**, hamda **HTTP Basic** autentifikatsiyasi. +* **Pydantic** yordamida **chuqur joylashgan JSON modellari**ni e’lon qilishning ilg‘or (lekin oson) usullari. +* **GraphQL** integratsiyasi: Strawberry va boshqa kutubxonalar yordamida. +* Ko‘plab qo‘shimcha imkoniyatlar (Starlette tufayli), jumladan: + * **WebSocket**lar + * HTTPX va `pytest` asosidagi juda oson testlar + * **CORS** + * **Cookie Session**lar + * ...va boshqalar. + +## Performance + +Mustaqil TechEmpower benchmark natijalari shuni ko‘rsatadiki, **FastAPI** ilovalari Uvicorn ostida eng tez ishlaydigan Python frameworklaridan biri hisoblanadi, faqat Starlette va Uvicorn (FastAPI ichida ishlatiladi) dan keyin turadi. (*) + +Batafsil ma’lumot uchun Benchmarks bo‘limiga qarang. + +## Bog‘liqliklar + +FastAPI Pydantic va Starlette kutubxonalariga bog‘liq. + +### `standard` bog‘liqliklar + +Agar siz FastAPI ni `pip install "fastapi[standard]"` orqali o‘rnatsangiz, u `standard` guruhidagi ixtiyoriy bog‘liqliklar bilan birga keladi: + +Pydantic tomonidan ishlatiladi: + +* email-validator — email manzillarini tekshirish uchun. + +Starlette tomonidan ishlatiladi: + +* httpx — agar siz `TestClient` dan foydalanmoqchi bo‘lsangiz, talab qilinadi. +* jinja2 — standart shablon konfiguratsiyasidan foydalanish uchun kerak bo‘ladi. +* python-multipart — forma "parsing" ni qo‘llab-quvvatlash uchun, `request.form()` bilan ishlatiladi. + +FastAPI / Starlette tomonidan ishlatiladi: + +* uvicorn — ilovangizni yuklab, serverda ishga tushirish uchun. Bu `uvicorn[standard]` ni o‘z ichiga oladi, u yuqori samaradorlik uchun kerakli ba’zi bog‘liqliklarni (masalan, `uvloop`) o‘z ichiga oladi. +* `fastapi-cli` — `fastapi` buyrug‘ini taqdim etadi. + +### `standard` bog‘liqliklarsiz + +Agar siz `standard` ixtiyoriy bog‘liqliklarni o‘rnatishni xohlamasangiz, `pip install fastapi` buyrug‘i orqali o‘rnating (`pip install "fastapi[standard]"` o‘rniga). + +### Qo‘shimcha ixtiyoriy bog‘liqliklar + +Qo‘shimcha o‘rnatishingiz mumkin bo‘lgan ba’zi bog‘liqliklar mavjud. + +Qo‘shimcha ixtiyoriy Pydantic bog‘liqliklari: + +* pydantic-settings — sozlamalarni boshqarish uchun. +* pydantic-extra-types — Pydantic bilan ishlatish uchun qo‘shimcha turlar. + +Qo‘shimcha ixtiyoriy FastAPI bog‘liqliklari: + +* orjson — agar siz `ORJSONResponse` dan foydalanmoqchi bo‘lsangiz, talab qilinadi. +* ujson — agar siz `UJSONResponse` dan foydalanmoqchi bo‘lsangiz, talab qilinadi. + +## Litsenziya + +Ushbu loyiha MIT litsenziyasi shartlariga muvofiq litsenziyalangan. diff --git a/docs/uz/mkdocs.yml b/docs/uz/mkdocs.yml new file mode 100644 index 000000000..de18856f4 --- /dev/null +++ b/docs/uz/mkdocs.yml @@ -0,0 +1 @@ +INHERIT: ../en/mkdocs.yml