pyyhi

pyyhi is a Python library that aims to simplify configuring and consuming HTTP APIs by using YAML definitions. It provides a YAML-first approach to declare base URLs, endpoints, headers, authentication, and payload schemas, then exposes Python callables that execute the defined operations. The project targets reducing boilerplate in multi-service environments while keeping configuration human-readable and portable.

Key features include a YAML-based configuration format, support for synchronous and asynchronous transports, pluggable authentication backends, automatic retries with backoff, and helpers for JSON and form data. It integrates with common HTTP backends such as httpx and aiohttp and relies on PyYAML for parsing. Generated clients emphasize a stable, typed interface and straightforward error handling.

Architecture centers on three concepts: a Config loader that reads and validates the YAML file, a Client that issues requests, and Endpoint definitions that bind path templates to methods. Transport adapters translate high-level calls to concrete HTTP requests. The library favors explicit configuration over ad-hoc HTTP calls and strives for predictable error reporting.

History: pyyhi was created by a community-driven team in 2021 to reduce repetitive API client code. It has seen regular maintenance and several major releases through 2024, with adoption primarily among small and mid-sized teams. The project is released under the MIT license and is hosted publicly on common package indexes and version-control platforms.

Example usage: After loading a YAML config, you instantiate a client for a service and perform requests. For instance, cfg = load_config('config.yaml'); client = Client.from_config(cfg, service='github'); r = client.get('/repos/owner/repo'); data = r.json()

Limitations: YAML syntax errors can prevent startup, and large configurations may introduce parsing overhead. Debugging often requires tracing the mapping from YAML endpoints to generated methods, and users may need to implement custom backends for niche authentication schemes.