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

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

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

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

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

Типово FastAPI повертатиме відповіді, використовуючи JSONResponse.

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

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

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

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

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

Примітка

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

Використовуйте `ORJSONResponse`¶

Наприклад, якщо ви максимально оптимізуєте продуктивність, можете встановити та використовувати orjson і встановити відповідь як ORJSONResponse.

Імпортуйте потрібний клас Response (підклас) і оголосіть його в декораторі операції шляху.

Для великих відповідей повернення Response безпосередньо значно швидше, ніж повернення словника.

Це тому, що за замовчуванням FastAPI перевірятиме кожен елемент усередині та переконуватиметься, що його можна серіалізувати як JSON, використовуючи той самий Сумісний кодувальник JSON, описаний у навчальному посібнику. Саме це дозволяє повертати довільні об'єкти, наприклад моделі бази даних.

Але якщо ви впевнені, що вміст, який повертається, серіалізується в JSON, ви можете передати його безпосередньо класу відповіді та уникнути додаткових витрат FastAPI на пропускання вашого вмісту через jsonable_encoder перед передаванням його класу відповіді.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

app = FastAPI()


@app.get("/items/", response_class=ORJSONResponse)
async def read_items():
    return ORJSONResponse([{"item_id": "Foo"}])

Інформація

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

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

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

Порада

ORJSONResponse доступний лише у FastAPI, не в Starlette.

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, як зазначено вище.

`ORJSONResponse`¶

Швидка альтернативна JSON-відповідь з використанням orjson, як описано вище.

Інформація

Потрібно встановити orjson, наприклад pip install orjson.

`UJSONResponse`¶

Альтернативна JSON-відповідь з використанням ujson.

Інформація

Потрібно встановити ujson, наприклад pip install ujson.

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

ujson менш обережний, ніж вбудована реалізація Python, у поводженні з деякими крайніми випадками.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import UJSONResponse

app = FastAPI()


@app.get("/items/", response_class=UJSONResponse)
async def read_items():
    return [{"item_id": "Foo"}]

Порада

Ймовірно, ORJSONResponse може бути швидшою альтернативою.

`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-генератор або звичайний генератор/ітератор і транслює тіло відповіді потоково.

Python 3.10+

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"


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

Використання `StreamingResponse` з об'єктами типу file-like¶

Якщо у вас є file-like об'єкт (наприклад, об'єкт, що повертається open()), ви можете створити генераторну функцію для ітерації по цьому file-like об'єкту.

Таким чином, вам не потрібно спочатку читати все в пам'ять, і ви можете передати цю генераторну функцію в StreamingResponse і повернути її.

Сюди входить багато бібліотек для взаємодії з хмарними сховищами, обробки відео та інші.

Python 3.10+

from fastapi import FastAPI
from fastapi.responses import StreamingResponse

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


@app.get("/")
def main():
    def iterfile():  # (1)
        with open(some_file_path, mode="rb") as file_like:  # (2)
            yield from file_like  # (3)

    return StreamingResponse(iterfile(), media_type="video/mp4")

Це генераторна функція. Вона є «генераторною функцією», бо містить оператори yield усередині.
Використовуючи блок with, ми гарантуємо, що file-like об'єкт буде закрито після завершення роботи генераторної функції. Тобто після того, як вона завершить надсилання відповіді.
Цей yield from вказує функції ітеруватися по об'єкту з назвою file_like. А потім, для кожної ітерованої частини, повертати цю частину, ніби вона надходить з цієї генераторної функції (iterfile).

Тож це генераторна функція, яка всередині передає роботу «генерації» чомусь іншому.

Роблячи це таким чином, ми можемо помістити її в блок with і таким чином гарантувати, що file-like об'єкт буде закрито після завершення.

Порада

Зверніть увагу, що тут ми використовуємо стандартний open(), який не підтримує async та await, тому ми оголошуємо операцію шляху звичайною def.

`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, але з деякими користувацькими налаштуваннями, які не використовуються у вбудованому класі ORJSONResponse.

Припустімо, ви хочете, щоб повертався відформатований із відступами 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. 😉

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

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

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

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

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, стрім, файл, інше¶

Використовуйте ORJSONResponse¶

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

Повернути Response¶

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

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

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

Response¶

HTMLResponse¶

PlainTextResponse¶

JSONResponse¶

ORJSONResponse¶

UJSONResponse¶

RedirectResponse¶

StreamingResponse¶

Використання StreamingResponse з об'єктами типу file-like¶

FileResponse¶

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

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

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

Використовуйте `ORJSONResponse`¶

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

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

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

`Response`¶

`HTMLResponse`¶

`PlainTextResponse`¶

`JSONResponse`¶

`ORJSONResponse`¶

`UJSONResponse`¶

`RedirectResponse`¶

`StreamingResponse`¶

Використання `StreamingResponse` з об'єктами типу file-like¶

`FileResponse`¶