smart-requests-dvxb 0.22

Universal caching wrapper for any sync HTTP session (curl_cffi, requests, cloudscraper, httpx)

smart_requests_dvxb

A lightweight wrapper around any sync HTTP session (requests, curl_cffi, cloudscraper, httpx, tls_client) that adds transparent disk caching with simple r / w / rr mode control and response condition validation.

---

Install

pip install smart_requests_dvxb

---

Standard vs Smart

Standard requests — fetches every time:

import requests

session = requests.Session()
resp = session.get("https://example.com/data.json")
print(resp.text)  # hits network every single run

SmartSession — fetches once, reads from disk after:

import requests
from smart_session import smart_session

sess = smart_session(requests.Session)
resp = sess.get(
    "https://example.com/data.json",
    mode="r",
    filepath="cache/data.json",
)
print(resp.text)  # network on first run, disk on every run after

Everything else (headers, cookies, params, data, json) works exactly as before.

---

Works with curl_cffi too

from curl_cffi import Session
from smart_session import smart_session

sess = smart_session(Session, impersonate="chrome124")
resp = sess.get(url, mode="r", filepath="cache/page.html")

---

Modes

Mode	Binary	Behaviour
r	rb	Cache-first — read from disk if cached, else fetch and cache
w	wb	Always live — fetch fresh every run, overwrite disk cache
rr	rrb	Read-only — offline replay; raises FileNotFoundError if no cache

Append b to any mode for binary responses (images, PDFs, etc.).

---

Condition Validation

Conditions are callables evaluated against the live response before writing to disk. If any condition fails, the file is never written and a ValueError is raised — so you never cache a bad response.

Without SmartSession — bad response silently saved:

resp = session.post(url, data=payload)
with open("result.html", "w") as f:
    f.write(resp.text)  # saves error page, captcha page, anything

With SmartSession — only valid responses are cached:

resp = sess.post(
    url,
    data=payload,
    mode="w",
    filepath="cache/result.html",
    conditions=[
        lambda r: r.status_code == 200,
        lambda r: len(r.content) > 500,
        lambda r: "error" not in r.text,
        lambda r: "captcha" not in r.text.lower(),
    ],
)

---

Full Parameter Reference

Parameter	Type	Description
mode	str	One of r, w, rr, rb, wb, rrb
filepath	str | Path	Path to cache file — required when mode is set
conditions	list[callable]	Validators run against the live response before writing

---

Debug Logging

sess = smart_session(Session, debug_mode=True)

Prints per-request cache hits/misses and write confirmations.

---

Built-in Docs

import smart_session
smart_session.info()   # module overview

sess = smart_session(Session)
sess.docs              # instance documentation
sess.supported         # available verbs + methods on wrapped session

---

Contact Developer

Dharmik Vadher — [e-mail]