Metadata-Version: 2.4
Name: smart_requests_dvxb
Version: 0.15
Summary: Cache-aware requests session with r/w/rw disk modes and condition validation
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

# SmartRequests

A lightweight wrapper around `requests.Session` that adds **transparent disk caching** with simple `r / w / rw` 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
```

**SmartRequests — fetches once, reads from disk after:**
```python
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:**
```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 SmartRequests — only valid responses are cached:**
```python
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** — dharmik.vadher@xbyte.io
