Eazy SDK

Библиотека для Python, на которой пишут типизированные SDK к чужим HTTP API, WebSocket и сайтам. Запрос объявляется классом, ответ разбирается в модель, а вход, обновление сессии, подпись, повторы и пагинация описываются рядом с операцией и не попадают в код вызова.

Статус: alpha, версия 0.2.0a12. Альфа-версии переименовывают публичные имена без устаревших псевдонимов, список замен ведёт страница «Миграция». Документация собирается в сайт из docs-site/ и публикуется на GitHub Pages.

Что это даёт

• Операция описана один раз: поля класса задают путь, query, заголовки и тело, а тип результата виден редактору и тайпчекеру.
• Один и тот же роутер работает через HTTPX, Requests, curl_cffi или свой обработчик. Пакет без дополнений не ставит ни HTTP-клиент, ни библиотеку моделей.
• Ответы разбираются в Pydantic, msgspec, dataclass или Adaptix. Ошибка API внутри ответа с кодом 200 становится типизированным исключением.
• Вход, обновление сессии по сроку и по отказу, подпись HMAC, шифрование тела, капча и пагинация объявляются декларативно и срабатывают на каждой попытке.
• Тот же SDK может работать через браузер: операции страницы на Playwright или Pydoll и сессия браузера у HTTP-клиента.
• Генераторы собирают SDK из OpenAPI 3.0-3.2 и AsyncAPI 3.0.

HTTP-клиент, браузер и хранилище аккаунтов остаются за приложением: SDK получает их готовыми.

Установка

Нужен Python 3.13 или новее.

pip install --pre "eazy-sdk-core[httpx,pydantic]"

На PyPI пакет называется eazy-sdk-core, а импортируется как eazy_sdk. Проект eazysdk на PyPI к этой библиотеке отношения не имеет. Флаг --pre нужен, пока выходят только альфа-версии. Те же файлы приложены к каждому релизу GitHub.

Всё поставляется одним пакетом. Дополнения ставят только сторонние библиотеки и выбираются по задаче: httpx, requests, curl-cffi, websocket, pydantic, msgspec, adaptix, html, xml, openapi, asyncapi, accounts, sqlmodel, browser, playwright, pydoll, presets. Полная таблица есть на странице «Установка».

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

Скрипт ниже получает одно письмо с учебного сайта mail.example. Сайт отвечает в том же процессе, поэтому для знакомства хватит одного файла и сети не нужно.

# quickstart.py
from dataclasses import dataclass

import httpx
from pydantic import BaseModel

from eazy_sdk import Client, Http, HttpOperation, Path, SyncApi, op
from eazy_sdk.handlers.httpx import HttpxHandler


class Message(BaseModel):
    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):
    message = op(GetMessage)  # операция становится методом роутера


def mail_site(request: httpx.Request) -> httpx.Response:
    # учебный сайт в этом же процессе; в приложении запрос уходит в сеть
    return httpx.Response(
        200,
        json={"id": 42, "sender": "ada@mail.example", "subject": "Планы на пятницу"},
    )


raw = httpx.Client(transport=httpx.MockTransport(mail_site))

with Client(
    base_url="https://mail.example",
    handler=HttpxHandler(raw, owns_client=True),
) as client:
    message = MailApi(client).message(message_id=42)
    response = MailApi(client).message.with_response(message_id=42)

print(f"{message.sender}: {message.subject}")
print(response.status_code)

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

Что здесь произошло:

1. GetMessage описал запрос как значение. __http__ задал метод и путь, поле message_id подставилось в путь, а HttpOperation[Message] назвал тип успешного ответа.
2. op(GetMessage) опубликовал операцию на роутере. Сигнатура метода message совпадает с конструктором класса, поэтому редактор подсказывает message_id.
3. Клиент доставил байты и разобрал JSON в Message. Роутер о транспорте не знает: в приложении вместо двух строк с raw достаточно Client.httpx(base_url=...).
4. .with_response() вернул тот же результат вместе со статусом и заголовками.

Дальше

Запускаемые примеры ко всем страницам лежат в examples/.

Для ИИ-ассистентов

Сайт документации отдаёт два текстовых файла, собранных из тех же страниц:

• llms.txt содержит краткое описание проекта и ссылки на страницы. Он подходит помощнику, который умеет открывать ссылки: в контекст попадают только нужные страницы.
• llms-full.txt содержит полный текст документации одним файлом. Он подходит для локального поиска и для инструмента, который по ссылкам не ходит.

Оба файла обновляются при каждой публикации сайта, отдельную копию документации поддерживать не нужно.

Разработка

Нужен uv. Браузерным тестам нужен Chromium.

uv sync --all-extras            # окружение и все инструменты
uv run playwright install chromium             # браузер для тестов плагина
uv run pytest -q                               # тесты
uv run mypy                                    # типы
uv run ruff check                              # линтер
uv run python scripts/docs_freshness.py check  # страницы не отстали от кода

Порядок работы описан в CONTRIBUTING.md, об уязвимостях сообщают по SECURITY.md. План архитектуры лежит в docs/implementation/.

Лицензия

MIT