smart-session 1.1

Cache-aware session wrapper with disk caching modes and response validation

smart_session

A lightweight wrapper for sync HTTP sessions that adds transparent disk caching with simple r / w / rr 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

smart_session - fetches once, reads from disk after:

import requests
from smart_session import session_wrapper

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

That is the only change. Everything else (headers, cookies, params, data, json) works the same as before.

---

Modes

Mode	Behavior
r	Return cache if it exists, otherwise fetch and store
w	Always fetch from network and overwrite the cache
rr	Read from cache only - raises error if file is missing
rb / wb / rrb	Same as above for binary responses (images, PDFs)

---

Condition Validation

Conditions are callables evaluated against the live response before writing to disk. If any condition fails, the file is not written and a ValueError is raised.

Without smart_session - bad response can be saved silently:

resp = session.post(url, data=payload)
with open("result.html", "w", encoding="utf-8") as f:
    f.write(resp.text)

With smart_session - 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.lower(),
        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	Cache file path. Required when mode is set
conditions	list[callable]	Response validators checked before writing to disk

---

Public API

from smart_session import session_wrapper, info

• session_wrapper is the main wrapper class export.
• info() prints module-level documentation.
• smart_session is still available as a compatibility alias.

---

Contact Developer

Dharmik Vadher
[e-mail]