⚜️ Clientele

Generate loveable Python HTTP API Clients

Clientele lets you generate fully-typed, pythonic HTTP API Clients using an OpenAPI schema.

Installation

Install clientele as a global CLI tool:

With Homebrew (macOS/Linux)

brew tap phalt/clientele
brew install clientele

With pipx (Python)

pipx install clientele

With uv (Python)

uv tool install clientele

Quick Start

# Generate a client from an OpenAPI schema
clientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o api_client/

Generated code

The generated code is designed by python developers, for python developers.

It uses modern tooling and has a great developer experience.

Function-based client

from my_api import client, schemas

# Pydantic models for inputs and outputs
data = schemas.RequestDataRequest(my_input="test")

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

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

Class-based client

Prefer object-oriented programming? Use clientele generate-class to generate a client with a Client class:

from my_api.client import Client
from my_api import schemas

# Instantiate the client
client = Client()

# Pydantic models for inputs and outputs
data = schemas.RequestDataRequest(my_input="test")

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

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

The generated code is tiny - the example schema we use for documentation and testing only requires 250 lines of code and 5 files.

Async support

You can choose to generate either a sync or an async client - we support both:

from my_async_api import client

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

Other features

• Written entirely in Python.
• Designed to work with FastAPI's and drf-spectacular's OpenAPI schema generator.
• The generated client only depends on httpx and Pydantic 2.9+.
• HTTP Basic and HTTP Bearer authentication support.
• Support your own configuration - we provide an entry point that will never be overwritten.
• Designed for easy testing with respx.
• API updated? Just run the same command again and check the git diff.
• Automatically formats the generated client with Ruff.