Metadata-Version: 2.4
Name: clientele
Version: 1.4.0
Summary: Clientele is a different way to think about Python API Clients
Project-URL: Homepage, https://phalt.github.io/clientele/
Project-URL: Changelog, https://phalt.github.io/clientele/CHANGELOG/
Project-URL: Documentation, https://phalt.github.io/clientele/
Project-URL: Issues, https://github.com/phalt/clientele/issues
Author-email: Paul Hallett <paulandrewhallett@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: cicerone==0.3.0
Requires-Dist: cli-helpers>=2.4.0
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.0
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pygments>=2.19.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.2.0
Requires-Dist: ruff>=0.14.10
Requires-Dist: types-pyyaml>=6.0.12.20250915
Description-Content-Type: text/markdown

# ⚜️ Clientele

<div style="text-align: center;">

<pre>
      ___ _ _            _       _
     / __\ (_) ___ _ __ | |_ ___| | ___
    / /  | | |/ _ \ '_ \| __/ _ \ |/ _ \
   / /___| | |  __/ | | | ||  __/ |  __/
   \____/|_|_|\___|_| |_|\__\___|_|\___|</pre>
<p>⚜️ Clientele is a different way to think about Python API Clients</p>

</div>

[![Package version](https://img.shields.io/pypi/v/clientele?color=%2334D058&label=latest%20version)](https://pypi.org/project/clientele)
![Python versions](https://img.shields.io/badge/python-3.10+-blue)
![PyPI - License](https://img.shields.io/pypi/l/clientele)
[![codecov](https://codecov.io/github/phalt/clientele/graph/badge.svg?token=7OH7QLCGBM)](https://codecov.io/github/phalt/clientele)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/clientele?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/clientele)

![Works with](https://img.shields.io/badge/Works_with-FastAPI,_DRF,_Django_Ninja-green)
![OpenAPI Compatibility](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/phalt/clientele/main/.github/compatibility.json)


## Clientele API

Clientele lets your write API clients as easily as you would write API servers:

```python
# api.py
from clientele import api as clientele_api
from .my_config import Config
from .my_models import Book, CreateBookReponse, CreateBookRequest

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

# Mix sync and async functions in the same client
@client.get("/book/{book_id}")
async def get_book(book_id: int, result: Book) -> Book:
    return result


# Return only what you need from the API
@client.get("/book/{book_id}")
def get_book_title(book_id: int, result: Book) -> str:
    return result.title

# POST, PUT, PATCH, DELETE all supported
@client.post("/books")
def create_user(
    data: CreateBookRequest,
    result: CreateBookReponse,
) -> CreateBookReponse:
    return result
```

Clientele allows you to build elegant API integrations:

```python
# service.py
import api

# Handle async requests
book_response = await api.get_book(book_id=123)

# Or sync requests
book_title = api.get_book_title(book_id=123)

response = api.create_book(
    data=schemas.CreateBookRequest(title="My awesome book")
)

match response:
    case schemas.CreateBookResponse():
        # handle valid response
    case schemas.ValidationError():
        # handle errors
```

## OpenAPI client generator

Clientele can scaffold an API client from an OpenAPI schema with:

- **A developer-first approach** designed for a loveable developer experience.
- **Pydantic models** for request and response validation.
- **Fully-typed function signatures** for IDE autocomplete and type checking.
- **Async support** if you want a client with concurrency.
- **A tiny output** - clientele is readable, debuggable Python.
- **Regeneration-friendly** - update your API, regenerate, review the git diff, then ship it!
- **Configuration**: that's never overwritten on regeneration.
- **Testing** is easy peasy with [respx](https://lundberg.github.io/respx/).
- **Formatted output** with [Ruff](https://docs.astral.sh/ruff/).

![generate_gif](https://raw.githubusercontent.com/phalt/clientele/refs/heads/main/docs/clientele_generate.gif)

## API CLI explorer

Clientele has an `explore` mode for quickly testing and debugging APIs through an interactive REPL:

```sh
# Explore an existing clientele-compatible client
uvx clientele explore -c my_clientele_client/

# Or generate a temporary client from any OpenAPI service on the web
uvx clientele explore -u https://raw.githubusercontent.com/PokeAPI/pokeapi/master/openapi.yml
# 🤫 Pssst! Copy and paste this right now to try it!
```

![repl demo](https://raw.githubusercontent.com/phalt/clientele/refs/heads/main/docs/clientele.gif)

### Explorer Features

- **Autocomplete** for operations and schemas.
- **Execute API operations** with Python-like syntax.
- **Syntax-highlighted** JSON responses.
- **Navigate previous commands** like a python shell.
- **Modify configuration** within the REPL as you're testing.
- **Run debug mode** to see diagnostics and errors.

## Works with your favourite Python API Servers

We have specifically built and tested Clientele to be 100% compatible with OpenAPI schemas generated from:

- **FastAPI**
- **Django REST Framework** via **drf-spectacular**
- **Django Ninja**

We have working example servers in the [`server_examples/`](https://github.com/phalt/clientele/tree/main/server_examples) directory.

These examples match the code shown in our documentation and provide real, working servers you can run locally to test out Clientele.

## OpenAPI Compatibility

Clientele is compatible with OpenAPI 3.0+ schemas.

We test Clientele against 2000+ real-world OpenAPI schemas from the [APIs.guru OpenAPI Directory](https://github.com/APIs-guru/openapi-directory) through a CI cron job.

As of our latest run, we successfully generate clients for **95.39%** of schemas in the directory.

![OpenAPI Compatibility](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/phalt/clientele/main/.github/compatibility.json)

## Getting Started

👉 Read the [full documentation](https://phalt.github.io/clientele/) for all documentation.
