Quickstart

1. Install descanso

pip install descanso requests

2. Declare models for request and response body

from dataclasses import dataclass

@dataclass
class Todo:
    id: int
    user_id: int
    title: str
    completed: bool

3. Select serialization library. We recommend using adaptix.

You need to have descanso.Loader and descanso.Dumper implementations. Or just use adaptix.Retort

4. Configure RestBuilder instance. It is needed to reuse common step during request.

from adaptix import Retort
from descanso import RestBuilder

rest = RestBuilder(
    request_body_dumper=Retort(),
    response_body_loader=Retort(),
    query_param_dumper=Retort(),
)

5. Create client class. Use RequestsClient or AiohttpClient

from descanso.http.requests import RequestsClient

class RealClient(RequestsClient):
    ...

6. Declare methods using rest.get/rest.post/rest.delete/rest.patch/rest.put decorators. Type hints are required. Body of method is ignored.

• First decorator params is an URL template as a python Format-string. You can reference any method params here (including self)

• By default, parameter called body is used as a request body.

• All other method params are treated as query params.

• Type hints are important

To customize this behavior refer Configuration

from descanso.http.requests import RequestsClient

class RealClient(RequestsClient):
    @rest.get("todos/{id}")
    def get_todo(self, id: str) -> Todo:
        pass

    @rest.get("todos")
    def list_todos(self, user_id: int | None) -> list[Todo]:
        pass

    @rest.delete("todos/{id}")
    def delete_todo(self, id: int):
        pass

    @rest.post("todos")
    def create_todo(self, body: Todo) -> Todo:
        pass

7. Create client instance and use it.

from requests import Session

client = RealClient(
    base_url="https://example.com/api",
    session=Session()
)
client.get_todo(5)