Metadata-Version: 2.4
Name: smart_requests_dvxb
Version: 0.22
Summary: Universal caching wrapper for any sync HTTP session (curl_cffi, requests, cloudscraper, httpx)
Author-email: dharmik.vadher@xbyte.io
Maintainer-email: dharmik.vadher@xbyte.io
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: loguru

# 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

```bash
pip install smart_requests_dvxb
```

---

## Standard vs Smart

**Standard requests — fetches every time:**
```python
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:**
```python
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

```python
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:**
```python
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:**
```python
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

```python
sess = smart_session(Session, debug_mode=True)
```

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

---

## Built-in Docs

```python
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** — dharmik.vadher@xbyte.io
