tiangolo.fastapi/docs/ka/docs/index.md

hide
[navigation]

FastAPI ფრეიმვორქი, მაღალი წარმადობა, ასათვისებლად მარტივი, ეფექტური, წარმოებაში ჩაშვებისათვის გამზადებული

---

დოკუმენტაცია: https://fastapi.tiangolo.com

პროგრამული კოდი: https://github.com/tiangolo/fastapi

---

FastAPI არის თანამედროვე, სწრაფი (მაღალი წარმადობის მქონე), Python-ზე დაფუძნებული ვებფრეიმვორქი, რომელიც იყენებს Python-ის სტანდარტულ ტიპთა ანოტაციებს და საშუალებას გვაძლევს შევქმნათ API-ები.

მისი ძირითადი მახასიათებლები გახლავთ:

• სისწრაფე: NodeJS-ისა და Go-ს მსგავსად აქვს ძალიან მაღალი წარმადობა (რასაც Starlette-ს და Pydantic-ს უნდა ვუმადლოდეთ). ერთ-ერთი უსწრაფესი ფრეიმვორქია Python-ის არსებულ ფრეიმვორქებს შორის.
• ეფექტურობა: დეველოპმენტის პროცესს აჩქარებს დაახლოებით 200-300 პროცენტით. *
• ნაკლები პროგრამული ხარვეზი: ადამიანის (დეველოპერის) მიერ გამოწვეული ხარვეზების ალბათობას ამცირებს დაახლოებით 40 პროცენტით. *
• ინტუიციურობა: შესანიშნავი თავსებადობა ტექსტურ რედაქტორებთან. კოდის ავტოდასრულების ფუნქციონალი ხელმისაწვდომია სრული მასშტაბით. ნაკლებ დროს დახარჯავთ ხარვეზების აღმოფხვრაში.
• სიმარტივე: ტექნოლოგია შემუშავებულია იმგვარად, რომ მარტივად გამოსაყენებელი და ასათვისებელი იყოს. დოკუმენტაციის კითხვაში ნაკლებ დროს დახარჯავთ.
• კომპაქტურობა: კოდის დუბლიკაციის საჭიროება მინიმუმამდეა დაყვანილი. თითოეული პარამეტრის განსაზღვრით აქტიურდება მრავალი ფუნქციონალი. პროგრამული ხარვეზების წარმოქმნის ალბათობა მინიმუმამდეა დაყვანილი.
• მდგრადობა: მიიღებთ წარმოებაში ჩაშვებისათვის გამზადებულ კოდს. ამას გარდა, მიიღებთ ავტომატურად გენერირებულ ინტერაქციულ დოკუმენტაციას.
• სტანდარტებზე დაფუძნებულობა: დაფუძნებულია (და სრულად თავსებადია) API-იებისთვის განსაზღვრულ ღია სტანდარტებზე: OpenAPI (ადრე ცნობილი იყო, როგორც Swagger) და JSON Schema.

* ზემოთ მოცემული შეფასებები ეფუძნება წარმოებაში ჩაშვებულ (რეალურ) აპლიკაციებზე მომუშავე შიდა დეველოპმენტის გუნდის მიერ ჩატარებულ ტესტებს.

სპონსორები

{% if sponsors %} {% for sponsor in sponsors.gold -%} {% endfor -%} {%- for sponsor in sponsors.silver -%} {% endfor %} {% endif %}

სხვა სპონსორები

მოსაზრებები

"[...] ბოლო დროს, ძალიან ხშირად ვიყენებ FastAPI-ს. [...] სიმართლე გითხრათ, მის გამოყენებას ვაპირებ ყველა იმ ML სერვისისთვის Microsoft-ში, რაზეც კი ჩემი გუნდი მუშაობს. აღნიშნული სერვისებიდან ზოგიერთი ინტეგრირებულია Windows-ის ბირთვში, ზოგი კი — Office-ის პროდუქტებში."

Kabir Khan - Microsoft (ref)

---

"ჩვენ გამოვიყენეთ FastAPI ბიბლიოთეკა REST სერვერის შესაქმნელად, რომლის დანიშნულება გახლავთ სხვადასხვა პროგნოზების გაკეთება. [Ludwig-ისთვის]"

Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)

---

"Netflix-ის სახელით მოხარული ვარ გაცნობოთ ჩვენი კრიზისის მართვის ორკესტრაციის სისტემის, Dispatch-ის წყაროს ღია რელიზის შესახებ! [რომელიც შექმნილია FastAPI-ის გამოყენებით]"

Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)

---

"FastAPI-ით ცამდე აღფრთოვანებული ვარ. მისი გამოყენება ძალიან სახალისოა!"

Brian Okken - Python Bytes podcast host (ref)

---

"გულწრფელად გეუბნებით, თქვენი ნამუშევარი ძალიან სანდოდ და დახვეწილად გამოიყურება. სწორედ ეს არის ის, რაც მინდოდა Hug-ი ყოფილიყო — მართლაც შთამაგონებელია იმის დანახვა, რომ ვიღაცამ შეძლო ამის შექმნა."

Timothy Crosley - Hug creator (ref)

---

"თუ თანამედროვე ფრეიმვორქს ეძებთ, რომლითაც REST API-ების შექმნაა შესაძლებელი, გადახედეთ FastAPI-ს [...] იგი არის სწრაფი, მარტივად გამოსაყენებელი და ადვილად შესასწავლი [...]"

"ჩვენ გადავაწყვეთ ჩვენი API-ები FastAPI-ზე [...] ვფიქრობ, აღნიშნული ფრეიმვორქი გულგრილს არავის დატოვებს [...]"

Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)

---

"თუ ვინმე აპირებს შექმნას Python-ზე დაფუძნებული, წარმოებაში ჩასაშვებად ვარგისი API-ი, FastAPI-ის გამოყენებას ვურჩევ. ეს არის დახვეწილი, მარტივად გამოსაყენებელი და მასშტაბირებადი ტექნოლოგია. იგი გახდა API-ების შემუშავების ჩვენეული სტრატეგიის ქვაკუთხედი და სწორედ მისი გამოყენებითაა შემუშავებული ჩვენი არაერთი ავტომატიზაციის სისტემა და სერვისები, მათ შორის ჩვენი ვირტუალური TAC ინჟინერი."

Deon Pillsbury - Cisco (ref)

---

Typer: ბრძანებათა სტრიქონის FastAPI

თუკი მუშაობთ CLI აპლიკაციაზე, რომელიც ვებ API-ის ნაცვლად გამოყენებულ იქნება ტერმინალში, თვალი შეავლეთ Typer-ს.

Typer-ი არის FastAPI-ის პატარა ძამიკო. იგი ჩაფიქრებულია, როგორც FastAPI ბრძანებათა სტრიქონისათვის. ⌨️ 🚀

მოთხოვნები

FastAPI მხრებზე შემოსდგომია ისეთ გიგანტებს, როგორებიცაა:

• Starlette: ვების ნაწილში.
• Pydantic: მონაცემების ნაწილში.

ინსტალაცია

$ pip install fastapi

---> 100%

მაგალითი

შევქმნათ

• შექმენით main.py ფაილი შემდეგი შიგთავსით:

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}

ან გამოიყენეთ async def...

თუ თქვენი კოდი იყენებს async / await კონსტრუქციას, გამოიყენეთ async def:

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}

შენიშვნა:

თუ თქვენ ჯერ არ ხართ გარკვეული აღნიშნულ საკითხში, async-ისა და await-ის შესახებ დოკუმენტაციაში გადახედეთ განყოფილებას, სათაურით: „გეჩქარებათ?“.

გავუშვათ

გაუშვით სერვერი შემდეგი ბრძანებით:

$ 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 ბრძანების შესახებ...

fastapi dev ბრძანება კითხულობს თქვენს main.py ფაილს, მასში FastAPI აპლიკაციას აიდენტიფიცირებს და Uvicorn-ის გამოყენებით უშვებს სერვერს.

ნაგულისხმევად, ლოკალური დეველოპმენტისთვის, fastapi dev ბრძანებით გაშვებული სერვერისთვის აქტივირებული იქნება ავტოგადატვირთვის ფუნქცია.

ამ საკითხთან დაკავშირებით დამატებითი ინფორმაცია შეგიძლიათ წაიკითხოთ FastAPI CLI-ის დოკუმენტაციაში.

შევამოწმოთ

ბრაუზერში გახსენით შემდეგი ბმული: http://127.0.0.1:8000/items/5?q=somequery.

დაინახავთ JSON ფორმატის მქონე მონაცემს:

{"item_id": 5, "q": "somequery"}

ამგვარად, თქვენ უკვე შექმენით API, რომელიც:

• იღებს HTTP მოთხოვნებს შემდეგ მისამართებზე: / და /items/{item_id}.
• ორივე მისამართი ამუშავებს GET ოპერაციას (ასევე ცნობილია, როგორც HTTP მეთოდი).
• /items/{item_id} მისამართს გააჩნია მარშრუტის პარამეტრი item_id, რომელიც უნდა იყოს მთელი რიცხვის (int) ტიპის.
• /items/{item_id} მისამართი შეიცავს სტრიქონის (str) ტიპის არასავალდებულო q საძიებო (query) პარამეტრს.

ინტერაქციული API დოკუმენტაცია

გახსენით თქვენი ბრაუზერი და შედით ბმულზე: http://127.0.0.1:8000/docs.

დაინახავთ ავტომატურად გენერირებულ ინტერაქციულ API დოკუმენტაციას (რომელიც უზრუნველყოფილია Swagger UI-ის მიერ):

ალტერნატიული API დოკუმენტაცია

ბრაუზერში გახსენით შემდეგი ბმული: http://127.0.0.1:8000/redoc.

დაინახავთ ალტერნატიულ ავტომატურად გენერირებულ დოკუმენტაციას (რომელიც უზრუნველყოფილია ReDoc-ის მიერ):

გაუმჯობესების მაგალითი

მოდით, შევცვალოთ main.py ფაილის შიგთავსი იმგვარად, რომ PUT ოპერაციით შევძლოთ მონაცემების მიღება.

მოვახდინოთ მოთხოვნის შიგთავსის პროტოტიპის დეკლარაცია Python-ის სტანდარტული ტიპების გამოყენებით. ამ შესაძლებლობას Pydantic-ს უნდა ვუმადლოდეთ.

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 ბრძანებით გაშვებული სერვერი, წესით და რიგით, ავტომატურად გადაიტვირთება.

გავაუმჯობესოთ ინტერაქციული API დოკუმენტაცია

ბრაუზერში გახსენით შემდეგი ბმული: http://127.0.0.1:8000/docs.

• ინტერაქციული API დოკუმენტაცია ავტომატურად განახლდება და ახლად დამატებული შიგთავსის პროტოტიპიც გამოჩნდება:

• დააწკაპუნეთ „Try it out“ ღილაკზე. ეს საშუალებას მოგცემთ, ხელით გაწეროთ პარამეტრების მნიშვნელობები და API-სთან უშუალო ინტერაქციით დაკავდეთ:

• შემდგომ ამისა, დააწკაპუნეთ „Execute“ ღილაკზე, რითაც თქვენ მიერ გახსნილი ინტერფეისი დაუკავშირდება API-ს, გაგზავნის თქვენ მიერ განსაზღვრულ პარამეტრებს, მიიღებს მოთხოვნის შედეგებს და გამოიტანს ეკრანზე:

გავაუმჯობესოთ ალტერნატიული API დოკუმენტაცია

ახლა კი, ბრაუზერში გახსენით შემდეგი ბმული: http://127.0.0.1:8000/redoc.

• ახლად დამატებული საძიებო პარამეტრი და შიგთავსის პროტოტიპი ალტერნატიულ დოკუმენტაციაშიც პოვებს ასახვას:

შეჯამება

ამრიგად, პარამეტრების, შიგთავსის პროტოტიპებისა და სხვა ტიპების დეკლარირებას ახორციელებთ ერთჯერადად. როგორც ფუნქციისათვის პარამეტრების განსაზღვრისას ხდება.

ამას აკეთებთ Python-ის თანამედროვე, სტანდარტული ტიპების გამოყენებით.

არ გჭირდებათ რომელიმე ცალკეული ბიბლიოთეკისთვის დამახასიათებელი განსხვავებული სინტაქსის, მეთოდების ან კლასების შესწავლა.

იყენებთ მხოლოდ და მხოლოდ სტანდარტულ Python-ს.

მაგალითისათვის, int-ის შემთხვევაში:

item_id: int

ან შედარებით რთული Item მოდელისთვის:

item: Item

...და ამ ერთი დეკლარაციით თქვენ მიიღებთ:

• რედაქტორის მხარდაჭერას. მათ შორის:
  • კოდის ავტოდასრულებას.
  • ტიპთა ვალიდურობის შემოწმებას.
• მონაცემთა ვალიდაციას:
  • ავტომატურად გენერირებულ და მარტივად გასაგებ ცდომილების შეტყობინებებს, როდესაც მონაცემები ვალიდური არ იქნება.
  • ვალიდაციას თუნდაც უკიდურესად კომპლექსური (მაგ.: მრავალშრიანი) JSON მონაცემებისათვის.
• შემავალ მონაცემთა გარდაქმნას: ქსელიდან შემომავალი მონაცემების გადათარგმნას Python-ისთვის გასაგებ მონაცემებად და ტიპებად. შესაძლებელია შემდეგი სახის მონაცემების წაკითხვა და გარდაქმნა:
  • JSON.
  • მარშრუტის (Path) პარამეტრები.
  • საძიებო (Query) პარამეტრები.
  • Cookie-ები.
  • თავსართები (Headers).
  • ფორმები.
  • ფაილები.
• გამომავალ მონაცემთა გარდაქმნას: Python-ის მონაცემებისა და ტიპების გადათარგმნას ქსელურ მონაცემებად (JSON-ში). შესაძლებელია შემდეგი სახის მონაცემების გარდაქმნა:
  • Python-ის ტიპები (str, int, float, bool, list და სხვ.).
  • datetime ობიექტები.
  • UUID ობიექტები.
  • მონაცემთა ბაზის მოდელები.
  • ...და მრავალი სხვა.
• ავტომატურად გენერირებულ ინტერაქციულ API დოკუმენტაციას, რომელიც მოიცავს 2 ალტერნატიულ ინტერფეისს. ესენია:
  • Swagger UI.
  • ReDoc.

---

მოდით, მივუბრუნდეთ წინა მაგალითს და გავაანალიზოთ, რას და როგორ გააკეთებს FastAPI:

• GET და PUT ოპერაციებისათვის შეამოწმებს, არის თუ არა item_id პარამეტრი მითითებული მისამართში.
• GET და PUT ოპერაციებისათვის გადაამოწმებს, არის თუ არა item_id პარამეტრი int ტიპის.
  • თუ ეს ასე არ იქნება, კლიენტი იხილავს გამოსადეგ, მარტივად გასაგებ ცდომილების შეტყობინებას.
• GET ოპერაციებისათვის შეამოწმებს, არის თუ არა მისამართში წარმოდგენილი არასავალდებულო საძიებო (query) პარამეტრი, სახელად q (მაგ.: http://127.0.0.1:8000/items/foo?q=somequery).
  • ვინაიდან q პარამეტრი კოდში განსაზღვრულია = None ბოლოსართით, იგი არასავალდებულოა.
  • None-ის არარსებობის შემთხვევაში, იგი იქნებოდა სავალდებულო (მსგავსად მოთხოვნის შიგთავსისა PUT ოპერაციის შემთხვევაში).
• /items/{item_id} მისამართზე PUT ოპერაციისას, წაიკითხავს მოთხოვნის შიგთავსს, როგორც JSON ფორმატის მქონე მონაცემს. ამასთან:
  • შეამოწმებს, არის თუ არა განსაზღვრული str ტიპის სავალდებულო name ატრიბუტი.
  • შეამოწმებს, არის თუ არა განსაზღვრული float ტიპის სავალდებულო price ატრიბუტი.
  • შეამოწმებს, მოთხოვნის შიგთავსში არის თუ არა წარმოდგენილი bool ტიპის არასავალდებულო is_offer ატრიბუტი.
  • ყველაფერი ეს იმუშავებს ნებისმიერი სახის (მაგ.: მრავალშრიანი) JSON მონაცემისათვის.
• ავტომატურად გარდაქმნის JSON-ს სხვა ფორმატის მქონე მონაცემად და პირიქით.
• OpenAPI-ით მოახდენს ყველაფრის დოკუმენტირებას, რაც გამოსადეგი იქნება:
  • ინტერაქციული დოკუმენტაციის სისტემებისათვის.
  • კლიენტის კოდის ავტომატიზებული გენერირების სისტემებისათვის სხვადასხვა ენაში.
• უშუალოდ უზრუნველყოფს 2 ალტერნატიული ინტერაქციული დოკუმენტაციის ვებინტერფეისის არსებობას.

---

ჯერჯერობით ჩვენ რაც განვიხილეთ, მხოლოდ და მხოლოდ ზედაპირია აისბერგისა, მაგრამ, ასე თუ ისე, ალბათ გაიაზრეთ ამ ყველაფრის მუშაობის ზოგადი პრინციპი.

სცადეთ შემდეგ ხაზში ცვლილების შეტანა:

    return {"item_name": item.name, "item_id": item_id}

...ადრე:

        ... "item_name": item.name ...

...ახლა:

        ... "item_price": item.price ...

...და დააკვირდით, როგორ მოახდენს თქვენი ტექსტური რედაქტორი ატრიბუტების ავტოდასრულებას და მათი ტიპების იდენტიფიცირებას:

მეტად სრულყოფილი მაგალითის სანახავად, სადაც განხილული იქნება უფრო მეტი საკითხი, იხილეთ სახელმძღვანელო — მომხმარებლის გზამკვლევი.

გაფრთხილება სპოილერის შესახებ: მომხმარებლის გზამკვლევი მოიცავს შემდეგ საკითხებს:

• პარამეტრების დეკლარირება სხვა წყაროებიდან, როგორებიცაა: თავსართები (headers), cookie-ები, ფორმის ველები და ფაილები.
• შემმოწმებლებისათვის (ვალიდატორებისათვის) შეზღუდვების დაწესება, როგორებიცაა: maximum_length ან regex.
• ძალიან მძლავრი და მარტივად გამოსაყენებელი პაკეტების ინექცირების სისტემა.
• უსაფრთხოება და ავთენტიკაცია, მათ შორის OAuth2-ის მხარდაჭერა JWT ტოკენებით და HTTP Basic ავთენტიკაცია.
• მეტად სიღრმისეული (მაგრამ ისეთივე მარტივი) მეთოდოლოგიები კომპლექსური (მრავალშრიანი) JSON მოდელების დეკლარირებისათვის (მადლობა Pydantic-ს).
• GraphQL-ის ინტეგრირება Strawberry-სთან და სხვა ბიბლიოთეკებთან ერთად.
• არაერთი სხვა ფუნქციონალი (მადლობა Starlette-ს), როგორებიცაა:
  • ვებსოკეტები
  • HTTPX-ზე და pytest-ზე დაფუძნებული უმარტივესი ტესტები
  • CORS
  • Cookie სესიები
  • ...და მრავალი სხვა.

წარმადობა

TechEmpower-ის მიუკერძოებელი ტესტები ცხადყოფენ, რომ Uvicorn-ით გაშვებული FastAPI-ზე დაფუძნებული აპლიკაციები წარმოაჩენენ FastAPI-ს, როგორც ერთ-ერთ უსწრაფეს ფრეიმვორქს Python-ის არსებულ ფრეიმვორქებს შორის. მას წინ უსწრებენ მხოლოდ Starlette-ი და Uvicorn-ი (რომლებსაც, თავის მხრივ, FastAPI-ი იყენებს). (*)

ამ ყველაფრის უკეთ გასააზრებლად იხილეთ შემდეგი განყოფილება: წარმადობის ტესტები (Benchmarks).

პაკეტები

Pydantic-ის მიერ გამოიყენება შემდეგი პაკეტები:

• email_validator — მეილის ვალიდაციისათვის.
• pydantic-settings — პარამეტრების სამართავად.
• pydantic-extra-types — Pydantic-თან ერთად გამოყენებადი დამატებითი ტიპებისათვის.

Starlette-ის მიერ გამოიყენება შემდეგი პაკეტები:

• httpx — სავალდებულოა, თუკი გსურთ, რომ გამოიყენოთ TestClient-ი .
• jinja2 — სავალდებულოა, თუკი გსურთ, რომ გამოიყენოთ შაბლონის ნაგულისხმევი კონფიგურაცია.
• python-multipart — სავალდებულოა, თუკი გსურთ, რომ გქონდეთ ფორმების „პარსინგის“ შესაძლებლობა request.form()-ის გამოყენებით.

FastAPI / Starlette-ის მიერ გამოიყენება შემდეგი პაკეტები:

• uvicorn — სერვერისთვის, რომელიც ემსახურება თქვენი აპლიკაციის ჩატვირთვას და მუშაობას.
• fastapi-cli — უზრუნველყოფს fastapi ბრძანების ხელმისაწვდომობას.

fastapi-ის ინსტალირებისას, მასთან ერთად ინსტალირდება ზემოთ ჩამოთვლილი სტანდარტული პაკეტებიც.

დამატებითი არასავალდებულო პაკეტები გახლავთ:

• orjson — სავალდებულოა, თუკი გსურთ, რომ გამოიყენოთ ORJSONResponse-ი.
• ujson — სავალდებულოა, თუკი გსურთ, რომ გამოიყენოთ UJSONResponse-ი.

fastapi-slim

თუ არ გჭირდებათ დამატებითი არასავალდებულო სტანდარტული პაკეტები, fastapi-ის ნაცვლად დააინსტალირეთ fastapi-slim-ი.

როდესაც ინსტალაციას ახორციელებთ შემდეგი ბრძანებით:

pip install fastapi

...ინსტალირდება იგივე კოდი და პაკეტები, რაც დაინსტალირდებოდა შემდეგი ბრძანების გამოყენების შემთხვევაში:

pip install "fastapi-slim[standard]"

არასავალდებულო სტანდარტულ პაკეტებში იგულისხმება ზემოთ მოხსენიებული პაკეტები.

ლიცენზია

აღნიშნულ პროექტზე ვრცელდება MIT ლიცენზიით გათვალისწინებული წესები და პირობები.