⚜️ Clientele

What is Clientele?

Clientele is a comprehensive framework for building and maintaining API Integrations.

Focus on the functionality and the data you want from an API, and let Clientele handle the rest.

Build, test, and maintain API integrations confidently.

Example code

from clientele import api
from pydantic import BaseModel

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

class Pokemon(BaseModel):
    name: str

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

See more examples

Why use Clientele?

• A comfortable abstraction - Encourages consistency and focus on the functionality.
• Easy to learn - Clientele is visually similar to popular python API server frameworks.
• Easy to test - All the testing tools you need to maintain API integrations.
• Easy to configure - Sensible HTTP defaults and plenty of hooks for customisation.
• Easy data validation - Built in data validation using Pydantic.
• Core built-ins - Caching, Network, and Retry handling built specifically for HTTP.
• Use your own HTTP - Clientele can support any Python HTTP library.
• OpenAPI support - Build your own client, or scaffold one from an OpenAPI schema.
• GraphQL support - Clientele has a GraphQLClient tailored for GraphQL APIs.

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: CreateBookResponse) -> CreateBookResponse:
    return result

GraphQL support

from pydantic import BaseModel
from clientele.graphql import GraphQLClient

client = GraphQLClient(base_url="https://api.github.com/graphql")

class Repository(BaseModel):
    name: str
    stargazerCount: int

class RepositoryQueryData(BaseModel):
    repository: Repository

class RepositoryQueryResponse(BaseModel):
    data: RepositoryQueryData

@client.query("""
    query($owner: String!, $name: String!) {
        repository(owner: $owner, name: $name) {
            name
            stargazerCount
        }
    }
""")
def get_repo(owner: str, name: str, result: RepositoryQueryResponse) -> Repository:
    return result.data.repository

Works with Python API frameworks

Building an API service in Python? Clientele can build you a client library in seconds.

Clientele is 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.
• Decorated 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.

Getting Started

👉 Read the full documentation for all documentation.