smart-session 0.32

Cache-aware requests session with r/w/rw disk modes and condition validation

SmartRequests

A lightweight wrapper around requests.Session that adds transparent disk caching with simple r / w / rw mode control and response condition validation.

---

Install

pip install smart_session

---

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

SmartRequests — fetches once, reads from disk after:

import requests
from SmartRequests import smart_session

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

That's the only change. Everything else (headers, cookies, params, data, json) works exactly as before.

---

Modes

Mode	Behavior
r	Read from cache only — raises error if file missing
w	Always fetch from network, write result to disk
rw	Return cache if exists, otherwise fetch and store
rb / wb / rwb	Same as above but read/write raw bytes (images, PDFs)

---

Condition Validation

Conditions are lambdas evaluated against the 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 SmartRequests — 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 SmartRequests — only valid responses are cached:

resp = session.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, rw, rb, wb, rwb
filepath	str	Absolute path to cache file — required when mode is set
conditions	list[callable]	Lambdas evaluated against response before writing — raises ValueError on first failure

---

Contact Developer

Dharmik Vadher — [e-mail]