Valentyn
4 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 |
# For mkdocstrings and tests |
||||
httpx >=0.23.0,<0.28.0 |
httpx >=0.23.0,<0.28.0 |
||||
# For linting and generating docs versions |
# 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