shadowcache 0.1.0__py3-none-any.whl

shadowcache/__init__.py

@@ -0,0 +1,31 @@
+"""ShadowCache -- Transparent Redis caching for raw SQL connections.
+
+Usage:
+    import mysql.connector
+    from shadowcache import ShadowCache
+
+    conn = mysql.connector.connect(host="localhost", database="mydb")
+    cache = ShadowCache(conn)
+
+    # SELECTs are transparently cached
+    cursor, rows = cache.execute("SELECT * FROM users WHERE id = %s", (42,))
+
+    # INSERT/UPDATE/DELETE automatically evict related cache entries
+    cache.execute("UPDATE users SET name = %s WHERE id = %s", ("Alice", 42))
+"""
+
+from shadowcache.exceptions import ShadowCacheError
+
+__all__ = ["ShadowCache", "ShadowCacheError"]
+__version__ = "0.1.0"
+
+
+def __getattr__(name):
+    """Lazily import ShadowCache so the package is usable even when
+    only a subset of modules have been installed."""
+    if name == "ShadowCache":
+        from shadowcache.core import ShadowCache as _sc
+
+        return _sc
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+

shadowcache/core.py

@@ -0,0 +1,360 @@
+"""Core ShadowCache class -- transparent Redis caching for raw SQL connections."""
+
+import datetime
+import hashlib
+import json
+from decimal import Decimal
+from typing import Any, Dict, List, Optional, Tuple
+
+import redis
+
+from shadowcache.exceptions import CacheBackendError
+from shadowcache.logger import get_logger
+from shadowcache.parser import extract_tables, extract_write_type, is_select_query
+
+_log = get_logger(__name__)
+
+_DEFAULT_KEY_PREFIX = "shadowcache"
+
+# Sentinel keys for type-tagged JSON serialization.
+# Each non-native value is encoded as a 3-element list:
+#   ["__sc__", "<type_name>", "<payload>"]
+# A list is used because it is far less likely to appear as a real column
+# value than a dict with particular keys.
+_SC_SENTINEL = "__sc__"
+
+
+def _param_repr(value: Any) -> str:
+    """Produce a type-aware string representation of a parameter value.
+
+    Prefixes the value with its Python type name so that ``1`` (int) and
+    ``"1"`` (str) produce different cache keys.
+    """
+    return f"{type(value).__name__}:{value}"
+
+
+def _build_cache_key(prefix: str, sql: str, params: Optional[tuple]) -> str:
+    """Produce a deterministic cache key from a SQL string and its parameters."""
+    raw = sql
+    if params:
+        raw += "|" + "|".join(_param_repr(p) for p in params)
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return f"{prefix}:{digest}"
+
+
+def _serialize(rows: List[Dict[str, Any]]) -> str:
+    """JSON-serialise rows, handling non-native types via sentinel lists.
+
+    Supported types: bytes, datetime, date, time, timedelta, Decimal.
+    Each is encoded as ``["__sc__", "<type>", "<payload>"]``.
+    """
+
+    def _default(obj: Any) -> Any:
+        if isinstance(obj, bytes):
+            return [_SC_SENTINEL, "bytes", obj.hex()]
+        if isinstance(obj, datetime.datetime):
+            return [_SC_SENTINEL, "datetime", obj.isoformat()]
+        if isinstance(obj, datetime.date):
+            return [_SC_SENTINEL, "date", obj.isoformat()]
+        if isinstance(obj, datetime.time):
+            return [_SC_SENTINEL, "time", obj.isoformat()]
+        if isinstance(obj, datetime.timedelta):
+            return [_SC_SENTINEL, "timedelta", obj.total_seconds()]
+        if isinstance(obj, Decimal):
+            return [_SC_SENTINEL, "Decimal", str(obj)]
+        raise TypeError(f"Unsupported type: {type(obj)}")
+
+    return json.dumps(rows, default=_default)
+
+
+def _deserialize(payload: str) -> List[Dict[str, Any]]:
+    """Deserialise rows, restoring non-native types from sentinel lists.
+
+    Recursively walks the decoded JSON tree.  Any three-element list whose
+    first element is ``_SC_SENTINEL`` is converted back to its native type;
+    all other values pass through unchanged.
+    """
+
+    def _walk(obj: Any) -> Any:
+        if isinstance(obj, list):
+            if len(obj) == 3 and obj and obj[0] == _SC_SENTINEL:
+                _, t, d = obj
+                if t == "bytes":
+                    return bytes.fromhex(d)
+                if t == "datetime":
+                    return datetime.datetime.fromisoformat(d)
+                if t == "date":
+                    return datetime.date.fromisoformat(d)
+                if t == "time":
+                    return datetime.time.fromisoformat(d)
+                if t == "timedelta":
+                    return datetime.timedelta(seconds=d)
+                if t == "Decimal":
+                    return Decimal(d)
+            return [_walk(item) for item in obj]
+        if isinstance(obj, dict):
+            return {k: _walk(v) for k, v in obj.items()}
+        return obj
+
+    return _walk(json.loads(payload))
+
+
+class ShadowCache:
+    """Transparent Redis cache layer for a DB-API2 MySQL connection.
+
+    Parameters
+    ----------
+    db_connection:
+        An open DB-API2 connection (e.g. from ``mysql.connector.connect``).
+    redis_client:
+        An optional pre-configured ``redis.Redis`` instance.  If omitted a
+        client bound to ``redis_host``/``redis_port`` is created.
+    redis_host:
+        Hostname for Redis (ignored when *redis_client* is supplied).
+    redis_port:
+        Port for Redis (ignored when *redis_client* is supplied).
+    ttl:
+        Time-to-live in seconds for cached SELECT results.  Default 300.
+    auto_invalidate:
+        When ``True`` (the default), INSERT/UPDATE/DELETE statements
+        automatically evict cached SELECT results that reference the same
+        table.
+    key_prefix:
+        Namespace prefix for all Redis keys.  Change this to share a Redis
+        instance across multiple applications.
+    """
+
+    def __init__(
+        self,
+        db_connection,
+        redis_client: Optional[redis.Redis] = None,
+        *,
+        redis_host: str = "localhost",
+        redis_port: int = 6379,
+        ttl: int = 300,
+        auto_invalidate: bool = True,
+        key_prefix: str = _DEFAULT_KEY_PREFIX,
+    ):
+        self._db = db_connection
+        self._ttl = ttl
+        self._auto_invalidate = auto_invalidate
+        self._key_prefix = key_prefix
+        self._index_prefix = f"{key_prefix}:index"
+
+        self._hits = 0
+        self._misses = 0
+
+        if redis_client is not None:
+            self._redis = redis_client
+        else:
+            try:
+                self._redis = redis.Redis(
+                    host=redis_host,
+                    port=redis_port,
+                    decode_responses=True,
+                )
+                self._redis.ping()
+            except Exception as exc:
+                raise CacheBackendError(
+                    f"Could not connect to Redis at {redis_host}:{redis_port}"
+                ) from exc
+
+    # ---------------------------------------------------------------- public API
+
+    def execute(
+        self,
+        sql: str,
+        params: Optional[tuple] = None,
+    ) -> Tuple[Any, Optional[List[Dict[str, Any]]]]:
+        """Execute *sql* with optional *params*, applying caching automatically.
+
+        Returns ``(cursor, rows)``.
+
+        *For SELECT statements* the cache is consulted first.  On a hit
+        ``cursor`` is ``None`` and *rows* contains the cached result.  On a
+        miss the query runs against MySQL, the result is stored in Redis,
+        and both the live cursor and rows are returned.
+
+        *For INSERT/UPDATE/DELETE* the statement runs against MySQL and any
+        cached SELECT results that reference the affected tables are
+        evicted.  ``rows`` is ``None``; the caller inspects ``cursor`` for
+        ``.lastrowid`` or ``.rowcount``.
+
+        *For all other statements* (DDL, administrative commands) the
+        statement is forwarded to MySQL unchanged.
+        """
+        if not sql or not sql.strip():
+            return None, None
+
+        sql = sql.strip()
+
+        if is_select_query(sql):
+            return self._handle_select(sql, params)
+
+        write_type = extract_write_type(sql)
+        if write_type is not None:
+            return self._handle_write(sql, params, write_type)
+
+        return self._handle_other(sql, params)
+
+    def invalidate_table(self, table_name: str) -> int:
+        """Evict all cached entries associated with *table_name*.
+
+        Returns the number of keys removed.
+        """
+        index_key = f"{self._index_prefix}:{table_name}"
+        try:
+            members = self._redis.smembers(index_key)
+            if not members:
+                return 0
+            keys = list(members)
+            keys.append(index_key)
+            return self._redis.delete(*keys)
+        except redis.RedisError as exc:
+            _log.warning("Failed to invalidate table %r: %s", table_name, exc)
+            return 0
+
+    def flush_cache(self) -> int:
+        """Remove all ShadowCache keys from Redis.
+
+        Returns the number of keys removed.
+        """
+        pattern = f"{self._key_prefix}:*"
+        try:
+            keys = list(self._redis.scan_iter(match=pattern, count=100))
+            if not keys:
+                return 0
+            return self._redis.delete(*keys)
+        except redis.RedisError as exc:
+            _log.warning("Failed to flush cache: %s", exc)
+            return 0
+
+    def close(self) -> None:
+        """Close the wrapped database connection."""
+        try:
+            if hasattr(self._db, "close"):
+                self._db.close()
+        except Exception as exc:
+            _log.warning("Error closing database connection: %s", exc)
+
+    @property
+    def stats(self) -> Dict[str, Any]:
+        """Return a snapshot of cache performance counters."""
+        total = self._hits + self._misses
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "total_requests": total,
+            "hit_ratio": self._hits / total if total else 0.0,
+        }
+
+    # --------------------------------------------------------------- internals
+
+    def _handle_select(self, sql: str, params):
+        cache_key = _build_cache_key(self._key_prefix, sql, params)
+
+        # Try Redis first.
+        try:
+            cached = self._redis.get(cache_key)
+        except Exception as exc:
+            _log.warning("Redis read error, falling through to MySQL: %s", exc)
+            cached = None
+
+        if cached is not None:
+            try:
+                rows = _deserialize(cached)
+            except Exception as exc:
+                _log.warning(
+                    "Cache deserialisation failed for key %r, falling through to MySQL: %s",
+                    cache_key,
+                    exc,
+                )
+            else:
+                self._hits += 1
+                _log.info("Cache HIT for key %s", cache_key)
+                return None, rows
+
+        self._misses += 1
+        _log.info("Cache MISS for key %s -- fetching from MySQL", cache_key)
+
+        cursor, rows = self._handle_other(sql, params)
+        if rows is None:
+            return cursor, None
+
+        # Store in Redis and update per-table indexes.
+        tables = extract_tables(sql)
+        self._store_result(cache_key, rows, tables)
+        return cursor, rows
+
+    def _handle_write(self, sql: str, params, write_type: str):
+        cursor, _ = self._handle_other(sql, params)
+
+        if self._auto_invalidate:
+            tables = extract_tables(sql)
+            for table in tables:
+                self.invalidate_table(table)
+            _log.debug("%s executed, tables evicted: %s", write_type, tables)
+
+        return cursor, None
+
+    def _handle_other(self, sql: str, params):
+        """Execute SQL directly against MySQL, returning (cursor, rows).
+
+        Rows are normalised to ``list[dict]`` regardless of whether the
+        underlying driver returns tuples or dicts.  The conversion uses
+        ``cursor.description`` (standard DB-API2) so the wrapper works
+        with ``mysql-connector-python``, ``pymysql``, and other PEP 249
+        drivers.
+        """
+        try:
+            cursor = self._db.cursor()
+            if params:
+                cursor.execute(sql, params)
+            else:
+                cursor.execute(sql)
+        except Exception:
+            try:
+                cursor.close()
+            except Exception:
+                pass
+            raise
+
+        try:
+            raw_rows = cursor.fetchall()
+        except Exception:
+            raw_rows = None
+
+        if raw_rows and cursor.description:
+            first_row = raw_rows[0]
+            if isinstance(first_row, dict):
+                rows = raw_rows
+            else:
+                columns = [col[0] for col in cursor.description]
+                rows = [dict(zip(columns, row)) for row in raw_rows]
+        elif raw_rows is not None:
+            rows = []  # empty result set
+        else:
+            rows = None  # fetchall failed on a non-result-set statement
+
+        return cursor, rows
+
+    def _store_result(self, cache_key: str, rows, tables: set):
+        try:
+            payload = _serialize(rows)
+        except Exception as exc:
+            _log.warning("Failed to serialise result for key %r: %s", cache_key, exc)
+            return
+
+        try:
+            self._redis.set(cache_key, payload, ex=self._ttl)
+        except redis.RedisError as exc:
+            _log.warning("Failed to store cache key %r: %s", cache_key, exc)
+            return
+
+        for table in tables:
+            index_key = f"{self._index_prefix}:{table}"
+            try:
+                self._redis.sadd(index_key, cache_key)
+                self._redis.expire(index_key, self._ttl)
+            except redis.RedisError as exc:
+                _log.debug("Failed to update index for table %r: %s", table, exc)

shadowcache/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exceptions for ShadowCache."""
+
+
+class ShadowCacheError(Exception):
+    """Base exception for all ShadowCache errors."""
+
+
+class CacheParseError(ShadowCacheError):
+    """Raised when a SQL statement cannot be parsed by sqlglot.
+
+    The original SQL is still executed against MySQL; only the caching
+    or invalidation step is skipped.
+    """
+
+
+class CacheBackendError(ShadowCacheError):
+    """Raised when Redis or MySQL is unreachable."""

shadowcache/logger.py

@@ -0,0 +1,39 @@
+"""Logging setup for ShadowCache.
+
+Provides a get_logger() factory so consumers can obtain a configured
+logger without relying on a module-level singleton.
+"""
+
+import logging
+import os
+
+_log_format = logging.Formatter(
+    "%(asctime)s - %(levelname)s - %(name)s:%(lineno)d - %(message)s"
+)
+
+_loggers: dict[str, logging.Logger] = {}
+
+
+def get_logger(name: str = "ShadowCache") -> logging.Logger:
+    """Return a configured logger for the given name.
+
+    Log level is read from the LOG_LEVEL environment variable and defaults
+    to INFO.  A StreamHandler writing to stderr is attached on the first
+    call for each *name*.
+    """
+    if name in _loggers:
+        return _loggers[name]
+
+    level_name = os.getenv("LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    if not logger.handlers:
+        console = logging.StreamHandler()
+        console.setFormatter(_log_format)
+        logger.addHandler(console)
+
+    _loggers[name] = logger
+    return logger

shadowcache/parser.py

@@ -0,0 +1,86 @@
+"""SQL parsing utilities using sqlglot.
+
+Extracts table names and statement type information from raw SQL
+strings so the core module can decide whether to cache or invalidate.
+"""
+
+from typing import Optional, Set
+
+import sqlglot
+from sqlglot import exp
+
+from shadowcache.logger import get_logger
+
+_log = get_logger(__name__)
+
+_READ_TYPES = frozenset({
+    exp.Select,
+    exp.Describe,
+})
+
+
+def _get_root_expression(sql: str) -> Optional[exp.Expression]:
+    """Parse *sql* and return the root AST node, or None on failure."""
+    try:
+        return sqlglot.parse_one(sql, error_level=sqlglot.ErrorLevel.IGNORE)
+    except Exception:
+        _log.debug("sqlglot could not parse: %s", sql[:120])
+        return None
+
+
+def extract_tables(sql: str) -> Set[str]:
+    """Return the set of table names referenced in *sql*.
+
+    Handles SELECT, INSERT, UPDATE, DELETE, TRUNCATE, JOINs,
+    sub-queries, and schema-qualified names like ``shop.users``.
+
+    Returns an empty set if the SQL cannot be parsed, so callers can
+    safely fall back to TTL-based expiry.
+    """
+    root = _get_root_expression(sql)
+    if root is None:
+        return set()
+
+    tables: Set[str] = set()
+    for table_node in root.find_all(exp.Table):
+        name = table_node.name
+        if not name:
+            continue
+        if table_node.db:
+            tables.add(f"{table_node.db}.{name}")
+        else:
+            tables.add(name)
+    return tables
+
+
+def extract_write_type(sql: str) -> Optional[str]:
+    """Determine the write category of *sql*.
+
+    Returns
+    -------
+    ``"INSERT"``, ``"UPDATE"``, ``"DELETE"``, or ``None`` if the
+    statement does not modify data (SELECT, SHOW, DDL, etc.).
+    TRUNCATE is treated as a write (returns ``"DELETE"``).
+    """
+    root = _get_root_expression(sql)
+    if root is None:
+        return None
+
+    root_type = type(root)
+
+    if root_type is exp.Insert:
+        return "INSERT"
+    if root_type is exp.Update:
+        return "UPDATE"
+    if root_type in (exp.Delete, exp.TruncateTable):
+        return "DELETE"
+
+    return None
+
+
+def is_select_query(sql: str) -> bool:
+    """Return True if *sql* is a SELECT (or SELECT-like) statement."""
+    root = _get_root_expression(sql)
+    if root is None:
+        return False
+    return type(root) in _READ_TYPES

shadowcache-0.1.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: shadowcache
+Version: 0.1.0
+Summary: Transparent Redis caching for raw SQL connections - no ORM required
+Author: Pratham Bhosale
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pratham2402/ShadowCache
+Project-URL: Repository, https://github.com/pratham2402/ShadowCache
+Keywords: redis,mysql,cache,sql,caching,database,db-api,transparent-cache,query-cache
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redis>=4.0
+Requires-Dist: mysql-connector-python>=8.0
+Requires-Dist: sqlglot>=20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/static/v1?label=%F0%9F%8C%9F&message=If%20Useful&style=flat&color=BC4E99">
+  <img src="https://badges.frapsoft.com/os/v1/open-source.svg?v=103">
+  <a href="https://github.com/pratham2402"><img src="https://img.shields.io/badge/View-My_Profile-green?logo=GitHub"></a>
+  <a href="https://github.com/pratham2402?tab=repositories"><img src="https://img.shields.io/badge/View-My_Repositories-blue?logo=GitHub"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.8+-blue?logo=python">
+  <img src="https://img.shields.io/badge/license-MIT-green">
+  <img src="https://img.shields.io/badge/platform-mysql%20%7C%20redis-red">
+</p>
+
+# ShadowCache
+
+<p align="center">
+  <img src="./README%20Banner%20Art.png" alt="ShadowCache Banner">
+</p>
+
+> **Write SQL. Get caching. Nothing else.**
+
+ShadowCache wraps your MySQL connection and transparently caches SELECT results
+in Redis. INSERT, UPDATE, or DELETE statements automatically evict affected cache
+entries so your reads never serve stale data. No ORM. No boilerplate. No config.
+
+<br>
+
+<details open>
+<summary><b>Table of Contents</b></summary>
+
+- [The Problem](#the-problem)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Configuration](#configuration)
+- [Running Tests](#running-tests)
+- [License](#license)
+
+</details>
+
+## The Problem
+
+Every developer who writes raw SQL eventually writes this:
+
+```python
+# 8 lines of boilerplate for every cached query
+cache_key = f"user:{user_id}"
+cached = redis.get(cache_key)
+if cached:
+    return json.loads(cached)
+
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+row = cursor.fetchone()
+redis.set(cache_key, json.dumps(row), ex=300)
+return row
+```
+
+And on every INSERT, UPDATE, or DELETE you need to remember:
+
+```python
+cursor.execute("UPDATE users SET name = %s WHERE id = %s", (name, user_id))
+redis.delete(f"user:{user_id}")  # easy to forget, easy to get wrong
+```
+
+```diff
+- Boilerplate for every query
+- Manual invalidation you will forget
++ One line. Caching and invalidation are automatic.
+```
+
+**With ShadowCache:**
+
+```python
+cursor, rows = cache.execute("SELECT * FROM users WHERE id = %s", (42,))
+cursor, _ = cache.execute("UPDATE users SET name = %s WHERE id = %s", ("Alice", 42))
+```
+
+## Features
+
+| | |
+|---|---|
+| **Zero-schema caching** | Works with any MySQL table, any query. No model definitions needed. |
+| **Write-triggered eviction** | INSERT, UPDATE, and DELETE automatically evict cached SELECTs for the same table. |
+| **TTL safety net** | Cached entries expire after a configurable time-to-live. Eventual consistency guaranteed. |
+| **Graceful fallback** | If Redis is unreachable, queries still execute against MySQL. |
+
+## Installation
+
+```bash
+pip install shadowcache
+```
+
+> Or install from source:
+
+```bash
+git clone https://github.com/pratham2402/ShadowCache.git
+cd ShadowCache
+pip install -r requirements.txt
+```
+
+**Requires:** Python 3.8+, Redis, MySQL.
+
+## Quick Start
+
+```python
+import mysql.connector
+from shadowcache import ShadowCache
+
+conn = mysql.connector.connect(
+    host="localhost", database="my_app",
+    user="app_user", password="secret",
+)
+
+cache = ShadowCache(conn)
+
+# Cold miss -- hits MySQL, stores in Redis
+cursor, rows = cache.execute("SELECT * FROM users WHERE id = %s", (42,))
+
+# Warm hit -- returns from Redis instantly
+cursor, rows = cache.execute("SELECT * FROM users WHERE id = %s", (42,))
+
+# Write evicts the cache
+cache.execute("UPDATE users SET name = %s WHERE id = %s", ("Alice", 42))
+
+# Cache was evicted -- fresh data from MySQL
+cursor, rows = cache.execute("SELECT * FROM users WHERE id = %s", (42,))
+```
+
+## API Reference
+
+### `ShadowCache(db_connection, *, ...)`
+
+```python
+ShadowCache(
+    db_connection,
+    *,
+    redis_client=None,
+    redis_host="localhost",
+    redis_port=6379,
+    ttl=300,
+    auto_invalidate=True,
+    key_prefix="shadowcache",
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `db_connection` | *(required)* | An open DB-API2 MySQL connection |
+| `redis_client` | `None` | Pre-configured `redis.Redis` instance; created automatically if omitted |
+| `redis_host` | `"localhost"` | Redis hostname |
+| `redis_port` | `6379` | Redis port |
+| `ttl` | `300` | Cache TTL in seconds |
+| `auto_invalidate` | `True` | Whether writes automatically evict related cache entries |
+| `key_prefix` | `"shadowcache"` | Namespace prefix for all Redis keys |
+
+### `ShadowCache.execute(sql, params=None)`
+
+Returns `(cursor, rows)`.
+
+| SQL | Behaviour |
+|---|---|
+| `SELECT` | Checks Redis first. Hit returns `(None, cached_rows)`. Miss executes on MySQL, caches, returns `(cursor, rows)`. |
+| `INSERT` | Executes on MySQL. Returns `(cursor, None)`. See `cursor.lastrowid`. |
+| `UPDATE` / `DELETE` | Executes on MySQL, evicts cache for affected tables. Returns `(cursor, None)`. See `cursor.rowcount`. |
+| DDL / other | Executes on MySQL. No caching, no eviction. |
+
+### Other Methods
+
+| Method | Description |
+|---|---|
+| `invalidate_table(name)` | Evict all cached entries for a table. Returns count of keys removed. |
+| `flush_cache()` | Remove all ShadowCache keys from Redis. Returns count of keys removed. |
+| `stats` | Property. Returns a dict with keys `hits`, `misses`, `total_requests`, `hit_ratio`. |
+| `close()` | Close the wrapped database connection. |
+
+## Configuration
+
+Copy `.env.example` to `.env` and set your credentials:
+
+```
+REDIS_HOST=localhost
+REDIS_PORT=6379
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=your_db_user
+MYSQL_PASSWORD=your_db_password
+MYSQL_DATABASE=your_database
+LOG_LEVEL=INFO
+```
+
+## Running Tests
+
+```bash
+# Unit tests -- no Redis or MySQL needed, all mocks
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT

shadowcache-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+shadowcache/__init__.py,sha256=G1ed7W_7dmQmKFlR7YapxJqPV8aHPZAmoGHf_sECwPQ,963
+shadowcache/core.py,sha256=6VPhu1TsyXVfjWFdXQqjer4VVJv8AsLDdzX2rOhDnK8,12588
+shadowcache/exceptions.py,sha256=1C4cuypOUgIgzNcbKLwrllt6WER1MK7eKV-Eq-FkXZc,453
+shadowcache/logger.py,sha256=pUcwJpXHZCnYn49GFyBKpFFfH6vY99GxAo0eI7xgl9M,1061
+shadowcache/parser.py,sha256=Rgz5mu3KGb3IIq8Y-uNucdJ2V7GA5mjorVNz4REBQpw,2292
+shadowcache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shadowcache-0.1.0.dist-info/licenses/LICENSE,sha256=BsPow-BLXSrbXdSzG4LW7LvsH2oV5lIKAV1iulFjJyI,1072
+shadowcache-0.1.0.dist-info/METADATA,sha256=DfdAynQ8CON0_qLBylShJoHqOUJr7uoEQy8RDwIn5mU,6956
+shadowcache-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+shadowcache-0.1.0.dist-info/top_level.txt,sha256=FQmAUbmMq91kPaIW3DzZ9JsARkPmC3l4oesbRSozZQY,12
+shadowcache-0.1.0.dist-info/RECORD,,

shadowcache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shadowcache-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratham Bhosale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shadowcache-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shadowcache