Metadata-Version: 2.4
Name: clientele
Version: 0.10.0
Summary: Generate loveable Python HTTP 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: click>=8.1.3
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.2
Requires-Dist: openapi-core>=0.19.0
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.4.2
Requires-Dist: ruff>=0.1.2
Requires-Dist: types-pyyaml>=6.0.12.11
Description-Content-Type: text/markdown

# ⚜️ Clientele

## Generate loveable Python HTTP API Clients

[![Package version](https://img.shields.io/pypi/v/clientele?color=%2334D058&label=latest%20version)](https://pypi.org/project/clientele)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/clientele?label=python%20support)
![PyPI - Downloads](https://img.shields.io/pypi/dm/clientele)
![PyPI - License](https://img.shields.io/pypi/l/clientele)

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)

```sh
brew tap phalt/clientele
brew install clientele
```

### With pipx (Python)

```sh
pipx install clientele
```

### With uv (Python)

```sh
uv tool install clientele
```

## Quick Start

```sh
# 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

```py
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:

```py
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](https://github.com/phalt/clientele/blob/main/example_openapi_specs/best.json) we use for documentation and testing only requires [250 lines of code](https://github.com/phalt/clientele/tree/main/tests/test_client) and 5 files.

## Async support

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

```py
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](https://fastapi.tiangolo.com/)'s and [drf-spectacular](https://github.com/tfranzel/drf-spectacular)'s OpenAPI schema generator.
* The generated client only depends on [httpx](https://www.python-httpx.org/) and [Pydantic 2.9+](https://docs.pydantic.dev/latest/).
* 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](https://lundberg.github.io/respx/).
* API updated? Just run the same command again and check the git diff.
* Automatically formats the generated client with [Ruff](https://docs.astral.sh/ruff/).
