Response Personalizado - HTML, Stream, Archivo, otros¶
🌐 Traducción por IA y humanos
Esta traducción fue hecha por IA guiada por humanos. 🤝
Podría tener errores al interpretar el significado original, o sonar poco natural, etc. 🤖
Puedes mejorar esta traducciónayudándonos a guiar mejor al LLM de IA.
Por defecto,FastAPI devolverá los responses usandoJSONResponse.
Puedes sobrescribirlo devolviendo unResponse directamente como se ve enDevolver una Response directamente.
Pero si devuelves unResponse directamente (o cualquier subclase, comoJSONResponse), los datos no se convertirán automáticamente (incluso si declaras unresponse_model), y la documentación no se generará automáticamente (por ejemplo, incluyendo el "media type" específico, en el HTTP headerContent-Type como parte del OpenAPI generado).
Pero también puedes declarar elResponse que quieres usar (por ejemplo, cualquier subclase deResponse), en elpath operation decorator usando el parámetroresponse_class.
Los contenidos que devuelvas desde tupath operation function se colocarán dentro de esaResponse.
Y si eseResponse tiene un media type JSON (application/json), como es el caso conJSONResponse yUJSONResponse, los datos que devuelvas se convertirán automáticamente (y serán filtrados) con cualquierresponse_model de Pydantic que hayas declarado en elpath operation decorator.
Nota
Si usas una clase de response sin media type, FastAPI esperará que tu response no tenga contenido, por lo que no documentará el formato del response en su OpenAPI generado.
UsaORJSONResponse¶
Por ejemplo, si estás exprimendo el rendimiento, puedes instalar y usarorjson y establecer el response comoORJSONResponse.
Importa la claseResponse (sub-clase) que quieras usar y declárala en elpath operation decorator.
Para responses grandes, devolver unaResponse directamente es mucho más rápido que devolver un diccionario.
Esto se debe a que, por defecto, FastAPI inspeccionará cada elemento dentro y se asegurará de que sea serializable como JSON, usando el mismoCodificador Compatible con JSON explicado en el tutorial. Esto es lo que te permite devolverobjetos arbitrarios, por ejemplo, modelos de bases de datos.
Pero si estás seguro de que el contenido que estás devolviendo esserializable con JSON, puedes pasarlo directamente a la clase de response y evitar la sobrecarga extra que FastAPI tendría al pasar tu contenido de retorno a través dejsonable_encoder antes de pasarlo a la clase de response.
fromfastapiimportFastAPIfromfastapi.responsesimportORJSONResponseapp=FastAPI()@app.get("/items/",response_class=ORJSONResponse)asyncdefread_items():returnORJSONResponse([{"item_id":"Foo"}])Información
El parámetroresponse_class también se utilizará para definir el "media type" del response.
En este caso, el HTTP headerContent-Type se establecerá enapplication/json.
Y se documentará así en OpenAPI.
Consejo
ElORJSONResponse solo está disponible en FastAPI, no en Starlette.
Response HTML¶
Para devolver un response con HTML directamente desdeFastAPI, usaHTMLResponse.
- Importa
HTMLResponse. - Pasa
HTMLResponsecomo parámetroresponse_classde tupath operation decorator.
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> """Información
El parámetroresponse_class también se utilizará para definir el "media type" del response.
En este caso, el HTTP headerContent-Type se establecerá entext/html.
Y se documentará así en OpenAPI.
Devuelve unaResponse¶
Como se ve enDevolver una Response directamente, también puedes sobrescribir el response directamente en tupath operation, devolviéndolo.
El mismo ejemplo de arriba, devolviendo unaHTMLResponse, podría verse así:
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)Advertencia
UnaResponse devuelta directamente por tupath operation function no se documentará en OpenAPI (por ejemplo, elContent-Type no se documentará) y no será visible en la documentación interactiva automática.
Información
Por supuesto, elContent-Type header real, el código de estado, etc., provendrán del objetoResponse que devolviste.
Documenta en OpenAPI y sobrescribeResponse¶
Si quieres sobrescribir el response desde dentro de la función pero al mismo tiempo documentar el "media type" en OpenAPI, puedes usar el parámetroresponse_class Y devolver un objetoResponse.
Elresponse_class solo se usará para documentar el OpenAPIpath operation, pero tuResponse se usará tal cual.
Devuelve unHTMLResponse directamente¶
Por ejemplo, podría ser algo así:
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()En este ejemplo, la funcióngenerate_html_response() ya genera y devuelve unaResponse en lugar de devolver el HTML en unstr.
Al devolver el resultado de llamar agenerate_html_response(), ya estás devolviendo unaResponse que sobrescribirá el comportamiento por defecto deFastAPI.
Pero como pasasteHTMLResponse en elresponse_class también,FastAPI sabrá cómo documentarlo en OpenAPI y la documentación interactiva como HTML context/html:
Responses disponibles¶
Aquí hay algunos de los responses disponibles.
Ten en cuenta que puedes usarResponse para devolver cualquier otra cosa, o incluso crear una sub-clase personalizada.
Nota Técnica
También podrías usarfrom starlette.responses import HTMLResponse.
FastAPI proporciona los mismosstarlette.responses comofastapi.responses solo como una conveniencia para ti, el desarrollador. Pero la mayoría de los responses disponibles vienen directamente de Starlette.
Response¶
La clase principalResponse, todos los otros responses heredan de ella.
Puedes devolverla directamente.
Acepta los siguientes parámetros:
content- Unstrobytes.status_code- Un código de estado HTTPint.headers- Undictde strings.media_type- Unstrque da el media type. Por ejemplo,"text/html".
FastAPI (de hecho Starlette) incluirá automáticamente un header Content-Length. También incluirá un header Content-Type, basado en elmedia_type y añadiendo un conjunto de caracteres para tipos de texto.
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¶
Toma algún texto o bytes y devuelve un response HTML, como leíste arriba.
PlainTextResponse¶
Toma algún texto o bytes y devuelve un response de texto plano.
fromfastapiimportFastAPIfromfastapi.responsesimportPlainTextResponseapp=FastAPI()@app.get("/",response_class=PlainTextResponse)asyncdefmain():return"Hello World"JSONResponse¶
Toma algunos datos y devuelve un response codificado comoapplication/json.
Este es el response usado por defecto enFastAPI, como leíste arriba.
ORJSONResponse¶
Un response JSON rápido alternativo usandoorjson, como leíste arriba.
Información
Esto requiere instalarorjson, por ejemplo, conpip install orjson.
UJSONResponse¶
Un response JSON alternativo usandoujson.
Información
Esto requiere instalarujson, por ejemplo, conpip install ujson.
Advertencia
ujson es menos cuidadoso que la implementación integrada de Python en cómo maneja algunos casos extremos.
fromfastapiimportFastAPIfromfastapi.responsesimportUJSONResponseapp=FastAPI()@app.get("/items/",response_class=UJSONResponse)asyncdefread_items():return[{"item_id":"Foo"}]Consejo
Es posible queORJSONResponse sea una alternativa más rápida.
RedirectResponse¶
Devuelve una redirección HTTP. Usa un código de estado 307 (Redirección Temporal) por defecto.
Puedes devolver unRedirectResponse directamente:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/typer")asyncdefredirect_typer():returnRedirectResponse("https://typer.tiangolo.com")O puedes usarlo en el parámetroresponse_class:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/fastapi",response_class=RedirectResponse)asyncdefredirect_fastapi():return"https://fastapi.tiangolo.com"Si haces eso, entonces puedes devolver la URL directamente desde tupath operation function.
En este caso, elstatus_code utilizado será el por defecto paraRedirectResponse, que es307.
También puedes usar el parámetrostatus_code combinado con el parámetroresponse_class:
fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/pydantic",response_class=RedirectResponse,status_code=302)asyncdefredirect_pydantic():return"https://docs.pydantic.dev/"StreamingResponse¶
Toma un generadorasync o un generador/iterador normal y transmite el cuerpo del response.
fromfastapiimportFastAPIfromfastapi.responsesimportStreamingResponseapp=FastAPI()asyncdeffake_video_streamer():foriinrange(10):yieldb"some fake video bytes"@app.get("/")asyncdefmain():returnStreamingResponse(fake_video_streamer())UsandoStreamingResponse con objetos similares a archivos¶
Si tienes unobjeto similar a un archivo (por ejemplo, el objeto devuelto poropen()), 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 alStreamingResponse, y devolverlo.
Esto incluye muchos paquetes para interactuar con almacenamiento en la nube, procesamiento de video y otros.
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")- Esta es la función generadora. Es una "función generadora" porque contiene declaraciones
yielddentro. - 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. Este
yield fromle dice a la función que itere sobre esa cosa llamadafile_like. Y luego, para cada parte iterada, yield esa parte como proveniente de esta función generadora (iterfile).Entonces, es una función generadora que transfiere el trabajo de "generar" a algo más internamente.
Al hacerlo de esta manera, podemos ponerlo en un bloque
with, y de esa manera, asegurarnos de que el objeto similar a un archivo se cierre después de finalizar.
Consejo
Nota que aquí como estamos usandoopen() estándar que no admiteasync yawait, declaramos el path operation condef normal.
FileResponse¶
Transmite un archivo asincrónicamente como response.
Toma un conjunto diferente de argumentos para crear un instance que los otros tipos de response:
path- La path del archivo para el archivo a transmitir.headers- Cualquier header personalizado para incluir, como un diccionario.media_type- Un string que da el media type. Si no se establece, se usará el nombre de archivo o la path para inferir un media type.filename- Si se establece, se incluirá en el responseContent-Disposition.
Los responses de archivos incluirán los headers apropiadosContent-Length,Last-Modified yETag.
fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsesome_file_path="large-video-file.mp4"app=FastAPI()@app.get("/")asyncdefmain():returnFileResponse(some_file_path)También puedes usar el parámetroresponse_class:
fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsesome_file_path="large-video-file.mp4"app=FastAPI()@app.get("/",response_class=FileResponse)asyncdefmain():returnsome_file_pathEn este caso, puedes devolver la path del archivo directamente desde tupath operation function.
Clase de response personalizada¶
Puedes crear tu propia clase de response personalizada, heredando deResponse y usándola.
Por ejemplo, digamos que quieres usarorjson, pero con algunas configuraciones personalizadas no utilizadas en la claseORJSONResponse incluida.
Digamos que quieres que devuelva JSON con sangría y formato, por lo que quieres usar la opción de orjsonorjson.OPT_INDENT_2.
Podrías crear unCustomORJSONResponse. Lo principal que tienes que hacer es crear un métodoResponse.render(content) que devuelva el contenido comobytes:
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"}Ahora en lugar de devolver:
{"message":"Hello World"}...este response devolverá:
{"message":"Hello World"}Por supuesto, probablemente encontrarás formas mucho mejores de aprovechar esto que formatear JSON. 😉
Clase de response por defecto¶
Al crear una instance de la claseFastAPI o unAPIRouter, puedes especificar qué clase de response usar por defecto.
El parámetro que define esto esdefault_response_class.
En el ejemplo a continuación,FastAPI usaráORJSONResponse por defecto, en todas laspath operations, en lugar deJSONResponse.
fromfastapiimportFastAPIfromfastapi.responsesimportORJSONResponseapp=FastAPI(default_response_class=ORJSONResponse)@app.get("/items/")asyncdefread_items():return[{"item_id":"Foo"}]Consejo
Todavía puedes sobrescribirresponse_class enpath operations como antes.
Documentación adicional¶
También puedes declarar el media type y muchos otros detalles en OpenAPI usandoresponses:Responses Adicionales en OpenAPI.