Clientele

When using decorators like @client.get(...), Clientele needs to provide the parsed HTTP response to your function. To do this without forcing the caller to provide the response manually, Clientele uses injected parameters.

These parameters (result and response) are included in your function definition so you can use them inside the function body, but Clientele strips them from the public signature. This means callers and IDEs only see the parameters they are supposed to provide (like path or query parameters), while the injected parameters remain invisible to the caller.

# What you write:
def get_user(result: User, user_id: int) -> User

# What your IDE and type checker see after decoration:
def get_user(user_id: int) -> User

Clientele is 100% compatible with OpenAPI schemas generated by the following Python frameworks:

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

Django Ninja Schema objects are automatically converted into Pydantic BaseModel classes within the generated client's schemas module. This provides full type safety for both request payloads and response bodies.

• Requests: Pass a schema instance to the data argument of a client method.
• Responses: The returned object is typed as the corresponding schema (e.g., schemas.UserOut).

# In my_client/schemas.py
import pydantic

class UserIn(pydantic.BaseModel):
    username: str
    email: str
    age: int

class UserOut(pydantic.BaseModel):
    id: int
    username: str
    email: str
    age: int
    created_at: datetime

# Usage
user_data = schemas.UserIn(username="alice", email="alice@example.com", age=30)
response = client.create_user(data=user_data)

# response is typed as schemas.UserOut
print(response.id)

Clientele uses the type hint inside the AsyncIterator[T] (or Iterator[T]) to determine how to parse and hydrate each line of the stream:

• str: No parsing is performed; each yielded item is a raw string.
• dict: Each line is parsed as JSON into a dictionary.
• Pydantic Model: Each line is parsed as JSON and validated against the provided Pydantic model.

This hydration happens automatically based on the type signature of the result parameter in your decorated function.

from typing import AsyncIterator
from pydantic import BaseModel

class Token(BaseModel):
    text: str
    id: int

# Using Pydantic for automatic JSON parsing and validation
@client.get("/stream", streaming_response=True)
async def stream_tokens(*, result: AsyncIterator[Token]) -> AsyncIterator[Token]:
    return result

By default, Clientele generates client method names by combining the operation_id from the OpenAPI schema with the HTTP method (e.g., list_users_api_users_get).

To get cleaner, more readable method names in your Python client, define a custom operation_id in your Django Ninja decorators. Clientele will use this exact string as the method name.

Example Transformation:

• Default: @api.get("/users") $\rightarrow$ client.list_users_api_users_get()
• Custom: @api.get("/users", operation_id="list_users") $\rightarrow$ client.list_users()

from ninja import NinjaAPI

api = NinjaAPI()

# This results in client.list_users()
@api.get("/users", operation_id="list_users")
def get_users(request):
    return []

# This results in client.create_user()
@api.post("/users", operation_id="create_user")
def create_user(request, user: UserIn):
    return user

Clientele offers two ways to interact with APIs. Choosing between them depends on your use case.

Direct Requests (APIClient.request)

Best for: Small, ad-hoc requests.

What you get:

• Strongly typed responses
• Automatic data validation on responses
• Response hydration into Pydantic models

What you lose:

• Strongly typed inputs for parameters (inputs are passed as kwargs)
• An abstract functional interface to the API
• Support for streaming responses

Decorated Functions

Best for: Primary API integration and structured client code.

What you get:

• Strongly typed inputs
• Abstract functional interface
• Streaming response support

The Clientele API supports both synchronous (def) and asynchronous (async def) function definitions within the same APIClient instance. You can define standard synchronous endpoints alongside asynchronous ones to suit your specific logic requirements or integration needs.

from clientele import api as clientele_api
from .my_config import Config
from .my_models import BookResponse, CreateBookResponse, CreateBookRequest

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

# A synchronous endpoint
@client.post("/books")
def create_user(
    result: CreateBookResponse,
    data: CreateBookResponse,
) -> CreateBookResponse:
    return result

# An asynchronous endpoint in the same client
@client.get("/book/{book_id}")
async def get_book(result: BookResponse, book_id: int) -> BookResponse:
    return result

By default, Clientele generates function names using the pattern {function_name}_{path}_{method} (e.g., get_users_users_get).

To get cleaner, more readable function names in your client, define a custom operation_id in your FastAPI route decorators. Clientele will use this exact string as the method name.

from fastapi import FastAPI

app = FastAPI()

# This will generate client.list_users()
@app.get("/users", operation_id="list_users")
def get_users():
    return []

# This will generate client.create_user()
@app.post("/users", operation_id="create_user")
def create_user(user: UserCreate):
    return user