lothc

Lord Of The Http Clients — a typed HTTP client for Python, built on pyreqwest (an awesome Rust-backed HTTP client), with first-class optional support for pydantic and msgspec as both decode and encode targets, plus TypedDict (validated via typeguard if installed) as a decode target.

Installing

uv add 'lothc[pydantic,msgspec,typeguard]'

(Any subset of the extras works — the base package alone gets you bytes/JSON/TypedDict-without-validation support.)

Quickstart

from lothc import HTTPClient
from pydantic import BaseModel


class Pokemon(BaseModel):
    id: int
    name: str


async with HTTPClient.build(base_url="https://pokeapi.co/api/v2/") as client:
    pikachu = await client.get("pokemon/pikachu", response_data_type=Pokemon)
    print(pikachu)  # id=25 name='pikachu'

Why?

Why was lothc built, and why should you use it?

pyreqwest is a genuinely excellent HTTP client for Python, fast because the heavy lifting happens in Rust, not pure Python. But its API is a builder pattern (client.get(path).build() before you can even .send() it), unfamiliar to anyone coming from requests/httpx/niquests, where a call is just client.get(url, params=..., headers=...). lothc wraps pyreqwest with exactly that familiar shape, so you get pyreqwest's speed without giving up the ergonomics Python HTTP users already expect.

The other reason: Python's most popular third-party HTTP clients (httpx, aiohttp, niquests) all have first-class JSON support: call .json() and get back a dict. But in order for a Python project to be end-to-end type-safe, data crossing I/O boundaries must be validated, and if invalid, handled accordingly (raise an error) — a plain dict does neither. Closing that gap is exactly what lothc is designed for.

The original idea was to make lothc backend-agnostic: httpx, aiohttp, niquests, and pyreqwest all interchangeable underneath the same typed lothc interface, so switching backends never meant switching your call sites. However, in the author's opinion there's currently no compelling reason not to just use pyreqwest, so pyreqwest is the only backend implemented today, but, if there's demand for an httpx/aiohttp/niquests backend, the author is happy to consider adding one.

Fast

Benchmarked with perf.py against a tiny Rust-based static JSON server, 10,000 requests at concurrency 100 — including lothc's fully-typed decode targets (response_data_type= a msgspec Struct, a pydantic BaseModel, or a TypedDict validated via typeguard), not just raw bytes or an untyped dict. The object handed back from those runs isn't just parsed JSON — it's a real, constructed, field-validated instance of your own type, and that validation cost is included in the numbers, not benchmarked around. Decoding into a real msgspec Struct even edged out the unvalidated dict path in this run; typeguard's pure-Python validation was the one clear exception, costing a real, visible slowdown. Full numbers: docs/benchmarks.md.

Highlights

Pass response_data_type to any lothc call and get back a real, constructed, field-validated pydantic BaseModel, msgspec Struct, or typeguard-checked TypedDict, instead of the plain dict .json() leaves you to validate yourself. See Benchmarks for what that costs (usually nothing).

Development

See CLAUDE.md and style-guide.md for architecture notes and the (non-obvious in places) design conventions this codebase relies on.

task deps-sync    # install
task test         # run tests
task check        # lint + format-check + typecheck (what CI runs)