Користувацька відповідь - HTML, стрім, файл, інше¶

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Типово FastAPI повертатиме JSON-відповіді.

Ви можете переписати це, повернувши Response безпосередньо, як показано в Повернути відповідь безпосередньо.

Але якщо ви повертаєте Response безпосередньо (або будь-який його підклас, як-от JSONResponse), дані не будуть автоматично конвертовані (навіть якщо ви оголосите response_model), і документація не буде автоматично згенерована (наприклад, з включенням конкретного «медіа-типу» в HTTP-заголовку Content-Type як частини згенерованого OpenAPI).

Ви також можете оголосити Response, який слід використовувати (наприклад, будь-який підклас Response), у декораторі операції шляху через параметр response_class.

Вміст, який ви повертаєте з вашої функції операції шляху, буде поміщений усередину цього Response.

Примітка

Якщо ви використовуєте клас відповіді без медіа-типу, FastAPI очікуватиме, що у вашої відповіді не буде вмісту, тож формат відповіді не буде задокументовано в згенерованій документації OpenAPI.

JSON-відповіді¶

Типово FastAPI повертає JSON-відповіді.

Якщо ви оголосите Модель відповіді, FastAPI використає її, щоб серіалізувати дані в JSON за допомогою Pydantic.

Якщо ви не оголосите модель відповіді, FastAPI використає jsonable_encoder, пояснений у Сумісний кодувальник JSON, і помістить результат у JSONResponse.

Якщо ви оголосите response_class з JSON медіа-типом (application/json), як у випадку з JSONResponse, дані, що повертаються, будуть автоматично перетворені (і відфільтровані) згідно з будь-якою Pydantic response_model, яку ви оголосили в декораторі операції шляху. Але дані не будуть серіалізовані в JSON-байти за допомогою Pydantic, натомість вони будуть перетворені з jsonable_encoder, а потім передані класу JSONResponse, який і серіалізує їх у байти, використовуючи стандартну JSON-бібліотеку в Python.

Продуктивність JSON¶

Коротко: якщо вам потрібна максимальна продуктивність, використовуйте Модель відповіді і не оголошуйте response_class у декораторі операції шляху.

Python 3.10+

# Code above omitted 👆

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

# Code below omitted 👇

👀 Full file preview

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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


@app.get("/items/")
async def read_items() -> list[Item]:
    return [
        Item(name="Portal Gun", price=42.0),
        Item(name="Plumbus", price=32.0),
    ]

HTML-відповідь¶

Щоб повернути відповідь із HTML безпосередньо з FastAPI, використовуйте HTMLResponse.

Імпортуйте HTMLResponse.
Передайте HTMLResponse як параметр response_class вашого декоратора операції шляху.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/items/", response_class=HTMLResponse)
async def read_items():
    return """
    <html>
        <head>
            <title>Some HTML in here</title>
        </head>
        <body>
            <h1>Look ma! HTML!</h1>
        </body>
    </html>
    """

Інформація

Параметр response_class також визначатиме «медіа-тип» відповіді.

У цьому випадку HTTP-заголовок Content-Type буде встановлено в text/html.

І це буде задокументовано відповідно в OpenAPI.

Повернути `Response`¶

Як показано в Повернути відповідь безпосередньо, ви також можете переписати відповідь безпосередньо у вашій операції шляху, просто повернувши її.

Той самий приклад вище, що повертає HTMLResponse, може виглядати так:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get("/items/")
async def read_items():
    html_content = """
    <html>
        <head>
            <title>Some HTML in here</title>
        </head>
        <body>
            <h1>Look ma! HTML!</h1>
        </body>
    </html>
    """
    return HTMLResponse(content=html_content, status_code=200)

Попередження

Response, повернений безпосередньо вашою функцією операції шляху, не буде задокументовано в OpenAPI (наприклад, Content-Type не буде задокументовано) і не буде видно в автоматичній інтерактивній документації.

Інформація

Звісно, фактичні заголовок Content-Type, код статусу тощо прийдуть з об'єкта Response, який ви повернули.

Задокументуйте в OpenAPI і перепишіть `Response`¶

Якщо ви хочете переписати відповідь усередині функції, але водночас задокументувати «медіа-тип» в OpenAPI, ви можете використати параметр response_class І повернути об'єкт Response.

Тоді response_class буде використано лише для документування операції шляху в OpenAPI, а ваша Response буде використана як є.

Повернути `HTMLResponse` безпосередньо¶

Наприклад, це може бути щось на кшталт:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


def generate_html_response():
    html_content = """
    <html>
        <head>
            <title>Some HTML in here</title>
        </head>
        <body>
            <h1>Look ma! HTML!</h1>
        </body>
    </html>
    """
    return HTMLResponse(content=html_content, status_code=200)


@app.get("/items/", response_class=HTMLResponse)
async def read_items():
    return generate_html_response()

У цьому прикладі функція generate_html_response() уже генерує та повертає Response замість повернення HTML як str.

Повертаючи результат виклику generate_html_response(), ви вже повертаєте Response, яка перепише типову поведінку FastAPI.

Але оскільки ви також передали HTMLResponse у response_class, FastAPI знатиме, як задокументувати це в OpenAPI та інтерактивній документації як HTML з text/html:

Доступні відповіді¶

Ось деякі з доступних відповідей.

Майте на увазі, що ви можете використовувати Response, щоб повертати що завгодно інше, або навіть створити власний підклас.

Технічні деталі

Ви також можете використати from starlette.responses import HTMLResponse.

FastAPI надає ті ж starlette.responses як fastapi.responses лише для вашої зручності як розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette.

`Response`¶

Головний клас Response, від якого успадковуються всі інші відповіді.

Ви можете повертати його безпосередньо.

Він приймає такі параметри:

content - str або bytes.
status_code - int - код статусу HTTP.
headers - dict строк.
media_type - str, що задає медіа-тип, напр. "text/html".

FastAPI (насправді Starlette) автоматично додасть заголовок Content-Length. Також буде додано заголовок Content-Type на основі media_type з додаванням набору символів для текстових типів.

Python 3.10+

from fastapi import FastAPI, Response

app = FastAPI()


@app.get("/legacy/")
def get_legacy_data():
    data = """<?xml version="1.0"?>
    <shampoo>
    <Header>
        Apply shampoo here.
    </Header>
    <Body>
        You'll have to use soap here.
    </Body>
    </shampoo>
    """
    return Response(content=data, media_type="application/xml")

`HTMLResponse`¶

Приймає текст або байти та повертає HTML-відповідь, як описано вище.

`PlainTextResponse`¶

Приймає текст або байти та повертає відповідь звичайним текстом.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import PlainTextResponse

app = FastAPI()


@app.get("/", response_class=PlainTextResponse)
async def main():
    return "Hello World"

`JSONResponse`¶

Приймає дані та повертає відповідь, закодовану як application/json.

Це типова відповідь, яку використовує FastAPI, як зазначено вище.

Технічні деталі

Але якщо ви оголосите модель відповіді або тип, його буде використано безпосередньо для серіалізації даних у JSON, і відповідь з коректним медіа-типом для JSON буде повернута безпосередньо, без використання класу JSONResponse.

Це ідеальний спосіб отримати найкращу продуктивність.

`RedirectResponse`¶

Повертає HTTP-перенаправлення. Типово використовує код статусу 307 (Temporary Redirect).

Ви можете повернути RedirectResponse безпосередньо:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/typer")
async def redirect_typer():
    return RedirectResponse("https://typer.tiangolo.com")

Або ви можете використати його в параметрі response_class:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/fastapi", response_class=RedirectResponse)
async def redirect_fastapi():
    return "https://fastapi.tiangolo.com"

У такому разі ви можете повертати URL безпосередньо з вашої функції операції шляху.

У цьому випадку status_code буде типовим для RedirectResponse, тобто 307.

Ви також можете використати параметр status_code разом із параметром response_class:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/pydantic", response_class=RedirectResponse, status_code=302)
async def redirect_pydantic():
    return "https://docs.pydantic.dev/"

`StreamingResponse`¶

Приймає async-генератор або звичайний генератор/ітератор (функцію з yield) і потоково передає тіло відповіді.

Python 3.10+

import anyio
from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()


async def fake_video_streamer():
    for i in range(10):
        yield b"some fake video bytes"
        await anyio.sleep(0)


@app.get("/")
async def main():
    return StreamingResponse(fake_video_streamer())

Технічні деталі

Завдання async може бути скасовано лише тоді, коли воно досягає await. Якщо немає await, генератор (функція з yield) не може бути коректно скасований і може продовжувати працювати навіть після запиту на скасування.

Оскільки цьому невеликому прикладу не потрібні жодні оператори await, ми додаємо await anyio.sleep(0), щоб надати циклу подій шанс обробити скасування.

Це ще важливіше для великих або нескінченних потоків.

Порада

Замість того щоб повертати StreamingResponse безпосередньо, імовірно, краще дотримуватися стилю в Потокова передача даних, це значно зручніше та обробляє скасування «за лаштунками» для вас.

Якщо ви транслюєте JSON Lines, дотримуйтесь навчального посібника Потоки JSON Lines.

`FileResponse`¶

Асинхронно транслює файл як відповідь.

Приймає інший набір аргументів для створення екземпляра, ніж інші типи відповідей:

path - шлях до файлу для трансляції.
headers - будь-які користувацькі заголовки як словник.
media_type - строка, що задає медіа-тип. Якщо не встановлено, медіа-тип буде виведено з імені файлу або шляху.
filename - якщо встановлено, буде включено до Content-Disposition відповіді.

Відповіді з файлами включатимуть відповідні заголовки Content-Length, Last-Modified і ETag.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import FileResponse

some_file_path = "large-video-file.mp4"
app = FastAPI()


@app.get("/")
async def main():
    return FileResponse(some_file_path)

Ви також можете використати параметр response_class:

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import FileResponse

some_file_path = "large-video-file.mp4"
app = FastAPI()


@app.get("/", response_class=FileResponse)
async def main():
    return some_file_path

У цьому випадку ви можете повертати шлях до файлу безпосередньо з вашої функції операції шляху.

Власний клас відповіді¶

Ви можете створити власний клас відповіді, успадкувавши його від Response, і використовувати його.

Наприклад, скажімо, ви хочете використовувати orjson з деякими налаштуваннями.

Припустімо, ви хочете, щоб повертався відформатований із відступами JSON, тож ви хочете використати опцію orjson orjson.OPT_INDENT_2.

Ви можете створити CustomORJSONResponse. Головне, що потрібно зробити, це створити метод Response.render(content), який повертає вміст як bytes:

Python 3.10+

from typing import Any

import orjson
from fastapi import FastAPI, Response

app = FastAPI()


class CustomORJSONResponse(Response):
    media_type = "application/json"

    def render(self, content: Any) -> bytes:
        assert orjson is not None, "orjson must be installed"
        return orjson.dumps(content, option=orjson.OPT_INDENT_2)


@app.get("/", response_class=CustomORJSONResponse)
async def main():
    return {"message": "Hello World"}

Тепер замість повернення:

{"message": "Hello World"}

...ця відповідь повертатиме:

{
  "message": "Hello World"
}

Звісно, ви, ймовірно, знайдете значно кращі способи скористатися цим, ніж просто форматування JSON. 😉

`orjson` або Модель відповіді¶

Якщо ви шукаєте продуктивність, імовірно, краще використати Модель відповіді, ніж відповідь orjson.

З моделлю відповіді FastAPI використає Pydantic, щоб серіалізувати дані в JSON без проміжних кроків, як-от перетворення за допомогою jsonable_encoder, що відбувалося б в іншому випадку.

І «під капотом» Pydantic використовує ті самі внутрішні механізми Rust, що й orjson, для серіалізації в JSON, тож ви вже отримаєте найкращу продуктивність із моделлю відповіді.

Типова відповідь за замовчуванням¶

Створюючи екземпляр класу FastAPI або APIRouter, ви можете вказати, який клас відповіді використовувати за замовчуванням.

Параметр, що це визначає, - default_response_class.

У прикладі нижче FastAPI використовуватиме HTMLResponse за замовчуванням в усіх операціях шляху, замість JSON.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI(default_response_class=HTMLResponse)


@app.get("/items/")
async def read_items():
    return "<h1>Items</h1><p>This is a list of items.</p>"

Порада

Ви все одно можете переписати response_class в операціях шляху, як і раніше.

Додаткова документація¶

Ви також можете оголосити медіа-тип і багато інших деталей в OpenAPI, використовуючи responses: Додаткові відповіді в OpenAPI.

Користувацька відповідь - HTML, стрім, файл, інше¶

JSON-відповіді¶

Продуктивність JSON¶

HTML-відповідь¶

Повернути Response¶

Задокументуйте в OpenAPI і перепишіть Response¶

Повернути HTMLResponse безпосередньо¶

Доступні відповіді¶

Response¶

HTMLResponse¶

PlainTextResponse¶

JSONResponse¶

RedirectResponse¶

StreamingResponse¶

FileResponse¶

Власний клас відповіді¶

orjson або Модель відповіді¶

Типова відповідь за замовчуванням¶

Додаткова документація¶

Повернути `Response`¶

Задокументуйте в OpenAPI і перепишіть `Response`¶

Повернути `HTMLResponse` безпосередньо¶

`Response`¶

`HTMLResponse`¶

`PlainTextResponse`¶

`JSONResponse`¶

`RedirectResponse`¶

`StreamingResponse`¶

`FileResponse`¶

`orjson` або Модель відповіді¶