Быстрый старт#

Получим письмо 42 из учебного сервиса mail.example. Выберите библиотеку моделей, которую уже использует проект. Объявление HTTP-операции и вызов SDK во всех трёх вариантах одинаковы.

Команды установки ниже относятся к вашему проекту. Команды запуска проверяют готовые файлы из репозитория Eazy SDK: клонируйте репозиторий и выполняйте их из его корня. Эти файлы подключены к локальному учебному сайту, поэтому не отправляют запросы во внешнюю сеть.

Установите зависимости командой uv add "eazy-sdk-core[httpx,pydantic]".

# mail_sdk/messages.py
class Message(BaseModel):
    model_config = ConfigDict(frozen=True)

    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")

Message наследует BaseModel и запрещает изменение полей после проверки ответа.

Файл примера целиком
"""Read one message into a Pydantic response model."""

from dataclasses import dataclass

from pydantic import BaseModel, ConfigDict

from eazy_sdk import Http, HttpOperation, Path, SyncApi, op

from ._quickstart import quickstart_client


# region docs: quickstart-pydantic
# mail_sdk/messages.py
class Message(BaseModel):
    model_config = ConfigDict(frozen=True)

    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")
# endregion docs: quickstart-pydantic


if __name__ == "__main__":
    main()

Запуск: uv run python -m examples.mail.http.quickstart_pydantic.

ada@mail.example: Планы на пятницу

Стандартной библиотеке нужен только HTTP-клиент: uv add "eazy-sdk-core[httpx]".

# mail_sdk/messages.py
@dataclass(frozen=True, slots=True)
class Message:
    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")

@dataclass(frozen=True, slots=True) даёт неизменяемую модель без внешней зависимости.

Файл примера целиком
"""Read one message into a standard-library dataclass."""

from dataclasses import dataclass

from eazy_sdk import Http, HttpOperation, Path, SyncApi, op

from ._quickstart import quickstart_client


# region docs: quickstart-dataclass
# mail_sdk/messages.py
@dataclass(frozen=True, slots=True)
class Message:
    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")
# endregion docs: quickstart-dataclass


if __name__ == "__main__":
    main()

Запуск: uv run python -m examples.mail.http.quickstart_dataclass.

ada@mail.example: Планы на пятницу

Установите зависимости командой uv add "eazy-sdk-core[httpx,msgspec]".

# mail_sdk/messages.py
class Message(msgspec.Struct, frozen=True):
    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")

msgspec.Struct проверяет ответ и создаёт неизменяемый объект Message.

Файл примера целиком
"""Read one message into a msgspec Struct response model."""

from dataclasses import dataclass

import msgspec

from eazy_sdk import Http, HttpOperation, Path, SyncApi, op

from ._quickstart import quickstart_client


# region docs: quickstart-msgspec
# mail_sdk/messages.py
class Message(msgspec.Struct, frozen=True):
    id: int
    sender: str
    subject: str


@dataclass(frozen=True, slots=True, kw_only=True)
class GetMessage(HttpOperation[Message]):
    __http__ = Http.get("/messages/{message_id}")

    message_id: Path[int]


class MailApi(SyncApi):
    base_url = "https://mail.example"
    message = op(GetMessage)


def main() -> None:
    with quickstart_client() as client:
        message = MailApi(client).message(message_id=42)
    print(f"{message.sender}: {message.subject}")
# endregion docs: quickstart-msgspec


if __name__ == "__main__":
    main()

Запуск: uv run python -m examples.mail.http.quickstart_msgspec.

ada@mail.example: Планы на пятницу

Что произошло#

GetMessage хранит описание GET-запроса. Поле message_id: Path[int] принимает число от вызывающего кода и подставляет его в /messages/{message_id}. Тип HttpOperation[Message] выбирает модель успешного ответа.

Библиотека моделей меняет только объявление Message.

MailApi публикует операцию под именем message и задаёт адрес сервиса. Вызов MailApi(client).message(message_id=42) имеет ту же сигнатуру, что и класс GetMessage, поэтому редактор кода знает имя и тип аргумента до запуска программы.

Функция quickstart_client() подключает пример к локальному учебному сайту из репозитория. В прикладном SDK приложение создаёт Client, а роутер получает его готовым. Выбор HTTPX, Requests или curl_cffi не меняет объявление операции.

Следующий запрос#

Для POST добавьте поля тела с маркером JsonField. Вложенную структуру внешнего JSON собирает BodyProjection; вызывающему коду по-прежнему передаются обычные именованные аргументы. Эти механизмы разобраны в руководстве по запросам.

Когда методов станет несколько, объедините роутеры в корень SDK. Дальше можно изучить структуру запросов, HTTP-интеграции или всё руководство.