⚜️ Clientele

      ___ _ _            _       _
     / __\ (_) ___ _ __ | |_ ___| | ___
    / /  | | |/ _ \ '_ \| __/ _ \ |/ _ \
   / /___| | |  __/ | | | ||  __/ |  __/
   \____/|_|_|\___|_| |_|\__\___|_|\___|

Clientele API

Clientele lets your write API clients as easily as you would write API servers:

# api.py
from clientele import api as clientele_api
from .my_config import Config
from .my_models import Book, CreateBookReponse, CreateBookRequest

client = clientele_api.APIClient(config=Config())

# Mix sync and async functions in the same client
@client.get("/book/{book_id}")
async def get_book(book_id: int, result: Book) -> Book:
    return result


# Return only what you need from the API
@client.get("/book/{book_id}")
def get_book_title(book_id: int, result: Book) -> str:
    return result.title

# POST, PUT, PATCH, DELETE all supported
@client.post("/books")
def create_user(
    data: CreateBookRequest,
    result: CreateBookReponse,
) -> CreateBookReponse:
    return result

Clientele allows you to build elegant API integrations:

# service.py
import api

# Handle async requests
book_response = await api.get_book(book_id=123)

# Or sync requests
book_title = api.get_book_title(book_id=123)

response = api.create_book(
    data=schemas.CreateBookRequest(title="My awesome book")
)

match response:
    case schemas.CreateBookResponse():
        # handle valid response
    case schemas.ValidationError():
        # handle errors

OpenAPI client generator

Clientele can scaffold an API client from an OpenAPI schema with:

• A developer-first approach designed for a loveable developer experience.
• Pydantic models for request and response validation.
• Fully-typed function signatures for IDE autocomplete and type checking.
• Async support if you want a client with concurrency.
• A tiny output - clientele is readable, debuggable Python.
• Regeneration-friendly - update your API, regenerate, review the git diff, then ship it!
• Configuration: that's never overwritten on regeneration.
• Testing is easy peasy with respx.
• Formatted output with Ruff.

API CLI 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!

Explorer Features

• Autocomplete for operations and schemas.
• Execute API operations with Python-like syntax.
• Syntax-highlighted JSON responses.
• Navigate previous commands like a python shell.
• Modify configuration within the REPL as you're testing.
• Run debug mode to see diagnostics and errors.

Works with your favourite Python API Servers

We have specifically built and tested Clientele to be 100% compatible with OpenAPI schemas generated from:

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

We have working example servers in the server_examples/ directory.

These examples match the code shown in our documentation and provide real, working servers you can run locally to test out Clientele.

OpenAPI Compatibility

Clientele is compatible with OpenAPI 3.0+ schemas.

We test Clientele against 2000+ real-world OpenAPI schemas from the APIs.guru OpenAPI Directory through a CI cron job.

As of our latest run, we successfully generate clients for 95.39% of schemas in the directory.

Getting Started

👉 Read the full documentation for all documentation.