HTTP-параметры

В этом разделе рассмотрим, как извлекать и проверять http-параметры с помощью Rapidy.

Основы извлечения и валидации данных

Для проверки и извлечения данных из входящего HTTP-запроса Rapidy использует свои внутренние типы данных — rapidy-параметры.

Пример ниже извлекает и проверяет переменную динамического пути user_id и заголовок Host:

from rapidy.http import get, PathParam, Header

@get('/{user_id}')
async def handler(
    user_id: int = PathParam(),
    host: str = Header(alias='Host'),
) -> ...:

Что такое rapidy-параметр?

Rapidy-параметр — это мета-объект, содержащий информацию о том, как именно будут извлекаться параметры из входящего HTTP-запроса.

Все rapidy-параметры находятся в модуле rapidy.parameters.http:

from rapidy.parameters.http import Header, Cookie, QueryParam, ..., Body

async def handler(
    user_id: int = QueryParam(),
) -> ...:
    ...

Также доступ к ним можно получить через модуль rapidy.http:

from rapidy.http import Header, Cookie, QueryParam, ..., Body

async def handler(
    user_id: int = QueryParam(),
) -> ...:
    ...

Параметры http-запроса

Подробнее о каждом типе параметров можно узнать в соответствующих разделах:

Path — параметры пути (используются для создания динамических API)
Headers — параметры заголовков запроса
Cookies — параметры cookie (извлекаются из заголовков автоматически)
Query Parameters — параметры запроса, передаваемые в URL
Body — параметры тела запроса

Извлечение данных

Для извлечения данных используется имя атрибута или alias rapidy-параметра.

Извлечение по имени атрибута

from rapidy.http import QueryParam

async def handler(
    test_query_param_name: int = QueryParam(),
) -> int:
    return test_query_param_name

curl -G -v -d "test_query_param_name=123456789" http://127.0.0.1:8080
# < HTTP/1.1 200 OK ...
# 123456789

Извлечение по alias

from rapidy.http import QueryParam

async def handler(
    test_query_param_name: int = QueryParam(alias='TestQueryParamName'),
) -> int:
    return test_query_param_name

curl -G -v -d "TestQueryParamName=123456789" http://127.0.0.1:8080
# < HTTP/1.1 200 OK ...
# 123456789

Возможности валидации

Каждый rapidy-параметр является наследником pydantic.Field и поддерживает все его функции.

@get('/')
async def handler(
    positive: int = QueryParam(gt=0),
    non_negative: int = QueryParam(ge=0),
    negative: int = QueryParam(lt=0),
    non_positive: int = QueryParam(le=0),
    even: int = QueryParam(multiple_of=2),
    love_for_pydantic: float = QueryParam(allow_inf_nan=True),
    short: str = QueryParam(min_length=3),
    long: str = QueryParam(max_length=10),
    regex: str = QueryParam(pattern=r'^\d*$'),
    precise: Decimal = QueryParam(max_digits=5, decimal_places=2),
) -> ...:
    ...

Способы аннотации параметров

Передача параметра как значения по умолчанию

Самый простой и понятный способ аннотации:

from rapidy.http import get, PathParam

@get('/{user_id}')
async def handler(
    user_id: int = PathParam(),
) -> ...:
    ...

Однако, если вы используете статические анализаторы кода, например, mypy, могут возникнуть ошибки:

main.py:4: error: Incompatible default for argument "user_id" (default has type "PathParam", argument has type
"int")  [assignment]

Чтобы этого избежать, включите mypy-плагин для Rapidy:

# pyproject.toml
[tool.mypy]
plugins = [
    "pydantic.mypy",
    "rapidy.mypy"     # <-- включение плагина Rapidy
]

Аннотация с использованием `typing.Annotated`

Подробнее о typing.Annotated можно прочитать в официальной документации Python здесь.

from typing import Annotated
from rapidy.http import get, PathParam

@get('/{user_id}')
async def handler(
    user_id: Annotated[int, PathParam()],
) -> ...:
    ...

В аннотации Annotated используются два ключевых аргумента:

Первый аргумент Annotated[int, ...] определяет ожидаемый тип данных (в данном случае, int).
Последний аргумент Annotated[..., PathParam()] должен быть одним из HTTP-параметров Rapidy (Header, Headers, Cookie, ..., Body). В данном случае сервер ожидает заголовок Host.

Так как Annotated может принимать неограниченное количество параметров, Rapidy использует только первый и последний аргумент для валидации. Остальные параметры может использовать pydantic в качестве мета-информации для модели, для дополнительных проверок, если он их поддерживает.

Отсутствие HTTP-параметров в Annotated

Если Annotated не содержит HTTP-параметра, например, Annotated[str, str], атрибут будет проигнорирован.

Поддержка значений по умолчанию

Header(default=..., default_factory=...)

Подробнее о значениях по умолчанию можно прочитать в разделе каждого http-параметра.