Объявить HTTP-операцию#

Объявите запрос неизменяемым классом HttpOperation[T]. Поля класса становятся аргументами вызова, __http__ хранит HTTP-контракт, а op(...) публикует операцию на роутере. Редактор кода видит сигнатуру до запуска программы.

Это основной вариант. Он сохраняет отдельный тип запроса, поддерживает фабрики значений по умолчанию и позволяет переиспользовать общие поля через обычное наследование моделей.

→ Request · POST /orders

{"item": "keyboard"}

← Response · 201 Created

{"id": "order-42", "item": "keyboard"}

Объявить операцию классом#

# examples/docs/request_declaration.py
@dataclass(frozen=True, slots=True, kw_only=True)
class CreateOrder(HttpOperation[Order]):
    __http__ = Http.post("/orders", success={201: Order})

    item: JsonField[str]


class OrdersApi(SyncApi):
    create = op(CreateOrder)

Order задаёт тип успешного ответа. success={201: Order} связывает статус 201 с этой моделью. Маркер JsonField[str] помещает item в JSON-тело. kw_only=True делает все аргументы именованными, поэтому добавление нового поля не меняет смысл старых вызовов.

Использовать короткий декоратор#

# examples/docs/request_declaration.py
class CompactOrdersApi(SyncApi):
    @api.post("/orders", success={201: Order})
    def create(
        self,
        *,
        item: Annotated[str, markers.JsonField()],
    ) -> Order:
        raise NotImplementedError

Декоратор синтезирует такой же неизменяемый класс и публикует его тем же дескриптором. Python не выполняет тело метода во время вызова SDK. Полученный класс доступен как CompactOrdersApi.create.Operation.

Файл примера целиком
"""Declare the same operation as a class and with the compact decorator."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Annotated

from eazy_sdk import Http, HttpOperation, JsonField, SyncApi, api, op
from eazy_sdk.request import markers
from examples.docs.request_site import request_client


@dataclass(frozen=True, slots=True)
class Order:
    id: str
    item: str


# docs:class:start
# examples/docs/request_declaration.py
@dataclass(frozen=True, slots=True, kw_only=True)
class CreateOrder(HttpOperation[Order]):
    __http__ = Http.post("/orders", success={201: Order})

    item: JsonField[str]


class OrdersApi(SyncApi):
    create = op(CreateOrder)
# docs:class:end


# docs:decorator:start
# examples/docs/request_declaration.py
class CompactOrdersApi(SyncApi):
    @api.post("/orders", success={201: Order})
    def create(
        self,
        *,
        item: Annotated[str, markers.JsonField()],
    ) -> Order:
        raise NotImplementedError
# docs:decorator:end


def main() -> None:
    with request_client() as client:
        declared = OrdersApi(client).create(item="keyboard")
        compact = CompactOrdersApi(client).create(item="mouse")

    print(f"class: {declared.id} {declared.item}")
    print(f"decorator: {compact.id} {compact.item}")


if __name__ == "__main__":
    main()

Запуск: uv run python examples/docs/request_declaration.py.

class: order-42 keyboard
decorator: order-42 mouse

Задача

Класс и op(...)

Декоратор

default_factory, наследование полей, проекция

подходит

ограничен сигнатурой метода

запрос как отдельное значение

прямой класс операции

синтезированный .Operation

короткая операция без сложного тела

больше строк

компактнее

Дальше#