fastapi tutorial - Githubissues

yeomko22 commented 2 years ago

FastAPI

starlette 객체를 바로 상속받는다.
starlette은 ASGI를 구현하는 python web framework이다. 그 자체로 사용도 가능하고, sdk로 사용도 가능하다.
fastapi는 이 starlette를 기반으로 한다.

class FastAPI(Starlette):
    ...

API 정의하기

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

앱 객체를 만든 뒤, 데코레이터를 이용해서 method, url을 등록해준다.
이 때 async를 붙여도 되고, 안붙여도 된다.
안붙이게 될 경우 그냥 synchronous하게 동작을 처리한다.

yeomko22 commented 2 years ago

Async, Await

modern python은 coroutine이라 불리는 개념을 이용해서 asynchronous 코드를 지원한다.

Asynchronous Code

asynchronous code란 컴퓨터나 프로그램이 코드의 한 지점에서 다른 어떤 작업이 수행되는 것을 기다리는 방법이 있다는 것을 의미한다.
가령 slow-file이라는 작업이 처리되도록 명령하고 그동안 다른 작업을 수행할 수 있는 것을 말한다.
이러한 작업들을 보통 I/O 작업이라 하며 아래와 같은 종류들이 있다.
- 클라이언트로부터 네트워크를 통해 데이터를 전달받는 작업
- 클라이언트로 네트워크를 통해 데이터를 전송하는 작업
- 디스크에 있는 파일을 읽어오는 작업
- 프로그램에 있는 데이터를 디스크에 쓰는 작업
- 외부 API 호출
- 데이터 베이스 작업
- 데이터 베이스 쿼리 등
반대의 개념으로 CPU bound 작업이 있으며 예시는 아래와 같다.
- 오디오, 이미지 처리
- 컴퓨터 비젼
- 머신러닝
- 딥 러닝
대부분의 작업 시간이 이 I/O 작업 대기 시간에 소요되는 것을 I/O bound한 작업이라고 표현한다.
동기 방식에서는 요청과 결과가 한 지점에서 일어난다. 결과가 리턴될 때까지 기다린다. 반면 비동기에서는 요청을 넣어준 뒤, 결과는 콜백함수를 통해서 받는다.

Concurrency

비동기 방식은 concurrency라고 불리기도 하며 이는 parallelism이랑 다르다.

async await

async def get_burgers(number: int):
    return burgers

@app.get('/burgers')
async def read_burgers():
    burgers = await get_burgers(2)
    return burgers

async 로 정의한 함수에서는 await를 쓸 수 있다.
await를 만나면 해당 함수를 실행시키고 결과가 오는 동안에 다른 작업을 하러 간다.
await를 붙여서 호출한 함수의 결과값이 리턴되면 원래의 루틴으로 돌아와서 나머지 작업을 수행한다.

yeomko22 commented 2 years ago

Path opeartion functions

async def 대신에 그냥 def를 쓰면 이는 직접 호출되는 대신 외부 쓰레드 풀에서 실행된다. 왜냐? 이 요청이 전체 서버를 block 할 수 있기 때문
path operation function이 blocking I/O를 포함하고 있는 케이스가 아니라면 async def를 사용해라.

yeomko22 commented 2 years ago

Path Parameter

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

url formatting으로 GET 메서드에 파라미터 전달이 가능
파라미터 뒤에 int 타이핑 추가 만으로 형식 검사 가능
리턴 값을 자세히 확인해보면 문자열이 아니라 숫자가 리턴된 것을 확인할 수 있다. 이는 즉, 문자열로 전달된 파라미터의 내용을 보고 형식 검사를 한 뒤, 타입 변환까지 해준 것이다. (pydantic 덕분! 땡큐!)

@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}

@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

고정 url은 가변 url 보다 위에 정의를 해주어야만 인식이 된다.

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
   ...

enum class를 만들어주고 파라미터에 타입을 enum으로 지정해주면 알아서 걸러준다. (너무 좋다...)

@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

이런 식으로 파일 경로를 파라미터로 받을 수 있다.
이는 openAPI의 규격에는 맞지 않지만 starlette의 기능을 직접 이용해서 가능케 한 것이다.
/files//home/johndoe/myfile.txt 이렇게 leading slash를 붙여서 전달해주어야 한다.

yeomko22 commented 2 years ago

Query Paramter

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

파라미터에 지정을 해놓으면 쿼리 파라미터 전달이 가능, 타입 지정과 기본값 지정도 가능

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Optional[str] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

기본적으로 fastAPI는 기본값이 지정된 파라미터는 optional로 인식함
그렇지만 optiional한 파라미터는 Optional[str]이라고 명시를 해주는 것이 디버깅에 편리하다.

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Optional[str] = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

short 파라미터에 1, True, true, yes, on 등의 문자열을 넣어도 모두 python bool 타입으로 형변환을 해준다.

@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: Optional[str] = None, short: bool = False
):
...

여러 path parameter와 query parameter를 함께 사용해도 무방하다.

yeomko22 commented 2 years ago

Request Body

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

@app.post("/items/")
async def create_item(item: Item):
    return item

pydantic의 BaseModel을 이용해서 데이터를 담을 모델을 만들어서 파라미터의 타입으로 지정해준다.
자동으로 타입 검사를 실행해준다.

yeomko22 commented 2 years ago

Query Parameters and String validation

from fastapi import Query

@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, min_length=3, max_length=50, regex="^fixedquery$")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

fastapi의 Query라는 객체를 이용해서 파라미터의 글자 수 제한을 적용할 수 있다.
```
@app.get("/items/")
async def read_items(q: str = Query(..., min_length=3)):
...
```

만일 required로 설정하고 싶다면 Query 객체 생성 시에 첫번째 파라미터를 ... 으로 두어라

@app.get("/items/")
async def read_items(
q: Optional[str] = Query(
    None,
    title="Query string",
    description="Query string for the items to search in the database that have a good match",
    min_length=3,
)
):

Query 객체 생성 시 파라미터를 전달해서 title, description 등의 해당 파라미터에 대한 메타데이터를 지정할 수도 있다.

yeomko22 commented 2 years ago

Path Parameters and Numeric Validation

Query 객체로 query 타입의 파라미터에 validation과 metadata를 추가할 수 있었던 것 처럼 Path 객체를 이용하면 path 타입 파라미터에 여러 제약이나 정보를 추가할 수 있다.
Path 사용 시에는 항상 required로 지정해주어라.

숫자 validation의 경우 gt (greater) le (less)를 적용할 수 있다.

@app.get("/items/{item_id}")
async def read_items(
*,
item_id: int = Path(..., title="The ID of the item to get", gt=0, le=1000),
q: str,
):

yeomko22 commented 2 years ago

Query, Path, Body

web api가 파라미터를 전달받을 수 있는 방법은 3가지이다.
url path로 받는 방법, url query로 받는 방법, body로 받는 방법이다.
각각에 validation, metadata 추가는 fastapi에서 제공하는 Query, Path, Body 객체를 이용하면 된다.

yeomko22 commented 2 years ago

Body - Field

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str
    description: Optional[str] = Field(
        None, title="The description of the item", max_length=300
    )
    price: float = Field(..., gt=0, description="The price must be greater than zero")
    tax: Optional[float] = None

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(..., embed=True)):
    results = {"item_id": item_id, "item": item}
    return results

즉 body를 통해서 전달받는 json 형식의 데이터에 validation을 추가하고 싶다면 pydantic의 BaseModel 정의 단에 Field를 적용해라.
이를 통해서 최대 길이, title, description 등의 정보를 추가할 수 있다.
Field는 Query, Path, Body와 유사하게 동작한다.
사실 Field, Query, Path, Body는 모두 Param의 subclass들이다. 이는 잠시 뒤 살펴본다.

yeomko22 commented 2 years ago

Body - Nested Model

from typing import Optional, Set

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
    tags: Set[str] = set()

model에 멤버 변수로 Set을 지정하면 중복 데이터가 포함된 파라미터가 들어오더라도 알아서 삭제해준다.

from pydantic import BaseModel, HttpUrl

class Image(BaseModel):
    url: HttpUrl
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
    tags: Set[str] = []
    image: Optional[Image] = None

이런 식으로 Item이라는 모델이 Image라는 모델의 list를 포함할 수 있도록 설정할 수도 있다.
pydantic을 잘 뒤져보면 HttpUrl 과 같이 특수 형식에 대한 타입 검사를 자동으로 수행해주는 구현체들이 있다. 잘 활용할 것

yeomko22 commented 2 years ago

Declare Request Example Data

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

    class Config:
        schema_extra = {
            "example": {
                "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

model 안쪽에 Config 클래스와 함께 schema_extra, example을 지정하면 문서에 모델의 예시를 남길 수 있다. (쓸 일이 있을까 싶긴함)

혹은 아래처럼 Field를 사용해서 example을 남길 수 있다.

class Item(BaseModel):
name: str = Field(..., example="Foo")
description: Optional[str] = Field(None, example="A very nice Item")
price: float = Field(..., example=35.4)
tax: Optional[float] = Field(None, example=3.2)

yeomko22 commented 2 years ago

Extra Data Types

UUID
datetime.datetime (2008-09-15T15:53:00+05:00)
datetime.date(2008-09-15)
datetime.time(14:23:55.003)
datetime.timedelta
frozenset
bytes
Decimal

yeomko22 commented 2 years ago

Response Model

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    return item

response_model을 지정하면 문서의 response에 표기된다.

yeomko22 commented 2 years ago

Error Handling

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "There goes my error"},
        )
    return {"item": items[item_id]}

raise HTTPException 함수를 이용해서 에러 처리를 한다.
HTTPException 객체 안에 여러 파라미터를 넣어서 정보를 추가할 수 있다.

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )

@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"unicorn_name": name}

직접 custom exception class를 만들어주고, 이를 처리하는 handler를 만들어준 뒤, 예외 상황 발생 시 exception을 raise 해주면 된다.

yeomko22 / TIL

fastapi tutorial #98

FastAPI

API 정의하기

Async, Await

Asynchronous Code

Concurrency

async await

Path opeartion functions

Path Parameter

Query Paramter

Request Body

Query Parameters and String validation

Path Parameters and Numeric Validation

Query, Path, Body

Body - Field

Body - Nested Model

Declare Request Example Data

Extra Data Types

Response Model

Error Handling