lightreq documentation

pipeline test coverage python version license version

lightreq is a lightweight, extensible and composable HTTP client for Python built around the chain-of-responsibility pattern. It provides a simple unified interface over different HTTP backend adapters (like urllib and requests) and features a middleware layer architecture to easily inject logic before or after making HTTP requests.

Features

  • Unified Interface: Use the same clean API regardless of the underlying HTTP engine.

  • Adapters: Comes with built-in adapters for urllib (no external dependencies) and requests (with connection pooling).

  • Middleware Architecture: Easily compose behaviors like retries and logging during your HTTP requests.

  • Built-in Middlewares: Includes out-of-the-box logging and retry middlewares.

  • Helpful Response Object: Unified Response object provides easy access to status codes, headers, plain text, and JSON body.

Installation

To install lightreq, use pip:

pip install lightreq

The built-in urllib adapter works without any external dependencies. If you want to use the requests adapter (highly recommended for production due to connection pooling), install it separately:

pip install requests

Quick Start

from src.client import HttpClient
from src.middleware import logging, retry

# init client using the 'requests' adapter and applying basic middlewares
client = HttpClient(
    adapter="requests",
    middleware=[logging(), retry(retries=3)]
)

# perform a GET request
response = client.get(url="https://jsonplaceholder.typicode.com/todos/1")

# extract HTTP properties from the unified Response object
print(response.is_ok())       # True
print(response.status_code)   # 200
print(response.json())        # {'userId': 1, 'id': 1, 'title': 'delectus aut autem', ...}
print(response.elapsed)       # 0.123 (time taken in seconds)
print(response.body)          # b'{\n  "userId": 1, ...}' (raw bytes)

# close active adapter connections
client.close()

Background

lightreq was built as an educational exercise for understanding how HTTP clients work from scratch, with zero external dependencies. Along the way it evolved into an extensible architecture that can integrate with libraries like requests. It is primarily intended for learning purposes.