tiercache 0.1.0__tar.gz

tiercache-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Build / dist
+dist/
+build/
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / tools
+.claude/
+.idea/
+.vscode/
+
+# Cache data
+/tmp/smartcache/
+
+# Project specific
+media/
+notes.txt

tiercache-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: tiercache
+Version: 0.1.0
+Summary: RAM-first three-tier cache with swappable backends
+Project-URL: Homepage, https://github.com/madtunebk/tiercache
+Project-URL: Repository, https://github.com/madtunebk/tiercache
+Project-URL: Issues, https://github.com/madtunebk/tiercache/issues
+Author-email: Cornea Valentin <valicornea84@gmail.com>
+License: MIT
+Keywords: async,cache,django,fastapi,flask,memcached,ram,tiered-cache
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: msgpack>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: aioboto3>=12.0; extra == 'all'
+Requires-Dist: aiomcache>=0.8; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: motor>=3.0; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Provides-Extra: memcached
+Requires-Dist: aiomcache>=0.8; extra == 'memcached'
+Provides-Extra: mongodb
+Requires-Dist: motor>=3.0; extra == 'mongodb'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: s3
+Requires-Dist: aioboto3>=12.0; extra == 's3'

tiercache-0.1.0/README.md

@@ -0,0 +1,298 @@
+# SmartCache
+
+RAM-first three-tier cache for Python. Designed to keep your SSD/HDD out of the hot path.
+
+```
+pip install smartcache
+```
+
+---
+
+## How it works
+
+Every request walks down the tier chain until a hit is found:
+
+```
+GET request
+  │
+  ├─ Hot cache  (RAM, 2GB, 4h TTL)   ──── HIT → serve, reset TTL
+  │                                   MISS ↓
+  ├─ Cold cache (RAM, 10GB, 24h TTL) ──── HIT → promote to hot → serve
+  │                                   MISS ↓
+  └─ Dry cache  (Disk / S3 / MongoDB) ─── HIT → promote to hot → serve
+                                      MISS → return None (fetch from origin)
+
+SET request
+  └─ Writes to hot only (zero disk I/O)
+       │
+       └─ When hot evicts or expires → auto-demote to dry (failsafe, background)
+```
+
+Both hot and cold live entirely in RAM. Dry is only hit on a true cache miss.
+After a server restart, the first GET recovers each item from dry back into hot.
+
+---
+
+## Installation
+
+```bash
+# Base (RAM + local filesystem + SQLite tracking)
+pip install smartcache
+
+# With Memcached backends (multi-process / multi-server)
+pip install "smartcache[memcached]"
+
+# With Redis tracking
+pip install "smartcache[redis]"
+
+# With S3 dry cache
+pip install "smartcache[s3]"
+
+# With MongoDB
+pip install "smartcache[mongodb]"
+
+# With PostgreSQL tracking
+pip install "smartcache[postgres]"
+
+# Everything
+pip install "smartcache[all]"
+```
+
+---
+
+## Quick start
+
+### From a config file
+
+```python
+from smartcache import CacheManager
+
+cache = CacheManager.from_config("smartcache.yaml")
+
+# Async (FastAPI, aiohttp, Sanic)
+value = await cache.get("my-key")
+await cache.set("my-key", data)
+
+# Sync (Flask, Django)
+value = cache.get_sync("my-key")
+cache.set_sync("my-key", data)
+```
+
+### In code
+
+```python
+from smartcache import CacheManager
+from smartcache.backends.ram import RamBackend
+from smartcache.backends.dry.local import LocalBackend
+from smartcache.tracking.sqlite import SQLiteTracking
+
+cache = CacheManager(
+    hot=RamBackend(ttl_seconds=14400, max_size_bytes=2 * 1024**3),
+    cold=RamBackend(ttl_seconds=86400, max_size_bytes=10 * 1024**3),
+    dry=LocalBackend(base_path="/var/cache/myapp/dry", max_size_bytes=100 * 1024**3),
+    tracking=SQLiteTracking(path="/var/cache/myapp/index.db"),
+)
+```
+
+---
+
+## Configuration
+
+```yaml
+# smartcache.yaml
+
+hot_cache:
+  backend: ram          # ram | memcached
+  ttl_hours: 4
+  max_size_gb: 2
+
+cold_cache:
+  backend: ram          # ram | memcached
+  ttl_hours: 24
+  max_size_gb: 10
+
+dry_cache:
+  backend: local        # local | s3 | mongodb
+  max_size_gb: 100
+  path: /var/cache/myapp/dry
+
+tracking:
+  backend: sqlite       # sqlite | redis | postgres | mongodb
+
+# Optional: TTL rules by tag
+ttl_rules:
+  - tag: { type: thumbnail }
+    hot_ttl_hours: 1
+    cold_ttl_hours: 6
+  - tag: { type: raw }
+    hot_ttl_hours: 8
+    cold_ttl_hours: 48
+```
+
+### Memcached (multi-process / multi-server)
+
+```yaml
+hot_cache:
+  backend: memcached
+  ttl_hours: 4
+  max_size_gb: 2
+
+cold_cache:
+  backend: memcached
+  ttl_hours: 24
+  max_size_gb: 10
+
+memcached:
+  host: localhost
+  port: 11211
+```
+
+### S3 dry cache
+
+```yaml
+dry_cache:
+  backend: s3
+
+s3:
+  endpoint_url: https://s3.amazonaws.com   # or MinIO, Cloudflare R2, etc.
+  bucket: my-cache-bucket
+  access_key: ...
+  secret_key: ...
+```
+
+### MongoDB dry cache + tracking
+
+```yaml
+dry_cache:
+  backend: mongodb
+
+tracking:
+  backend: mongodb
+
+mongodb:
+  uri: mongodb://localhost:27017
+  database: smartcache
+```
+
+### Redis tracking
+
+```yaml
+tracking:
+  backend: redis
+
+redis:
+  host: localhost
+  port: 6379
+  db: 0
+```
+
+---
+
+## API
+
+```python
+# Fetch a value (returns None on miss)
+value = await cache.get("key")
+
+# Store a value using tier default TTL
+await cache.set("key", data)
+
+# Override TTL for this key only
+await cache.set("key", data, ttl_hours=2)
+
+# Tag-based TTL (matched against ttl_rules in config)
+await cache.set("key", data, tags={"type": "thumbnail"})
+
+# Delete from all tiers
+await cache.delete("key")
+
+# Flush a specific tier or all
+await cache.flush(tier="hot")   # hot | cold | dry | all
+
+# Hit/miss stats + tier sizes
+stats = await cache.stats()
+# {
+#   "hot_hits": 120, "cold_hits": 30, "dry_hits": 5, "misses": 2,
+#   "hot_size_bytes": 1048576, "cold_size_bytes": 0, "dry_size_bytes": 4096
+# }
+
+# Sync equivalents (Flask, Django)
+cache.get_sync("key")
+cache.set_sync("key", data, ttl_hours=2, tags={"type": "thumbnail"})
+cache.delete_sync("key")
+cache.flush_sync(tier="hot")
+cache.stats_sync()
+
+# Always close on shutdown
+await cache.close()
+```
+
+### TTL priority (highest wins)
+
+| Priority | Example |
+|---|---|
+| 1. Per-key override | `cache.set("k", v, ttl_hours=1)` |
+| 2. Tag rule | `cache.set("k", v, tags={"type": "thumbnail"})` → matched in config |
+| 3. Tier default | `hot_cache.ttl_hours` in yaml |
+| 4. Global default | hot: 4h, cold: 24h, dry: no expiry |
+
+---
+
+## Backends
+
+| Tier | Backend | Notes |
+|---|---|---|
+| Hot / Cold | `ram` | In-process, single server |
+| Hot / Cold | `memcached` | Shared pool, multi-process/server |
+| Dry | `local` | Local filesystem, SSD/HDD |
+| Dry | `s3` | AWS S3, MinIO, Cloudflare R2 |
+| Dry | `mongodb` | GridFS + native TTL indexes |
+| Tracking | `sqlite` | Zero deps, single machine |
+| Tracking | `redis` | In-memory, fast, recommended |
+| Tracking | `postgres` | Production relational |
+| Tracking | `mongodb` | Flexible schema, TTL indexes |
+
+---
+
+## Example HTTP app (FastAPI)
+
+```bash
+pip install fastapi uvicorn
+
+# Single process (RAM)
+uvicorn example.app:app --port 8989
+
+# Multi-process (Memcached — shared cache across all workers)
+SMARTCACHE_CONFIG=example/config_memcached.yaml \
+uvicorn example.app:app --workers 4 --port 8989
+```
+
+```bash
+# Store an image
+curl -X PUT "http://localhost:8989/cache/photo.png?tag_type=thumbnail" \
+    -H "Content-Type: image/png" \
+    --data-binary @photo.png
+
+# Fetch it (opens directly in browser)
+curl "http://localhost:8989/cache/photo.png" -o out.png
+
+# Stats
+curl "http://localhost:8989/stats"
+```
+
+---
+
+## Why not just use Redis for everything?
+
+Redis is great but it is a network service — every cache hit is a round trip.
+SmartCache's RAM backend (`ram`) stores values directly in the Python process
+memory, making hot-path lookups **microsecond-range** with zero network overhead.
+
+Use `memcached` when you need shared cache across multiple processes or servers.
+Use `redis` for tracking metadata (tiny footprint, fast, persistent).
+
+---
+
+## License
+
+MIT

tiercache-0.1.0/design.txt

@@ -0,0 +1,289 @@
+SmartCache — Design Document
+============================
+
+
+CORE PHILOSOPHY
+---------------
+RAM-first. Hit disk as rarely as possible.
+
+Hot and cold tiers live entirely in memory — no SSD, no HDD.
+Dry is the only disk tier and should be a last resort.
+The goal is to serve 95%+ of requests from RAM.
+
+
+OVERVIEW
+--------
+A Python pip package implementing a three-tier hierarchical cache with
+swappable backends per tier. Designed to be dropped into any project.
+
+    pip install smartcache
+    pip install smartcache[memcached]
+    pip install smartcache[s3]
+    pip install smartcache[mongodb]
+    pip install smartcache[postgres]
+    pip install smartcache[all]
+
+
+TIERS
+-----
+
+Hot Cache
+  Purpose   : Fastest access, short-lived. Serves the majority of hits.
+  Storage   : RAM only
+  TTL       : 4 hours (configurable)
+  Default   : RAM (in-process)
+  Options   : RAM, Memcached
+  Max size  : 2 GB (configurable)
+
+Cold Cache
+  Purpose   : Larger RAM pool, longer-lived. Fallback when hot misses.
+  Storage   : RAM only
+  TTL       : 24 hours (configurable)
+  Default   : RAM (in-process)
+  Options   : RAM, Memcached
+  Max size  : 10 GB (configurable)
+
+Dry Cache
+  Purpose   : Disk-based last resort. Only hit when both RAM tiers miss.
+  Storage   : Disk / object storage
+  TTL       : None by default (configurable)
+  Default   : Local filesystem
+  Options   : Local filesystem, S3-compatible, MongoDB (GridFS)
+  Max size  : 100 GB (configurable)
+
+Note:
+  Hot and cold use the same backend options. The difference is size and TTL.
+  Hot = small + short-lived (most frequent hits).
+  Cold = larger + longer-lived (warm data that didn't fit or expired from hot).
+
+
+TTL PRIORITY (highest wins)
+--------------------------
+TTLs are resolved in this order:
+
+  1. Per-key override  →  cache.set("key", data, ttl_hours=1)
+  2. Per-call tag      →  cache.set("key", data, tags={"type": "thumbnail"})
+                          matched against tag rules in config
+  3. Tier default      →  hot_cache.ttl_hours in smartcache.yaml
+  4. Global default    →  hot: 4h, cold: 24h, dry: no expiry
+
+This means the user can:
+  - Set a global default in the config file
+  - Override per tag/category (e.g. thumbnails expire faster than raw files)
+  - Override per individual key at set time
+
+
+LOOKUP BEHAVIOR
+---------------
+On every cache.get(key):
+
+  1. Check hot cache  (RAM)
+       HIT  → serve it, reset TTL, return value
+       MISS → continue
+
+  2. Check cold cache  (RAM)
+       HIT  → promote to hot cache, return value
+       MISS → continue
+
+  3. Check dry cache  (Disk — last resort)
+       HIT  → promote to hot cache, return value
+       MISS → return None (caller handles origin fetch)
+
+On cache.set(key, value, ttl_hours=None, tags=None):
+  - Writes to hot cache only
+  - ttl_hours overrides the tier default for this key only
+  - Dry cache is populated automatically on eviction (failsafe), not on write
+  - On hot/cold LRU evict or TTL expiry → value is demoted to dry
+  - On server restart all RAM is lost, but dry still holds everything
+
+
+TRACKING / METADATA
+-------------------
+Keeps a record of all cached keys, timestamps, hit counts, tier location.
+Should be fast — lives in memory where possible.
+
+  Default  : Redis (in-memory, fast key lookups, tiny metadata footprint)
+  Options  : Redis, SQLite, PostgreSQL, MongoDB
+
+Used for:
+  - Knowing which tier holds a key without probing all three
+  - Hit/miss statistics
+  - Manual inspection and cache management
+
+Why Redis as default for tracking:
+  Metadata per key is tiny (timestamps, tier, hit count). Redis holds this
+  entirely in memory with near-zero overhead. No disk I/O for lookups,
+  which fits the RAM-first philosophy.
+
+
+BACKENDS (per tier)
+-------------------
+
+Hot / Cold  (RAM only)
+  ram        — Python dict with TTL and LRU eviction, single process
+  memcached  — Distributed in-memory, great for multi-process or multi-server
+
+Dry  (Disk — last resort)
+  local    — Files on SSD/HDD, size-based cleanup
+  s3       — S3-compatible object storage (AWS S3, MinIO, Cloudflare R2)
+  mongodb  — GridFS for large binary/blob storage, flexible metadata
+
+Tracking
+  redis     — Default. In-memory, fast, fits RAM-first philosophy
+  sqlite    — Zero-dependency fallback, single .db file on disk
+  postgres  — Production relational option, strong querying
+  mongodb   — Native TTL indexes, flexible schema, good if already used for dry
+
+Note on MongoDB (dry + tracking):
+  - TTL indexes: MongoDB handles key expiry automatically, no cron needed
+  - GridFS: native large file storage split into chunks
+  - A single MongoDB instance can serve as dry backend AND tracking store
+
+
+CONFIGURATION
+-------------
+Configured via a YAML file or passed as a dict in code.
+
+Example smartcache.yaml:
+
+    hot_cache:
+      backend: ram          # ram | memcached
+      ttl_hours: 4          # default TTL — overridable per key or per tag
+      max_size_gb: 2
+
+    cold_cache:
+      backend: ram          # ram | memcached
+      ttl_hours: 24         # default TTL — overridable per key or per tag
+      max_size_gb: 10
+
+    dry_cache:
+      backend: local        # local | s3 | mongodb
+      ttl_hours: null       # null = no expiry (default)
+      max_size_gb: 100
+      path: /var/cache/smartcache/dry
+
+    tracking:
+      backend: redis        # redis | sqlite | postgres | mongodb
+
+    # Optional: TTL rules by tag
+    # Applied when cache.set() is called with a matching tag
+    ttl_rules:
+      - tag: { type: thumbnail }
+        hot_ttl_hours: 1
+        cold_ttl_hours: 12
+      - tag: { type: raw }
+        hot_ttl_hours: 8
+        cold_ttl_hours: 48
+        dry_ttl_hours: 720   # 30 days
+
+    redis:                  # only needed if tracking backend is redis
+      host: localhost
+      port: 6379
+      db: 0
+
+    memcached:              # only needed if hot/cold backend is memcached
+      host: localhost
+      port: 11211
+
+    s3:                     # only needed if dry backend is s3
+      endpoint_url: ...
+      bucket: smartcache
+      access_key: ...
+      secret_key: ...
+
+    mongodb:                # only needed if dry or tracking uses mongodb
+      uri: mongodb://localhost:27017
+      database: smartcache
+
+
+PUBLIC API
+----------
+
+    from smartcache import CacheManager
+
+    # Load from config file
+    cache = CacheManager.from_config("smartcache.yaml")
+
+    # Or configure in code
+    cache = CacheManager(
+        hot=RamBackend(ttl_hours=4, max_size_gb=2),
+        cold=RamBackend(ttl_hours=24, max_size_gb=10),
+        dry=S3Backend(bucket="my-bucket"),
+        tracking=RedisTracking(host="localhost", port=6379),
+    )
+
+    # Basic usage
+    value = await cache.get("my-key")
+
+    # Use tier default TTL
+    await cache.set("my-key", data)
+
+    # Override TTL for this key only
+    await cache.set("my-key", data, ttl_hours=2)
+
+    # Tag-based TTL (matches ttl_rules in config)
+    await cache.set("my-key", data, tags={"type": "thumbnail"})
+
+    # No expiry for this key
+    await cache.set("my-key", data, ttl_hours=None)
+
+    await cache.delete("my-key")
+    await cache.flush(tier="hot")   # clear a specific tier
+
+    # Stats
+    stats = await cache.stats()
+    # { "hot_hits": 120, "cold_hits": 30, "dry_hits": 5, "misses": 2 }
+
+
+PROJECT STRUCTURE
+-----------------
+
+    smartcache/
+    ├── pyproject.toml
+    ├── src/
+    │   └── smartcache/
+    │       ├── __init__.py             ← public API surface
+    │       ├── manager.py              ← CacheManager, lookup chain logic
+    │       ├── config.py               ← YAML loading, validation
+    │       ├── backends/
+    │       │   ├── base.py             ← AbstractBackend interface
+    │       │   ├── ram.py              ← shared by hot and cold
+    │       │   ├── memcached.py        ← shared by hot and cold
+    │       │   └── dry/
+    │       │       ├── local.py
+    │       │       ├── s3.py
+    │       │       └── mongodb.py      ← GridFS + TTL indexes
+    │       └── tracking/
+    │           ├── base.py             ← AbstractTracking interface
+    │           ├── redis.py            ← default
+    │           ├── sqlite.py
+    │           ├── postgres.py
+    │           └── mongodb.py
+    └── tests/
+        ├── test_manager.py
+        ├── test_backends/
+        └── test_tracking/
+
+Note: hot and cold share the same backend implementations (ram.py, memcached.py)
+— they are just two instances with different size and TTL config.
+
+
+OPTIONAL DEPENDENCIES (extras)
+-------------------------------
+
+    pip install smartcache               → base only (RAM + local + Redis tracking)
+    pip install smartcache[memcached]    → adds Memcached hot/cold backends
+    pip install smartcache[s3]           → adds S3 dry backend
+    pip install smartcache[mongodb]      → adds MongoDB dry backend + tracking
+    pip install smartcache[postgres]     → adds PostgreSQL tracking
+    pip install smartcache[all]          → everything
+
+
+PACKAGING STANDARDS
+-------------------
+- pyproject.toml  (PEP 517/518, modern standard — no setup.py)
+- src/ layout     (prevents accidental imports during development)
+- Semantic versioning  (1.0.0)
+- Type hints on all public methods  (PEP 484)
+- Async-first API  (asyncio, with optional sync wrappers)
+- Lazy imports for optional backends  (clear error if dep not installed)