.. lightreq documentation master file, created by
   sphinx-quickstart on Sat Apr 25 16:08:33 2026.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

lightreq documentation
======================

.. image:: https://gitlab.com/ryaneatfood/lightreq/badges/master/pipeline.svg
   :alt: pipeline

.. image:: https://gitlab.com/ryaneatfood/lightreq/badges/master/coverage.svg
   :alt: test coverage

.. image:: https://img.shields.io/pypi/pyversions/lightreq
   :alt: python version

.. image:: https://img.shields.io/pypi/l/lightreq
   :alt: 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
-----------

.. code-block:: python

   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.


.. toctree::
   :hidden:

   api
   client
   architecture
   middleware
   response