Hello folks.

I recently built an API client library that is heavily inspired by the style of FastAPI and how it leverages decorators and types.

from clientele import api

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

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

# Mix async and sync in client
@client.get("/pokemon/{id}")
async def get_pokemon(id: int, result: dict) -> dict:
    return result

Strongly typed validation

You can use types to enforce data validation on the responses:

from clientele import api
from pydantic import BaseModel

class Book(BaseModel):
    title: str
    author: str

client = api.APIClient(base_url="http://localhost:8000")

@client.get("/book/{book_id}")
def get_book(book_id: int, result: Book) -> Book:
    return result

# Or just return the data you want!
@client.get("/book/{book_id}")
def get_book_title(book_id: int, result: Book) -> str:
    return result.title

You can do the same when you're sending POST/PUT/PATCH/DELETE requests too:

from clientele import api as api
from .my_pydantic_models import CreateBookRequest, CreateBookResponse

client = api.APIClient(base_url="http://localhost:8000")


# Strongly typed inputs and outputs
@client.post("/books")
def create_book(data: CreateBookRequest, result: CreateBookReponse) -> CreateBookResponse:
    return result

Other features

• Control the response parsing with either a response_parser callback or a simple response_map.
• Configure the http layer (it's built on httpx) easily, or pass your own httpx.Client if you prefer full control.
• Use FastAPI's OpenAPI schema to scaffold an entire API client with a command line tool - generates all operations and schemas for you.

But, why?

One of FastAPI's successes is the way they use decorators and types:

• Functions are a popular unit for encapsulating endpoint behaviour.
• Decorators are popular for declaring the configuration for those endpoints.
• Types are amazing for documentation and validation.

I took that idea and applied it to a client library to see if it would work, and I think it does?

Docs etc

Project can be found at https://github.com/phalt/clientele - please ⭐ if you like it!

Documentation can be found at https://clientele.spice.tools/

Background and the original blog post where I explored this idea: https://paulwrites.software/articles/python-api-clients

What do you think?

Give it a try, and let me know what you think 😸