lexigram-http

Outbound HTTP client for the Lexigram Framework.

Overview

Async outbound HTTP client for the Lexigram Framework. Provides a first-class async HTTP client backed by aiohttp, with connection pooling, typed request/ response contexts, interceptor chains, base URL clients, streaming support, and DI integration.

This package focuses on making outbound HTTP requests — for inbound web servers, use lexigram-web. Resilience patterns (retry, circuit breaker) are layered in through lexigram-resilience, not built in by default.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-http

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.http import HTTPModule, HTTPClientConfig

@module(imports=[HTTPModule.configure(HTTPClientConfig())])
class AppModule(Module):
    pass

async def main():
    async with Application.boot(modules=[AppModule]) as app:
        from lexigram.http import HTTPClient
        async with HTTPClient.session_context() as client:
            response = await client.get("https://api.example.com/users/123")
            if response.ok:
                user = await response.json()
                print(user)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configuration

Zero-config usage: Call HTTPModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
http:
  pool:
    max_connections: 100
    max_keepalive_connections: 50
    timeout: 30.0
  trust_env: true
  cookie_jar: true

Option 2 — Profiles + Environment Variables (recommended)

export LEX_HTTP__POOL__MAX_CONNECTIONS=100
export LEX_HTTP__POOL__TIMEOUT=30.0
export LEX_HTTP__TRUST_ENV=true

Option 3 — Python

from lexigram.http import HTTPModule, HTTPClientConfig, ConnectionPoolConfig

HTTPModule.configure(
    HTTPClientConfig(
        pool=ConnectionPoolConfig(
            max_connections=100,
            timeout=30.0,
        ),
        trust_env=True,
        cookie_jar=True,
    )
)

Config reference

Module Factory Methods

Key Features

• Connection pooling — per-host limits, keepalive, DNS caching via aiohttp
• Proxy support — HTTP/HTTPS with environment variable auto-detection
• Cookie jar — optional, per-session in-memory cookie persistence
• Streaming — StreamContext for large file downloads
• Interceptor chains — composable auth, logging, metrics hooks
• Type-safe contexts — RequestContext and ResponseContext typed models

Testing

from lexigram.contracts.web import HTTPClientProtocol
from lexigram.http.types import ResponseContext

class FakeHTTPClient(HTTPClientProtocol):
    async def get(self, url: str, **kwargs) -> ResponseContext:
        return ResponseContext(status=200, headers={}, body=b'{"id": 123}')

# Inject into service under test
service = UserService(http_client=FakeHTTPClient())

Key Source Files