⚜️ Clientele

Clientele generates fully-typed, idiomatic python HTTP API clients from OpenAPI 3.0+ schemas.

It is designed and tested to work seamlessly with:

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

What Clientele Does

Clientele transforms your OpenAPI schema into a clean, maintainable Python HTTP client with:

• Pydantic models for request and response validation.
• Fully-typed function signatures for IDE autocomplete and type checking.
• Async support through httpx if you need it.
• Your preferences - class-based or functional, you can choose.
• Minimal footprint - the generated code is readable, debuggable Python with only two dependencies.
• Regeneration-friendly - update your API, regenerate, review the git diff, ship it!
• API REPL - a dedicated REPL for exploring and testing the client.
• Deterministic: No exepensive LLMs, no hallucinations - same input always produces same output.

When to Use Clientele

Consumer

• You want to use an HTTP API that has an OpenAPI schema
• And you want to consume that API from another Python service
• And you need type safety and validation without manual schema maintenance
• And you want code that is readable, maintainable, and extendable to suit your project

Publisher

• You have an HTTP API that has an OpenAPI schema
• And you want to offer a client library in Python
• And you don't want the overhead of maintaining it

Quick Start

# Best installed as a tool
uv tool install clientele
# Generate a client from the PokeAPI OpenAPI schema
clientele generate -u https://raw.githubusercontent.com/PokeAPI/pokeapi/master/openapi.yml -o pokeapi_client/
# Load the REPL to start testing with the generated code immediately
clientele explore -c pokeapi_client/

The generated code

We offer many different flavours of client to suit your needs:

Function-based client

from my_api import client, schemas

# Pydantic models for inputs and outputs
data = schemas.CreateBookRequest(title="My awesome book")

# Easy to read client functions
response = client.create_book(data=data)

# Handle responses elegantly
match response:
    case schemas.CreateBookResponse():
        # Handle valid response
        ...
    case schemas.ValidationError():
        # Handle validation error
        ...

Class-based client

from my_api.client import Client
from my_api import schemas

# Instantiate the client
client = Client()

# Pydantic models for inputs and outputs
data = schemas.CreateBookRequest(title="My awesome book")

# Call API methods on the client instance
response = client.create_book(data=data)

# Handle responses elegantly
match response:
    case schemas.CreateBookResponse():
        # Handle valid response
        ...
    case schemas.ValidationError():
        # Handle validation error
        ...

Async support

For both class-based and functional clients we can produce async versions:

from my_async_api import client

# Async client functions
response = await client.list_books()

API Explorer

Clientele includes an interactive REPL that lets you explore and test APIs without writing any code:

# Explore an existing client
clientele explore -c pokeapi_client/

# Or generate a temporary client from any OpenAPI service on the web and start using it immediately
clientele explore -u https://raw.githubusercontent.com/PokeAPI/pokeapi/master/openapi.yml

═══════════════════════════════════════════════════════════
  Clientele Interactive API Explorer v1.0.0
═══════════════════════════════════════════════════════════

Type /help or ? for commands, /exit or Ctrl+D to quit
Type /list to see available operations

Press TAB for autocomplete

>>>

Explorer Features

• Autocomplete: Press TAB to discover operations and parameters with type hints.
• Execute instantly: Execute API operations with Python-like syntax.
• Beautiful output: Syntax-highlighted JSON responses.
• Command history: Navigate previous commands with UP/DOWN arrows.
• Local config: Modify configuration locally as you're testing.
• Debug mode: Run debug mode to see diagnostics and errors.

OpenAPI Compatibility

Clientele works by traversing OpenAPI 3.0+ schemas.

Any framework or tool that generates standards-compliant OpenAPI schemas should work with Clientele.

Verified Compatibility

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 93.86% of schemas in the directory.

Additionally we have specifically built and tested Clientele to support:

• FastAPI - 100% compatibility with FastAPI's built-in OpenAPI schema generation.
• Django REST Framework with drf-spectacular - Full support for DRF's OpenAPI schemas.
• Django Ninja - Works with Django Ninja's OpenAPI output.

Server Examples

Working example server applications are available in the server_examples/ directory. Read more about each in our documentation:

• FastAPI - See server_examples/fastapi/
• Django REST Framework - See server_examples/django-rest-framework/
• Django Ninja - See server_examples/django-ninja/

These examples match the code shown in our framework-specific documentation and provide real, working servers you can run locally to test Clientele's client generation.

Additional Features

• Authentication: HTTP Basic and HTTP Bearer authentication built-in.
• Configuration: A config.py entry point that's never overwritten on regeneration.
• Testing: Designed for easy testing thanks to respx.
• Formatting: Automatically formats generated code with Ruff.

Getting Started

👉 See our framework-specific guides for FastAPI, Django REST Framework, and Django Ninja

👉 Read the full documentation for advanced usage