Özel Response - HTML, Stream, File ve Diğerleri¶
🌐 Yapay Zekâ ve İnsanlar Tarafından Çeviri
Bu çeviri, insanlar tarafından yönlendirilen bir yapay zekâ ile oluşturuldu. 🤝
Orijinal anlamın yanlış anlaşılması ya da kulağa doğal gelmeme gibi hatalar içerebilir. 🤖
Yapay zekâ LLM'ini daha iyi yönlendirmemize yardımcı olarak bu çeviriyi iyileştirebilirsiniz.
Varsayılan olarakFastAPI, response'larıJSONResponse kullanarak döndürür.
Bunu,Doğrudan bir Response döndür bölümünde gördüğünüz gibi doğrudan birResponse döndürerek geçersiz kılabilirsiniz.
Ancak doğrudan birResponse döndürürseniz (veyaJSONResponse gibi herhangi bir alt sınıfını), veri otomatik olarak dönüştürülmez (birresponse_model tanımlamış olsanız bile) ve dokümantasyon da otomatik üretilmez (örneğin, üretilen OpenAPI’nin parçası olarak HTTP headerContent-Type içindeki ilgili "media type" dahil edilmez).
Bununla birlikte,path operation decorator içinderesponse_class parametresini kullanarak hangiResponse’un (örn. herhangi birResponse alt sınıfı) kullanılacağını da ilan edebilirsiniz.
path operation function’ınızdan döndürdüğünüz içerik, oResponse’un içine yerleştirilir.
Ve eğer buResponse (JSONResponse veUJSONResponse’ta olduğu gibi) bir JSON media type’a (application/json) sahipse, döndürdüğünüz veri;path operation decorator içinde tanımladığınız herhangi bir Pydanticresponse_model ile otomatik olarak dönüştürülür (ve filtrelenir).
Not
Media type’ı olmayan bir response class kullanırsanız, FastAPI response’unuzun content içermediğini varsayar; bu yüzden ürettiği OpenAPI dokümanında response formatını dokümante etmez.
ORJSONResponse Kullan¶
Örneğin performansı sıkıştırmaya çalışıyorsanız,orjson kurup kullanabilir ve response’uORJSONResponse olarak ayarlayabilirsiniz.
Kullanmak istediğinizResponse class’ını (alt sınıfını) import edin vepath operation decorator içinde tanımlayın.
Büyük response'larda, doğrudan birResponse döndürmek bir dictionary döndürmekten çok daha hızlıdır.
Çünkü varsayılan olarak FastAPI, içindeki her item’ı inceleyip JSON olarak serialize edilebilir olduğundan emin olur; tutorial’da anlatılan aynıJSON Compatible Encoder mekanizmasını kullanır. Bu da örneğin veritabanı modelleri gibikeyfi objeleri döndürebilmenizi sağlar.
Ancak döndürdüğünüz içeriğinJSON ile serialize edilebilir olduğundan eminseniz, onu doğrudan response class’ına verebilir ve FastAPI’nin response class’ına vermeden önce dönüş içeriğinizijsonable_encoder içinden geçirirken oluşturacağı ek yükten kaçınabilirsiniz.
fromfastapiimportFastAPIfromfastapi.responsesimportORJSONResponseapp=FastAPI()@app.get("/items/",response_class=ORJSONResponse)asyncdefread_items():returnORJSONResponse([{"item_id":"Foo"}])Bilgi
response_class parametresi, response’un "media type"’ını tanımlamak için de kullanılır.
Bu durumda HTTP headerContent-Type,application/json olarak ayarlanır.
Ve OpenAPI’de de bu şekilde dokümante edilir.
İpucu
ORJSONResponse yalnızca FastAPI’de vardır, Starlette’te yoktur.
HTML Response¶
FastAPI’den doğrudan HTML içeren bir response döndürmek içinHTMLResponse kullanın.
HTMLResponseimport edin.- path operation decorator’ınızın
response_classparametresi olarakHTMLResponseverin.
fromfastapiimportFastAPIfromfastapi.responsesimportHTMLResponseapp=FastAPI()@app.get("/items/",response_class=HTMLResponse)asyncdefread_items():return""" <html> <head> <title>Some HTML in here</title> </head> <body> <h1>Look ma! HTML!</h1> </body> </html> """Bilgi
response_class parametresi, response’un "media type"’ını tanımlamak için de kullanılır.
Bu durumda HTTP headerContent-Type,text/html olarak ayarlanır.
Ve OpenAPI’de de bu şekilde dokümante edilir.
BirResponse Döndür¶
Doğrudan bir Response döndür bölümünde görüldüğü gibi,path operation içinde doğrudan bir response döndürerek response’u override edebilirsiniz.
Yukarıdaki örneğin aynısı, bu sefer birHTMLResponse döndürerek, şöyle görünebilir:
fromfastapiimportFastAPIfromfastapi.responsesimportHTMLResponseapp=FastAPI()@app.get("/items/")asyncdefread_items():html_content=""" <html> <head> <title>Some HTML in here</title> </head> <body> <h1>Look ma! HTML!</h1> </body> </html> """returnHTMLResponse(content=html_content,status_code=200)Uyarı
path operation function’ınızın doğrudan döndürdüğü birResponse, OpenAPI’de dokümante edilmez (örneğinContent-Type dokümante edilmez) ve otomatik interaktif dokümanlarda görünmez.
Bilgi
Elbette gerçekContent-Type header’ı, status code vb. değerler, döndürdüğünüzResponse objesinden gelir.
OpenAPI’de Dokümante Et veResponse’u Override Et¶
Response’u fonksiyonun içinden override etmek ama aynı zamanda OpenAPI’de "media type"’ı dokümante etmek istiyorsanız,response_class parametresini kullanıp ayrıca birResponse objesi döndürebilirsiniz.
Bu durumdaresponse_class sadece OpenAPIpath operation’ını dokümante etmek için kullanılır; sizinResponse’unuz ise olduğu gibi kullanılır.
Doğrudan birHTMLResponse Döndür¶
Örneğin şöyle bir şey olabilir:
fromfastapiimportFastAPIfromfastapi.responsesimportHTMLResponseapp=FastAPI()defgenerate_html_response():html_content=""" <html> <head> <title>Some HTML in here</title> </head> <body> <h1>Look ma! HTML!</h1> </body> </html> """returnHTMLResponse(content=html_content,status_code=200)@app.get("/items/",response_class=HTMLResponse)asyncdefread_items():returngenerate_html_response()Bu örnektegenerate_html_response() fonksiyonu, HTML’i birstr olarak döndürmek yerine zaten birResponse üretip döndürmektedir.
generate_html_response() çağrısının sonucunu döndürerek, varsayılanFastAPI davranışını override edecek birResponse döndürmüş olursunuz.
Amaresponse_class içindeHTMLResponse da verdiğiniz içinFastAPI, bunu OpenAPI’de ve interaktif dokümanlardatext/html ile HTML olarak nasıl dokümante edeceğini bilir:
Mevcut Response'lar¶
Mevcut response'lardan bazıları aşağıdadır.
Unutmayın:Response ile başka herhangi bir şeyi döndürebilir, hatta özel bir alt sınıf da oluşturabilirsiniz.
Teknik Detaylar
from starlette.responses import HTMLResponse da kullanabilirsiniz.
FastAPI, geliştirici için kolaylık olsun diyestarlette.responses içindekilerifastapi.responses olarak da sağlar. Ancak mevcut response'ların çoğu doğrudan Starlette’ten gelir.
Response¶
AnaResponse class’ıdır; diğer tüm response'lar bundan türetilir.
Bunu doğrudan döndürebilirsiniz.
Şu parametreleri kabul eder:
content- Birstrveyabytes.status_code- BirintHTTP status code.headers- String’lerden oluşan birdict.media_type- Media type’ı veren birstr. Örn."text/html".
FastAPI (aslında Starlette) otomatik olarak bir Content-Length header’ı ekler. Ayrıcamedia_type’a göre bir Content-Type header’ı ekler ve text türleri için sona bir charset ekler.
fromfastapiimportFastAPI,Responseapp=FastAPI()@app.get("/legacy/")defget_legacy_data():data="""<?xml version="1.0"?> <shampoo> <Header> Apply shampoo here. </Header> <Body> You'll have to use soap here. </Body> </shampoo> """returnResponse(content=data,media_type="application/xml")HTMLResponse¶
Yukarıda okuduğunuz gibi, bir miktar text veya bytes alır ve HTML response döndürür.
PlainTextResponse¶
Bir miktar text veya bytes alır ve düz metin response döndürür.
fromfastapiimportFastAPIfromfastapi.responsesimportPlainTextResponseapp=FastAPI()@app.get("/",response_class=PlainTextResponse)asyncdefmain():return"Hello World"JSONResponse¶
Bir miktar veri alır veapplication/json olarak encode edilmiş bir response döndürür.
Yukarıda okuduğunuz gibi,FastAPI’de varsayılan response budur.
ORJSONResponse¶
Yukarıda okuduğunuz gibiorjson kullanan hızlı bir alternatif JSON response.
Bilgi
Bunun içinorjson kurulmalıdır; örneğinpip install orjson.
UJSONResponse¶
ujson kullanan alternatif bir JSON response.
Bilgi
Bunun içinujson kurulmalıdır; örneğinpip install ujson.
Uyarı
ujson, bazı edge-case’leri ele alma konusunda Python’un built-in implementasyonu kadar dikkatli değildir.
fromfastapiimportFastAPIfromfastapi.responsesimportUJSONResponseapp=FastAPI()@app.get("/items/",response_class=UJSONResponse)asyncdefread_items():return[{"item_id":"Foo"}]İpucu
ORJSONResponse daha hızlı bir alternatif olabilir.
RedirectResponse¶
HTTP redirect döndürür. Varsayılan olarak 307 status code (Temporary Redirect) kullanır.
RedirectResponse’u doğrudan döndürebilirsiniz:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/typer")asyncdefredirect_typer():returnRedirectResponse("https://typer.tiangolo.com")Veyaresponse_class parametresi içinde kullanabilirsiniz:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/fastapi",response_class=RedirectResponse)asyncdefredirect_fastapi():return"https://fastapi.tiangolo.com"Bunu yaparsanız,path operation function’ınızdan doğrudan URL döndürebilirsiniz.
Bu durumda kullanılanstatus_code,RedirectResponse için varsayılan olan307 olur.
Ayrıcastatus_code parametresiniresponse_class parametresiyle birlikte kullanabilirsiniz:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/pydantic",response_class=RedirectResponse,status_code=302)asyncdefredirect_pydantic():return"https://docs.pydantic.dev/"StreamingResponse¶
Bir async generator veya normal generator/iterator alır ve response body’yi stream eder.
fromfastapiimportFastAPIfromfastapi.responsesimportStreamingResponseapp=FastAPI()asyncdeffake_video_streamer():foriinrange(10):yieldb"some fake video bytes"@app.get("/")asyncdefmain():returnStreamingResponse(fake_video_streamer())StreamingResponse’u file-like objelerle kullanma¶
Birfile-like objeniz varsa (örn.open()’ın döndürdüğü obje), o file-like obje üzerinde iterate eden bir generator function oluşturabilirsiniz.
Böylece önce hepsini memory’ye okumak zorunda kalmazsınız; bu generator function’ıStreamingResponse’a verip döndürebilirsiniz.
Buna cloud storage ile etkileşime giren, video işleyen ve benzeri birçok kütüphane dahildir.
fromfastapiimportFastAPIfromfastapi.responsesimportStreamingResponsesome_file_path="large-video-file.mp4"app=FastAPI()@app.get("/")defmain():defiterfile():# (1)withopen(some_file_path,mode="rb")asfile_like:# (2)yield fromfile_like# (3)returnStreamingResponse(iterfile(),media_type="video/mp4")- Bu generator function’dır. İçinde
yieldifadeleri olduğu için "generator function" denir. - Bir
withbloğu kullanarak, generator function bittiğinde file-like objenin kapandığından emin oluruz. Yani response göndermeyi bitirdikten sonra kapanır. Bu
yield from, fonksiyonafile_likeisimli şeyi iterate etmesini söyler. Ardından iterate edilen her parça için, o parçayı bu generator function’dan (iterfile) geliyormuş gibi yield eder.Yani, içerdeki "üretme" (generating) işini başka bir şeye devreden bir generator function’dır.
Bunu bu şekilde yaptığımızda
withbloğu içinde tutabilir ve böylece iş bitince file-like objenin kapanmasını garanti edebiliriz.
İpucu
Buradaasync veawait desteklemeyen standartopen() kullandığımız için path operation’ı normaldef ile tanımlarız.
FileResponse¶
Asenkron olarak bir dosyayı response olarak stream eder.
Diğer response türlerine göre instantiate ederken farklı argümanlar alır:
path- Stream edilecek dosyanın dosya path'i.headers- Eklenecek özel header’lar; dictionary olarak.media_type- Media type’ı veren string. Ayarlanmazsa, dosya adı veya path kullanılarak media type tahmin edilir.filename- Ayarlanırsa response içindekiContent-Disposition’a dahil edilir.
File response'ları uygunContent-Length,Last-Modified veETag header’larını içerir.
fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsesome_file_path="large-video-file.mp4"app=FastAPI()@app.get("/")asyncdefmain():returnFileResponse(some_file_path)response_class parametresini de kullanabilirsiniz:
fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsesome_file_path="large-video-file.mp4"app=FastAPI()@app.get("/",response_class=FileResponse)asyncdefmain():returnsome_file_pathBu durumdapath operation function’ınızdan doğrudan dosya path'ini döndürebilirsiniz.
Özel response class¶
Response’dan türeterek kendi özel response class’ınızı oluşturabilir ve kullanabilirsiniz.
Örneğin, dahil gelenORJSONResponse class’ında kullanılmayan bazı özel ayarlarlaorjson kullanmak istediğinizi varsayalım.
Diyelim ki girintili ve biçimlendirilmiş JSON döndürmek istiyorsunuz; bunun içinorjson.OPT_INDENT_2 seçeneğini kullanmak istiyorsunuz.
BirCustomORJSONResponse oluşturabilirsiniz. Burada yapmanız gereken temel şey, content’ibytes olarak döndüren birResponse.render(content) metodu yazmaktır:
fromtypingimportAnyimportorjsonfromfastapiimportFastAPI,Responseapp=FastAPI()classCustomORJSONResponse(Response):media_type="application/json"defrender(self,content:Any)->bytes:assertorjsonisnotNone,"orjson must be installed"returnorjson.dumps(content,option=orjson.OPT_INDENT_2)@app.get("/",response_class=CustomORJSONResponse)asyncdefmain():return{"message":"Hello World"}Artık şunu döndürmek yerine:
{"message":"Hello World"}...bu response şunu döndürür:
{"message":"Hello World"}Elbette JSON’u formatlamaktan çok daha iyi şekillerde bundan faydalanabilirsiniz. 😉
Varsayılan response class¶
BirFastAPI class instance’ı veya birAPIRouter oluştururken, varsayılan olarak hangi response class’ının kullanılacağını belirtebilirsiniz.
Bunu tanımlayan parametredefault_response_class’tır.
Aşağıdaki örnekteFastAPI, tümpath operations için varsayılan olarakJSONResponse yerineORJSONResponse kullanır.
fromfastapiimportFastAPIfromfastapi.responsesimportORJSONResponseapp=FastAPI(default_response_class=ORJSONResponse)@app.get("/items/")asyncdefread_items():return[{"item_id":"Foo"}]İpucu
Daha önce olduğu gibi,path operations içinderesponse_class’ı yine override edebilirsiniz.
Ek dokümantasyon¶
OpenAPI’de media type’ı ve daha birçok detayıresponses kullanarak da tanımlayabilirsiniz:OpenAPI’de Ek Response'lar.