Metadata-Version: 2.4
Name: smart_session
Version: 1.2
Summary: Cache-aware session wrapper with disk caching modes and response validation
Author-email: dharmik.vadher@xbyte.io
Maintainer-email: dharmik.vadher@xbyte.io
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: loguru
Dynamic: license-file

# 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

```bash
pip install smart_session
```

Prebuilt wheels are intended for Windows x64 CPython 3.10+.

---

## 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
```

**smart_session - fetches once, reads from disk after:**

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

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

```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.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

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