unihttp

unihttp

unihttp is a modern library for creating declarative API clients.

Table of Contents

• Features
• Installation
• Serialization Backends
• Quick Start
  • 1. Define Methods
  • 2. Client Implementation Strategies
• Markers Reference
• Middleware
• Error Handling
  • 1. Method-Level Handling
  • 2. Client-Level Handling
  • 3. Middleware-Level Handling
  • 4. Response Body Validation
• Custom JSON Serialization
• Powered by Adaptix
• Pydantic Integration
• msgspec Integration
• Agent Skills

Features

• Declarative: Define API methods using standard Python type hints.
• Type-Safe: Full support for static type checking.
• Backend Agnostic: Works with httpx, httpx2, aiohttp, requests, niquests, zapros and the standard library urllib.
• Extensible: Powerful middleware and error handling systems.

Installation

pip install unihttp

To include a specific HTTP backend (recommended):

pip install "unihttp[httpx]"    # For HTTPX (Sync/Async) support
# OR
pip install "unihttp[httpx2]"   # For HTTPX2 (Sync/Async) support
# OR
pip install "unihttp[niquests]"  # For niquests (Sync/Async) support
# OR
pip install "unihttp[requests]" # For Requests (Sync) support
# OR
pip install "unihttp[aiohttp]"  # For Aiohttp (Async) support
# OR
pip install "unihttp[zapros]"   # For Zapros (Sync/Async) support

The standard library urllib backend (UrllibSyncClient) requires no extra — it works out of the box with a plain pip install unihttp, which is handy for dependency-free environments.

Serialization Backends

unihttp allows you to choose your preferred serialization framework:

1. Adaptix (recommended): High-performance serialization for standard Python types (dataclasses, TypedDict).
2. Pydantic: Native support for Pydantic models.
3. msgspec: Native support for msgspec.Struct models — ideal if you already define your models as structs and want them serialized directly.

You will need to pass the appropriate request_dumper and response_loader when initializing your client. See Powered by Adaptix, Pydantic Integration or msgspec Integration for configuration details.

Quick Start

1. Define Methods

unihttp uses markers to map method arguments to HTTP request components.

from dataclasses import dataclass
from unihttp import BaseMethod, Path, Query, Body, Header, Form, File


@dataclass
class User:
    id: int
    name: str
    email: str


@dataclass
class GetUser(BaseMethod[User]):
    __url__ = "/users/{id}"
    __method__ = "GET"

    id: Path[int]
    compact: Query[bool] = False


@dataclass
class CreateUser(BaseMethod[User]):
    __url__ = "/users"
    __method__ = "POST"

    name: Body[str]
    email: Body[str]

2. Client Implementation Strategies

You can choose between a purely declarative style using bind_method or a more imperative style using call_method.

Option A: Declarative Client (via bind_method)

This is the most concise way to define your client. You simply bind the methods to the client class.

[!NOTE] PyCharm Users: There is currently a known issue with displaying type hints for descriptors like bind_method ( see PY-51768). This is expected to be fixed in the 2026.1 version.

from unihttp import bind_method
from unihttp.clients.httpx import HTTPXSyncClient
from unihttp.serializers.adaptix import DEFAULT_RETORT


class UserClient(HTTPXSyncClient):
    get_user = bind_method(GetUser)
    create_user = bind_method(CreateUser)


client = UserClient(
    base_url="https://api.example.com",
    request_dumper=DEFAULT_RETORT,
    response_loader=DEFAULT_RETORT
)
user = client.get_user(id=123)

Option B: Imperative Client (via call_method)