⚜️ Clientele

Example code

from clientele import api
from .schemas import Pokemon

client = api.APIClient(base_url="https://pokeapi.co/api/v2/")

@client.get("/pokemon/{id}")
def get_pokemon_name(id: int, result: Pokemon) -> str:
    return result.name

See more examples

Why use Clientele?

• Just modern Python - Types, Pydantic, and HTTPX, that's it.
• Easy to learn - Clientele is visually similar to popular python API server frameworks.
• Easy to test - Works with existing tools like respx and pytest-httpx.
• Easy to configure - Clientele has sensible defaults and plenty of hooks for customisation.
• A comfortable abstraction - Focus on the data and the functionality, not the connectivity.
• OpenAPI support - Build your own client, or scaffold one from an OpenAPI schema.

Async support

@client.get("/pokemon/{id}")
async def get_pokemon_name(id: int, result: Pokemon) -> str:
    return result.name

Automatic data validation

from clientele import api as clientele_api
from .my_pydantic_models import CreateBookRequest, CreateBookResponse

client = clientele_api.APIClient(base_url="http://localhost:8000")


@client.post("/books")
def create_book(data: CreateBookRequest, result: CreateBookReponse) -> CreateBookResponse:
    return result

Streaming responses

from typing import AsyncIterator
from pydantic import BaseModel
from clientele import api

client = api.APIClient(base_url="http://localhost:8000")

class Event(BaseModel):
    text: str

@client.get("/events", streaming_response=True)
async def stream_events(*, result: AsyncIterator[Event]) -> AsyncIterator[Event]:
    return result

Works with Python API frameworks

Built and tested to be 100% compatible with the OpenAPI schemas generated from:

• FastAPI
• Django REST Framework via drf-spectacular
• Django Ninja

See the working demos in our server_examples/ directory.

OpenAPI support

Clientele can create scaffolding for an API client from an OpenAPI schema with:

• Pydantic models generated from the schema objects.
• Smart function signatures generated from schema operations.
• Async support if you want a client with concurrency.
• A tiny output that is only 3 files big.
• Regeneration-friendly - update your API, regenerate, review the git diff, then ship it!
• Formatted code thanks to Ruff.

API Client explorer

Clientele has an explore mode for quickly testing and debugging APIs through an interactive REPL:

# Explore an existing clientele-compatible client
uvx clientele explore -c my_clientele_client/

# Or generate a temporary client from any OpenAPI service on the web
uvx clientele explore -u https://raw.githubusercontent.com/PokeAPI/pokeapi/master/openapi.yml
# 🤫 Pssst! Copy and paste this right now to try it!

• Autocomplete for operations and schemas.
• Execute API operations to test the API.
• Inspect schemas to see what the objects look like.
• Modify configuration within the REPL as you're testing.

Getting Started

👉 Read the full documentation for all documentation.