cachu 0.1.3__py3-none-any.whl → 0.2.1__py3-none-any.whl

cachu/backends/async_redis.py

@@ -0,0 +1,141 @@
+"""Async Redis cache backend implementation using redis.asyncio.
+"""
+import pickle
+import struct
+import time
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from . import NO_VALUE
+from .async_base import AsyncBackend
+
+if TYPE_CHECKING:
+    import redis.asyncio as aioredis
+
+
+_METADATA_FORMAT = 'd'
+_METADATA_SIZE = struct.calcsize(_METADATA_FORMAT)
+
+
+def _get_async_redis_module() -> Any:
+    """Import redis.asyncio module, raising helpful error if not installed.
+    """
+    try:
+        import redis.asyncio as aioredis
+        return aioredis
+    except ImportError as e:
+        raise RuntimeError(
+            "Async Redis support requires the 'redis' package (>=4.2.0). "
+            "Install with: pip install cachu[redis]"
+        ) from e
+
+
+async def get_async_redis_client(url: str) -> 'aioredis.Redis':
+    """Create an async Redis client from URL.
+
+    Args:
+        url: Redis URL (e.g., 'redis://localhost:6379/0')
+    """
+    aioredis = _get_async_redis_module()
+    return aioredis.from_url(url)
+
+
+class AsyncRedisBackend(AsyncBackend):
+    """Async Redis cache backend using redis.asyncio.
+    """
+
+    def __init__(self, url: str, distributed_lock: bool = False) -> None:
+        self._url = url
+        self._distributed_lock = distributed_lock
+        self._client: aioredis.Redis | None = None
+
+    async def _get_client(self) -> 'aioredis.Redis':
+        """Lazy-load async Redis client.
+        """
+        if self._client is None:
+            self._client = await get_async_redis_client(self._url)
+        return self._client
+
+    def _pack_value(self, value: Any, created_at: float) -> bytes:
+        """Pack value with creation timestamp.
+        """
+        metadata = struct.pack(_METADATA_FORMAT, created_at)
+        pickled = pickle.dumps(value)
+        return metadata + pickled
+
+    def _unpack_value(self, data: bytes) -> tuple[Any, float]:
+        """Unpack value and creation timestamp.
+        """
+        created_at = struct.unpack(_METADATA_FORMAT, data[:_METADATA_SIZE])[0]
+        value = pickle.loads(data[_METADATA_SIZE:])
+        return value, created_at
+
+    async def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found.
+        """
+        client = await self._get_client()
+        data = await client.get(key)
+        if data is None:
+            return NO_VALUE
+        value, _ = self._unpack_value(data)
+        return value
+
+    async def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        client = await self._get_client()
+        data = await client.get(key)
+        if data is None:
+            return NO_VALUE, None
+        value, created_at = self._unpack_value(data)
+        return value, created_at
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        client = await self._get_client()
+        now = time.time()
+        packed = self._pack_value(value, now)
+        await client.setex(key, ttl, packed)
+
+    async def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        client = await self._get_client()
+        await client.delete(key)
+
+    async def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        client = await self._get_client()
+        if pattern is None:
+            pattern = '*'
+
+        count = 0
+        async for key in client.scan_iter(match=pattern):
+            await client.delete(key)
+            count += 1
+        return count
+
+    async def keys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        client = await self._get_client()
+        redis_pattern = pattern or '*'
+        async for key in client.scan_iter(match=redis_pattern):
+            yield key.decode() if isinstance(key, bytes) else key
+
+    async def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        count = 0
+        async for _ in self.keys(pattern):
+            count += 1
+        return count
+
+    async def close(self) -> None:
+        """Close the Redis connection.
+        """
+        if self._client is not None:
+            await self._client.close()
+            self._client = None

cachu/backends/async_sqlite.py

@@ -0,0 +1,244 @@
+"""Async SQLite-based cache backend using aiosqlite.
+"""
+import asyncio
+import pickle
+import time
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from . import NO_VALUE
+from .async_base import AsyncBackend
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+
+def _get_aiosqlite_module() -> Any:
+    """Import aiosqlite module, raising helpful error if not installed.
+    """
+    try:
+        import aiosqlite
+        return aiosqlite
+    except ImportError as e:
+        raise RuntimeError(
+            "Async SQLite support requires the 'aiosqlite' package. "
+            "Install with: pip install cachu[async]"
+        ) from e
+
+
+class AsyncSqliteBackend(AsyncBackend):
+    """Async SQLite file-based cache backend using aiosqlite.
+    """
+
+    def __init__(self, filepath: str) -> None:
+        self._filepath = filepath
+        self._connection: aiosqlite.Connection | None = None
+        self._lock = asyncio.Lock()
+        self._initialized = False
+
+    async def _ensure_initialized(self) -> 'aiosqlite.Connection':
+        """Ensure database is initialized and return connection.
+        """
+        if self._connection is None:
+            aiosqlite = _get_aiosqlite_module()
+            self._connection = await aiosqlite.connect(self._filepath)
+
+        if not self._initialized:
+            await self._connection.execute('''
+                CREATE TABLE IF NOT EXISTS cache (
+                    key TEXT PRIMARY KEY,
+                    value BLOB NOT NULL,
+                    created_at REAL NOT NULL,
+                    expires_at REAL NOT NULL
+                )
+            ''')
+            await self._connection.execute('''
+                CREATE INDEX IF NOT EXISTS idx_cache_expires
+                ON cache(expires_at)
+            ''')
+            await self._connection.commit()
+            self._initialized = True
+
+        return self._connection
+
+    async def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found or expired.
+        """
+        async with self._lock:
+            try:
+                conn = await self._ensure_initialized()
+                cursor = await conn.execute(
+                    'SELECT value, expires_at FROM cache WHERE key = ?',
+                    (key,),
+                )
+                row = await cursor.fetchone()
+
+                if row is None:
+                    return NO_VALUE
+
+                value_blob, expires_at = row
+                if time.time() > expires_at:
+                    await conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                    await conn.commit()
+                    return NO_VALUE
+
+                return pickle.loads(value_blob)
+            except Exception:
+                return NO_VALUE
+
+    async def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        async with self._lock:
+            try:
+                conn = await self._ensure_initialized()
+                cursor = await conn.execute(
+                    'SELECT value, created_at, expires_at FROM cache WHERE key = ?',
+                    (key,),
+                )
+                row = await cursor.fetchone()
+
+                if row is None:
+                    return NO_VALUE, None
+
+                value_blob, created_at, expires_at = row
+                if time.time() > expires_at:
+                    await conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                    await conn.commit()
+                    return NO_VALUE, None
+
+                return pickle.loads(value_blob), created_at
+            except Exception:
+                return NO_VALUE, None
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        value_blob = pickle.dumps(value)
+
+        async with self._lock:
+            conn = await self._ensure_initialized()
+            await conn.execute(
+                '''INSERT OR REPLACE INTO cache (key, value, created_at, expires_at)
+                   VALUES (?, ?, ?, ?)''',
+                (key, value_blob, now, now + ttl),
+            )
+            await conn.commit()
+
+    async def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        async with self._lock:
+            try:
+                conn = await self._ensure_initialized()
+                await conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                await conn.commit()
+            except Exception:
+                pass
+
+    async def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        async with self._lock:
+            try:
+                conn = await self._ensure_initialized()
+                if pattern is None:
+                    cursor = await conn.execute('SELECT COUNT(*) FROM cache')
+                    row = await cursor.fetchone()
+                    count = row[0]
+                    await conn.execute('DELETE FROM cache')
+                    await conn.commit()
+                    return count
+
+                glob_pattern = self._fnmatch_to_glob(pattern)
+                cursor = await conn.execute(
+                    'SELECT COUNT(*) FROM cache WHERE key GLOB ?',
+                    (glob_pattern,),
+                )
+                row = await cursor.fetchone()
+                count = row[0]
+                await conn.execute('DELETE FROM cache WHERE key GLOB ?', (glob_pattern,))
+                await conn.commit()
+                return count
+            except Exception:
+                return 0
+
+    async def keys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        now = time.time()
+
+        async with self._lock:
+            conn = await self._ensure_initialized()
+            if pattern is None:
+                cursor = await conn.execute(
+                    'SELECT key FROM cache WHERE expires_at > ?',
+                    (now,),
+                )
+            else:
+                glob_pattern = self._fnmatch_to_glob(pattern)
+                cursor = await conn.execute(
+                    'SELECT key FROM cache WHERE key GLOB ? AND expires_at > ?',
+                    (glob_pattern, now),
+                )
+
+            all_keys = [row[0] for row in await cursor.fetchall()]
+
+        for key in all_keys:
+            yield key
+
+    async def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        now = time.time()
+
+        async with self._lock:
+            try:
+                conn = await self._ensure_initialized()
+                if pattern is None:
+                    cursor = await conn.execute(
+                        'SELECT COUNT(*) FROM cache WHERE expires_at > ?',
+                        (now,),
+                    )
+                else:
+                    glob_pattern = self._fnmatch_to_glob(pattern)
+                    cursor = await conn.execute(
+                        'SELECT COUNT(*) FROM cache WHERE key GLOB ? AND expires_at > ?',
+                        (glob_pattern, now),
+                    )
+
+                row = await cursor.fetchone()
+                return row[0]
+            except Exception:
+                return 0
+
+    def _fnmatch_to_glob(self, pattern: str) -> str:
+        """Convert fnmatch pattern to SQLite GLOB pattern.
+        """
+        return pattern
+
+    async def cleanup_expired(self) -> int:
+        """Remove expired entries. Returns count of removed entries.
+        """
+        now = time.time()
+
+        async with self._lock:
+            conn = await self._ensure_initialized()
+            cursor = await conn.execute(
+                'SELECT COUNT(*) FROM cache WHERE expires_at <= ?',
+                (now,),
+            )
+            row = await cursor.fetchone()
+            count = row[0]
+            await conn.execute('DELETE FROM cache WHERE expires_at <= ?', (now,))
+            await conn.commit()
+            return count
+
+    async def close(self) -> None:
+        """Close the database connection.
+        """
+        if self._connection is not None:
+            await self._connection.close()
+            self._connection = None
+            self._initialized = False

cachu/backends/file.py

@@ -1,158 +1,10 @@
-"""File-based cache backend using DBM.
-"""
-import dbm
-import fnmatch
-import pathlib
-import pickle
-import struct
-import threading
-import time
-from collections.abc import Iterator
-from typing import Any
-
-from . import NO_VALUE, Backend
-
-_METADATA_FORMAT = 'dd'
-_METADATA_SIZE = struct.calcsize(_METADATA_FORMAT)
-
-
-class FileBackend(Backend):
-    """DBM file-based cache backend.
-    """
-
-    def __init__(self, filepath: str) -> None:
-        self._filepath = filepath
-        self._lock = threading.RLock()
-        self._ensure_dir()
-
-    def _ensure_dir(self) -> None:
-        """Ensure the directory for the cache file exists.
-        """
-        directory = pathlib.Path(self._filepath).parent
-        if directory and not pathlib.Path(directory).exists():
-            pathlib.Path(directory).mkdir(exist_ok=True, parents=True)
-
-    def _pack_value(self, value: Any, created_at: float, expires_at: float) -> bytes:
-        """Pack value with metadata.
-        """
-        metadata = struct.pack(_METADATA_FORMAT, created_at, expires_at)
-        pickled = pickle.dumps(value)
-        return metadata + pickled
-
-    def _unpack_value(self, data: bytes) -> tuple[Any, float, float]:
-        """Unpack value and metadata.
-        """
-        created_at, expires_at = struct.unpack(_METADATA_FORMAT, data[:_METADATA_SIZE])
-        value = pickle.loads(data[_METADATA_SIZE:])
-        return value, created_at, expires_at
-
-    def get(self, key: str) -> Any:
-        """Get value by key. Returns NO_VALUE if not found or expired.
-        """
-        with self._lock:
-            try:
-                with dbm.open(self._filepath, 'c') as db:
-                    data = db.get(key.encode())
-                    if data is None:
-                        return NO_VALUE
-
-                    value, created_at, expires_at = self._unpack_value(data)
-                    if time.time() > expires_at:
-                        del db[key.encode()]
-                        return NO_VALUE
+"""File-based cache backend using SQLite.
 
-                    return value
-            except Exception:
-                return NO_VALUE
-
-    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
-        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
-        """
-        with self._lock:
-            try:
-                with dbm.open(self._filepath, 'c') as db:
-                    data = db.get(key.encode())
-                    if data is None:
-                        return NO_VALUE, None
-
-                    value, created_at, expires_at = self._unpack_value(data)
-                    if time.time() > expires_at:
-                        del db[key.encode()]
-                        return NO_VALUE, None
-
-                    return value, created_at
-            except Exception:
-                return NO_VALUE, None
-
-    def set(self, key: str, value: Any, ttl: int) -> None:
-        """Set value with TTL in seconds.
-        """
-        now = time.time()
-        packed = self._pack_value(value, now, now + ttl)
-        with self._lock, dbm.open(self._filepath, 'c') as db:
-            db[key.encode()] = packed
-
-    def delete(self, key: str) -> None:
-        """Delete value by key.
-        """
-        with self._lock:
-            try:
-                with dbm.open(self._filepath, 'c') as db:
-                    if key.encode() in db:
-                        del db[key.encode()]
-            except Exception:
-                pass
-
-    def clear(self, pattern: str | None = None) -> int:
-        """Clear entries matching pattern. Returns count of cleared entries.
-        """
-        with self._lock:
-            try:
-                if pattern is None:
-                    with dbm.open(self._filepath, 'n'):
-                        pass
-                    return -1
-
-                with dbm.open(self._filepath, 'c') as db:
-                    keys_to_delete = [
-                        k for k in db.keys()
-                        if fnmatch.fnmatch(k.decode(), pattern)
-                    ]
-                    for key in keys_to_delete:
-                        del db[key]
-                    return len(keys_to_delete)
-            except Exception:
-                return 0
-
-    def keys(self, pattern: str | None = None) -> Iterator[str]:
-        """Iterate over keys matching pattern.
-        """
-        now = time.time()
-        with self._lock:
-            try:
-                with dbm.open(self._filepath, 'c') as db:
-                    all_keys = [k.decode() for k in db.keys()]
-            except Exception:
-                return
-
-        for key in all_keys:
-            with self._lock:
-                try:
-                    with dbm.open(self._filepath, 'c') as db:
-                        data = db.get(key.encode())
-                        if data is None:
-                            continue
-                        _, _, expires_at = self._unpack_value(data)
-                        if now > expires_at:
-                            del db[key.encode()]
-                            continue
-                except Exception:
-                    continue
+Note: This module previously used DBM. Migration to SQLite happened in v0.2.0.
+Existing DBM cache files will be ignored - clear your cache directory on upgrade.
+"""
+from .sqlite import SqliteBackend
 
-            if pattern is None or fnmatch.fnmatch(key, pattern):
-                yield key
+FileBackend = SqliteBackend
 
-    def count(self, pattern: str | None = None) -> int:
-        """Count keys matching pattern.
-        """
-        return sum(1 for _ in self.keys(pattern))
+__all__ = ['FileBackend']