Valentyn
3 days ago
committed by
GitHub
GitHub
23 changed files with 800 additions and 325 deletions
@ -0,0 +1,72 @@ |
|||
# Модели Header-параметров |
|||
|
|||
Если у вас есть группа связанных **header-параметров**, то вы можете объединить их в одну **Pydantic-модель**. |
|||
|
|||
Это позволит вам **переиспользовать модель** в **разных местах**, а также задать валидацию и метаданные сразу для всех параметров. 😎 |
|||
|
|||
/// note | Заметка |
|||
|
|||
Этот функционал доступен в FastAPI начиная с версии `0.115.0`. 🤓 |
|||
|
|||
/// |
|||
|
|||
## Header-параметры в виде Pydantic-модели |
|||
|
|||
Объявите нужные **header-параметры** в **Pydantic-модели** и затем аннотируйте параметр как `Header`: |
|||
|
|||
{* ../../docs_src/header_param_models/tutorial001_an_py310.py hl[9:14,18] *} |
|||
|
|||
**FastAPI** **извлечёт** данные для **каждого поля** из **заголовков** запроса и выдаст заданную вами Pydantic-модель. |
|||
|
|||
## Проверьте документацию |
|||
|
|||
Вы можете посмотреть нужные header-параметры в графическом интерфейсе сгенерированной документации по пути `/docs`: |
|||
|
|||
<div class="screenshot"> |
|||
<img src="/img/tutorial/header-param-models/image01.png"> |
|||
</div> |
|||
|
|||
## Как запретить дополнительные заголовки |
|||
|
|||
В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** заголовки, которые вы хотите получать. |
|||
|
|||
Вы можете использовать возможности конфигурации Pydantic-модели для того, чтобы запретить (`forbid`) любые дополнительные (`extra`) поля: |
|||
|
|||
{* ../../docs_src/header_param_models/tutorial002_an_py310.py hl[10] *} |
|||
|
|||
Если клиент попробует отправить **дополнительные заголовки**, то в ответ он получит **ошибку**. |
|||
|
|||
Например, если клиент попытается отправить заголовок `tool` со значением `plumbus`, то в ответ он получит ошибку, сообщающую ему, что header-параметр `tool` не разрешен: |
|||
|
|||
```json |
|||
{ |
|||
"detail": [ |
|||
{ |
|||
"type": "extra_forbidden", |
|||
"loc": ["header", "tool"], |
|||
"msg": "Extra inputs are not permitted", |
|||
"input": "plumbus", |
|||
} |
|||
] |
|||
} |
|||
``` |
|||
|
|||
## Как отключить автоматическое преобразование подчеркиваний |
|||
|
|||
Как и в случае с обычными заголовками, если у вас в именах параметров имеются символы подчеркивания, они **автоматически преобразовываются в дефис**. |
|||
|
|||
Например, если в коде есть header-параметр `save_data`, то ожидаемый HTTP-заголовок будет `save-data` и именно так он будет отображаться в документации. |
|||
|
|||
Если по каким-то причинам вам нужно отключить данное автоматическое преобразование, это можно сделать и для Pydantic-моделей для header-параметров. |
|||
|
|||
{* ../../docs_src/header_param_models/tutorial003_an_py310.py hl[19] *} |
|||
|
|||
/// warning | Внимание |
|||
|
|||
Перед тем как устанавливать для параметра `convert_underscores` значение `False`, имейте в виду, что некоторые HTTP-прокси и серверы не разрешают использовать заголовки с символами подчеркивания. |
|||
|
|||
/// |
|||
|
|||
## Резюме |
|||
|
|||
Вы можете использовать **Pydantic-модели** для объявления **header-параметров** в **FastAPI**. 😎 |
|||
@ -0,0 +1,19 @@ |
|||
from typing import List, Union |
|||
|
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: Union[str, None] = None |
|||
traceparent: Union[str, None] = None |
|||
x_tag: List[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)): |
|||
return headers |
|||
@ -0,0 +1,22 @@ |
|||
from typing import List, Union |
|||
|
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
from typing_extensions import Annotated |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: Union[str, None] = None |
|||
traceparent: Union[str, None] = None |
|||
x_tag: List[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items( |
|||
headers: Annotated[CommonHeaders, Header(convert_underscores=False)], |
|||
): |
|||
return headers |
|||
@ -0,0 +1,21 @@ |
|||
from typing import Annotated |
|||
|
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: str | None = None |
|||
traceparent: str | None = None |
|||
x_tag: list[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items( |
|||
headers: Annotated[CommonHeaders, Header(convert_underscores=False)], |
|||
): |
|||
return headers |
|||
@ -0,0 +1,21 @@ |
|||
from typing import Annotated, Union |
|||
|
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: Union[str, None] = None |
|||
traceparent: Union[str, None] = None |
|||
x_tag: list[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items( |
|||
headers: Annotated[CommonHeaders, Header(convert_underscores=False)], |
|||
): |
|||
return headers |
|||
@ -0,0 +1,17 @@ |
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: str | None = None |
|||
traceparent: str | None = None |
|||
x_tag: list[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)): |
|||
return headers |
|||
@ -0,0 +1,19 @@ |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI, Header |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class CommonHeaders(BaseModel): |
|||
host: str |
|||
save_data: bool |
|||
if_modified_since: Union[str, None] = None |
|||
traceparent: Union[str, None] = None |
|||
x_tag: list[str] = [] |
|||
|
|||
|
|||
@app.get("/items/") |
|||
async def read_items(headers: CommonHeaders = Header(convert_underscores=False)): |
|||
return headers |
|||
@ -1,4 +1,4 @@ |
|||
# For mkdocstrings and tests |
|||
httpx >=0.23.0,<0.28.0 |
|||
# For linting and generating docs versions |
|||
ruff ==0.9.4 |
|||
ruff ==0.11.2 |
|||
|
|||
@ -0,0 +1,285 @@ |
|||
import importlib |
|||
|
|||
import pytest |
|||
from dirty_equals import IsDict |
|||
from fastapi.testclient import TestClient |
|||
from inline_snapshot import snapshot |
|||
|
|||
from tests.utils import needs_py39, needs_py310 |
|||
|
|||
|
|||
@pytest.fixture( |
|||
name="client", |
|||
params=[ |
|||
"tutorial003", |
|||
pytest.param("tutorial003_py39", marks=needs_py39), |
|||
pytest.param("tutorial003_py310", marks=needs_py310), |
|||
"tutorial003_an", |
|||
pytest.param("tutorial003_an_py39", marks=needs_py39), |
|||
pytest.param("tutorial003_an_py310", marks=needs_py310), |
|||
], |
|||
) |
|||
def get_client(request: pytest.FixtureRequest): |
|||
mod = importlib.import_module(f"docs_src.header_param_models.{request.param}") |
|||
|
|||
client = TestClient(mod.app) |
|||
return client |
|||
|
|||
|
|||
def test_header_param_model(client: TestClient): |
|||
response = client.get( |
|||
"/items/", |
|||
headers=[ |
|||
("save_data", "true"), |
|||
("if_modified_since", "yesterday"), |
|||
("traceparent", "123"), |
|||
("x_tag", "one"), |
|||
("x_tag", "two"), |
|||
], |
|||
) |
|||
assert response.status_code == 200 |
|||
assert response.json() == { |
|||
"host": "testserver", |
|||
"save_data": True, |
|||
"if_modified_since": "yesterday", |
|||
"traceparent": "123", |
|||
"x_tag": ["one", "two"], |
|||
} |
|||
|
|||
|
|||
def test_header_param_model_no_underscore(client: TestClient): |
|||
response = client.get( |
|||
"/items/", |
|||
headers=[ |
|||
("save-data", "true"), |
|||
("if-modified-since", "yesterday"), |
|||
("traceparent", "123"), |
|||
("x-tag", "one"), |
|||
("x-tag", "two"), |
|||
], |
|||
) |
|||
assert response.status_code == 422 |
|||
assert response.json() == snapshot( |
|||
{ |
|||
"detail": [ |
|||
IsDict( |
|||
{ |
|||
"type": "missing", |
|||
"loc": ["header", "save_data"], |
|||
"msg": "Field required", |
|||
"input": { |
|||
"host": "testserver", |
|||
"traceparent": "123", |
|||
"x_tag": [], |
|||
"accept": "*/*", |
|||
"accept-encoding": "gzip, deflate", |
|||
"connection": "keep-alive", |
|||
"user-agent": "testclient", |
|||
"save-data": "true", |
|||
"if-modified-since": "yesterday", |
|||
"x-tag": "two", |
|||
}, |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "value_error.missing", |
|||
"loc": ["header", "save_data"], |
|||
"msg": "field required", |
|||
} |
|||
) |
|||
] |
|||
} |
|||
) |
|||
|
|||
|
|||
def test_header_param_model_defaults(client: TestClient): |
|||
response = client.get("/items/", headers=[("save_data", "true")]) |
|||
assert response.status_code == 200 |
|||
assert response.json() == { |
|||
"host": "testserver", |
|||
"save_data": True, |
|||
"if_modified_since": None, |
|||
"traceparent": None, |
|||
"x_tag": [], |
|||
} |
|||
|
|||
|
|||
def test_header_param_model_invalid(client: TestClient): |
|||
response = client.get("/items/") |
|||
assert response.status_code == 422 |
|||
assert response.json() == snapshot( |
|||
{ |
|||
"detail": [ |
|||
IsDict( |
|||
{ |
|||
"type": "missing", |
|||
"loc": ["header", "save_data"], |
|||
"msg": "Field required", |
|||
"input": { |
|||
"x_tag": [], |
|||
"host": "testserver", |
|||
"accept": "*/*", |
|||
"accept-encoding": "gzip, deflate", |
|||
"connection": "keep-alive", |
|||
"user-agent": "testclient", |
|||
}, |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "value_error.missing", |
|||
"loc": ["header", "save_data"], |
|||
"msg": "field required", |
|||
} |
|||
) |
|||
] |
|||
} |
|||
) |
|||
|
|||
|
|||
def test_header_param_model_extra(client: TestClient): |
|||
response = client.get( |
|||
"/items/", headers=[("save_data", "true"), ("tool", "plumbus")] |
|||
) |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == snapshot( |
|||
{ |
|||
"host": "testserver", |
|||
"save_data": True, |
|||
"if_modified_since": None, |
|||
"traceparent": None, |
|||
"x_tag": [], |
|||
} |
|||
) |
|||
|
|||
|
|||
def test_openapi_schema(client: TestClient): |
|||
response = client.get("/openapi.json") |
|||
assert response.status_code == 200, response.text |
|||
assert response.json() == snapshot( |
|||
{ |
|||
"openapi": "3.1.0", |
|||
"info": {"title": "FastAPI", "version": "0.1.0"}, |
|||
"paths": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"parameters": [ |
|||
{ |
|||
"name": "host", |
|||
"in": "header", |
|||
"required": True, |
|||
"schema": {"type": "string", "title": "Host"}, |
|||
}, |
|||
{ |
|||
"name": "save_data", |
|||
"in": "header", |
|||
"required": True, |
|||
"schema": {"type": "boolean", "title": "Save Data"}, |
|||
}, |
|||
{ |
|||
"name": "if_modified_since", |
|||
"in": "header", |
|||
"required": False, |
|||
"schema": IsDict( |
|||
{ |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "If Modified Since", |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "string", |
|||
"title": "If Modified Since", |
|||
} |
|||
), |
|||
}, |
|||
{ |
|||
"name": "traceparent", |
|||
"in": "header", |
|||
"required": False, |
|||
"schema": IsDict( |
|||
{ |
|||
"anyOf": [{"type": "string"}, {"type": "null"}], |
|||
"title": "Traceparent", |
|||
} |
|||
) |
|||
| IsDict( |
|||
# TODO: remove when deprecating Pydantic v1 |
|||
{ |
|||
"type": "string", |
|||
"title": "Traceparent", |
|||
} |
|||
), |
|||
}, |
|||
{ |
|||
"name": "x_tag", |
|||
"in": "header", |
|||
"required": False, |
|||
"schema": { |
|||
"type": "array", |
|||
"items": {"type": "string"}, |
|||
"default": [], |
|||
"title": "X Tag", |
|||
}, |
|||
}, |
|||
], |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": {"application/json": {"schema": {}}}, |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
}, |
|||
}, |
|||
}, |
|||
} |
|||
} |
|||
}, |
|||
"components": { |
|||
"schemas": { |
|||
"HTTPValidationError": { |
|||
"properties": { |
|||
"detail": { |
|||
"items": { |
|||
"$ref": "#/components/schemas/ValidationError" |
|||
}, |
|||
"type": "array", |
|||
"title": "Detail", |
|||
} |
|||
}, |
|||
"type": "object", |
|||
"title": "HTTPValidationError", |
|||
}, |
|||
"ValidationError": { |
|||
"properties": { |
|||
"loc": { |
|||
"items": { |
|||
"anyOf": [{"type": "string"}, {"type": "integer"}] |
|||
}, |
|||
"type": "array", |
|||
"title": "Location", |
|||
}, |
|||
"msg": {"type": "string", "title": "Message"}, |
|||
"type": {"type": "string", "title": "Error Type"}, |
|||
}, |
|||
"type": "object", |
|||
"required": ["loc", "msg", "type"], |
|||
"title": "ValidationError", |
|||
}, |
|||
} |
|||
}, |
|||
} |
|||
) |
|||
Loading…
Reference in new issue