cachu 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

cachu/backends/sqlite.py

@@ -8,7 +8,8 @@ import time
 from collections.abc import AsyncIterator, Iterator
 from typing import TYPE_CHECKING, Any
 
-from . import NO_VALUE, AsyncBackend, Backend
+from ..mutex import AsyncCacheMutex, AsyncioMutex, CacheMutex, ThreadingMutex
+from . import NO_VALUE, Backend
 
 if TYPE_CHECKING:
     import aiosqlite
@@ -28,18 +29,36 @@ def _get_aiosqlite_module() -> Any:
 
 
 class SqliteBackend(Backend):
-    """SQLite file-based cache backend.
+    """Unified SQLite file-based cache backend with both sync and async interfaces.
     """
 
     def __init__(self, filepath: str) -> None:
         self._filepath = filepath
-        self._lock = threading.RLock()
-        self._init_db()
+        self._sync_lock = threading.RLock()
+        self._async_lock: asyncio.Lock | None = None
+        self._async_write_lock: asyncio.Lock | None = None
+        self._async_connection: aiosqlite.Connection | None = None
+        self._async_initialized = False
+        self._init_sync_db()
+
+    def _get_async_lock(self) -> asyncio.Lock:
+        """Lazy-create async init lock (must be called from async context).
+        """
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        return self._async_lock
+
+    def _get_async_write_lock(self) -> asyncio.Lock:
+        """Lazy-create async write lock (must be called from async context).
+        """
+        if self._async_write_lock is None:
+            self._async_write_lock = asyncio.Lock()
+        return self._async_write_lock
 
-    def _init_db(self) -> None:
-        """Initialize database schema.
+    def _init_sync_db(self) -> None:
+        """Initialize sync database schema.
         """
-        with self._lock:
+        with self._sync_lock:
             conn = sqlite3.connect(self._filepath)
             try:
                 conn.execute("""
@@ -58,16 +77,65 @@ class SqliteBackend(Backend):
             finally:
                 conn.close()
 
-    def _get_connection(self) -> sqlite3.Connection:
-        """Get a database connection.
+    async def _ensure_async_initialized(self) -> 'aiosqlite.Connection':
+        """Ensure async database is initialized and return connection.
+        """
+        async with self._get_async_lock():
+            if self._async_connection is None:
+                aiosqlite = _get_aiosqlite_module()
+                self._async_connection = await aiosqlite.connect(self._filepath)
+                await self._async_connection.execute('PRAGMA journal_mode=WAL')
+                await self._async_connection.execute('PRAGMA busy_timeout=5000')
+
+            if not self._async_initialized:
+                await self._async_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._async_connection.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_cache_expires
+                    ON cache(expires_at)
+                """)
+                await self._async_connection.commit()
+                self._async_initialized = True
+
+        return self._async_connection
+
+    def _get_sync_connection(self) -> sqlite3.Connection:
+        """Get a sync database connection.
         """
         return sqlite3.connect(self._filepath)
 
+    def _fnmatch_to_glob(self, pattern: str) -> str:
+        """Convert fnmatch pattern to SQLite GLOB pattern.
+        """
+        return pattern
+
+    def _schedule_async_delete(self, key: str) -> None:
+        """Schedule a background deletion task (fire-and-forget).
+        """
+        async def _delete() -> None:
+            try:
+                async with self._get_async_write_lock():
+                    conn = await self._ensure_async_initialized()
+                    await conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                    await conn.commit()
+            except Exception:
+                pass
+
+        asyncio.create_task(_delete())
+
+    # ===== Sync interface =====
+
     def get(self, key: str) -> Any:
         """Get value by key. Returns NO_VALUE if not found or expired.
         """
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 cursor = conn.execute(
                     'SELECT value, expires_at FROM cache WHERE key = ?',
@@ -93,8 +161,8 @@ class SqliteBackend(Backend):
     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:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 cursor = conn.execute(
                     'SELECT value, created_at, expires_at FROM cache WHERE key = ?',
@@ -123,8 +191,8 @@ class SqliteBackend(Backend):
         now = time.time()
         value_blob = pickle.dumps(value)
 
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 conn.execute(
                     """INSERT OR REPLACE INTO cache (key, value, created_at, expires_at)
@@ -138,8 +206,8 @@ class SqliteBackend(Backend):
     def delete(self, key: str) -> None:
         """Delete value by key.
         """
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 conn.execute('DELETE FROM cache WHERE key = ?', (key,))
                 conn.commit()
@@ -151,8 +219,8 @@ class SqliteBackend(Backend):
     def clear(self, pattern: str | None = None) -> int:
         """Clear entries matching pattern. Returns count of cleared entries.
         """
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 if pattern is None:
                     cursor = conn.execute('SELECT COUNT(*) FROM cache')
@@ -180,8 +248,8 @@ class SqliteBackend(Backend):
         """
         now = time.time()
 
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 if pattern is None:
                     cursor = conn.execute(
@@ -206,8 +274,8 @@ class SqliteBackend(Backend):
         """
         now = time.time()
 
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 if pattern is None:
                     cursor = conn.execute(
@@ -227,21 +295,18 @@ class SqliteBackend(Backend):
             finally:
                 conn.close()
 
-    def _fnmatch_to_glob(self, pattern: str) -> str:
-        """Convert fnmatch pattern to SQLite GLOB pattern.
-
-        fnmatch uses * and ? which are the same as SQLite GLOB.
-        The main difference is character classes [...] which we don't use.
+    def get_mutex(self, key: str) -> CacheMutex:
+        """Get a mutex for dogpile prevention on the given key.
         """
-        return pattern
+        return ThreadingMutex(f'sqlite:{self._filepath}:{key}')
 
     def cleanup_expired(self) -> int:
         """Remove expired entries. Returns count of removed entries.
         """
         now = time.time()
 
-        with self._lock:
-            conn = self._get_connection()
+        with self._sync_lock:
+            conn = self._get_sync_connection()
             try:
                 cursor = conn.execute(
                     'SELECT COUNT(*) FROM cache WHERE expires_at <= ?',
@@ -254,65 +319,13 @@ class SqliteBackend(Backend):
             finally:
                 conn.close()
 
+    # ===== Async interface =====
 
-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._init_lock = asyncio.Lock()
-        self._write_lock = asyncio.Lock()
-        self._initialized = False
-
-    async def _ensure_initialized(self) -> 'aiosqlite.Connection':
-        """Ensure database is initialized and return connection.
-        """
-        async with self._init_lock:
-            if self._connection is None:
-                aiosqlite = _get_aiosqlite_module()
-                self._connection = await aiosqlite.connect(self._filepath)
-                await self._connection.execute('PRAGMA journal_mode=WAL')
-                await self._connection.execute('PRAGMA busy_timeout=5000')
-
-            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
-
-    def _schedule_delete(self, key: str) -> None:
-        """Schedule a background deletion task (fire-and-forget).
-        """
-        async def _delete() -> None:
-            try:
-                async with self._write_lock:
-                    conn = await self._ensure_initialized()
-                    await conn.execute('DELETE FROM cache WHERE key = ?', (key,))
-                    await conn.commit()
-            except Exception:
-                pass
-
-        asyncio.create_task(_delete())
-
-    async def get(self, key: str) -> Any:
-        """Get value by key. Returns NO_VALUE if not found or expired.
+    async def aget(self, key: str) -> Any:
+        """Async get value by key. Returns NO_VALUE if not found or expired.
         """
         try:
-            conn = await self._ensure_initialized()
+            conn = await self._ensure_async_initialized()
             cursor = await conn.execute(
                 'SELECT value, expires_at FROM cache WHERE key = ?',
                 (key,),
@@ -324,18 +337,18 @@ class AsyncSqliteBackend(AsyncBackend):
 
             value_blob, expires_at = row
             if time.time() > expires_at:
-                self._schedule_delete(key)
+                self._schedule_async_delete(key)
                 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 def aget_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Async get value and creation timestamp. Returns (NO_VALUE, None) if not found.
         """
         try:
-            conn = await self._ensure_initialized()
+            conn = await self._ensure_async_initialized()
             cursor = await conn.execute(
                 'SELECT value, created_at, expires_at FROM cache WHERE key = ?',
                 (key,),
@@ -347,21 +360,21 @@ class AsyncSqliteBackend(AsyncBackend):
 
             value_blob, created_at, expires_at = row
             if time.time() > expires_at:
-                self._schedule_delete(key)
+                self._schedule_async_delete(key)
                 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.
+    async def aset(self, key: str, value: Any, ttl: int) -> None:
+        """Async set value with TTL in seconds.
         """
         now = time.time()
         value_blob = pickle.dumps(value)
 
-        async with self._write_lock:
-            conn = await self._ensure_initialized()
+        async with self._get_async_write_lock():
+            conn = await self._ensure_async_initialized()
             await conn.execute(
                 """INSERT OR REPLACE INTO cache (key, value, created_at, expires_at)
                    VALUES (?, ?, ?, ?)""",
@@ -369,23 +382,23 @@ class AsyncSqliteBackend(AsyncBackend):
             )
             await conn.commit()
 
-    async def delete(self, key: str) -> None:
-        """Delete value by key.
+    async def adelete(self, key: str) -> None:
+        """Async delete value by key.
         """
-        async with self._write_lock:
+        async with self._get_async_write_lock():
             try:
-                conn = await self._ensure_initialized()
+                conn = await self._ensure_async_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 def aclear(self, pattern: str | None = None) -> int:
+        """Async clear entries matching pattern. Returns count of cleared entries.
         """
-        async with self._write_lock:
+        async with self._get_async_write_lock():
             try:
-                conn = await self._ensure_initialized()
+                conn = await self._ensure_async_initialized()
                 if pattern is None:
                     cursor = await conn.execute('SELECT COUNT(*) FROM cache')
                     row = await cursor.fetchone()
@@ -407,11 +420,11 @@ class AsyncSqliteBackend(AsyncBackend):
             except Exception:
                 return 0
 
-    async def keys(self, pattern: str | None = None) -> AsyncIterator[str]:
-        """Iterate over keys matching pattern.
+    async def akeys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Async iterate over keys matching pattern.
         """
         now = time.time()
-        conn = await self._ensure_initialized()
+        conn = await self._ensure_async_initialized()
 
         if pattern is None:
             cursor = await conn.execute(
@@ -430,13 +443,13 @@ class AsyncSqliteBackend(AsyncBackend):
         for key in all_keys:
             yield key
 
-    async def count(self, pattern: str | None = None) -> int:
-        """Count keys matching pattern.
+    async def acount(self, pattern: str | None = None) -> int:
+        """Async count keys matching pattern.
         """
         now = time.time()
 
         try:
-            conn = await self._ensure_initialized()
+            conn = await self._ensure_async_initialized()
             if pattern is None:
                 cursor = await conn.execute(
                     'SELECT COUNT(*) FROM cache WHERE expires_at > ?',
@@ -454,18 +467,18 @@ class AsyncSqliteBackend(AsyncBackend):
         except Exception:
             return 0
 
-    def _fnmatch_to_glob(self, pattern: str) -> str:
-        """Convert fnmatch pattern to SQLite GLOB pattern.
+    def get_async_mutex(self, key: str) -> AsyncCacheMutex:
+        """Get an async mutex for dogpile prevention on the given key.
         """
-        return pattern
+        return AsyncioMutex(f'sqlite:{self._filepath}:{key}')
 
-    async def cleanup_expired(self) -> int:
-        """Remove expired entries. Returns count of removed entries.
+    async def acleanup_expired(self) -> int:
+        """Async remove expired entries. Returns count of removed entries.
         """
         now = time.time()
 
-        async with self._write_lock:
-            conn = await self._ensure_initialized()
+        async with self._get_async_write_lock():
+            conn = await self._ensure_async_initialized()
             cursor = await conn.execute(
                 'SELECT COUNT(*) FROM cache WHERE expires_at <= ?',
                 (now,),
@@ -476,10 +489,37 @@ class AsyncSqliteBackend(AsyncBackend):
             await conn.commit()
             return count
 
-    async def close(self) -> None:
-        """Close the database connection.
+    # ===== Lifecycle =====
+
+    def _close_async_connection_sync(self) -> None:
+        """Forcefully close async connection from sync context.
+
+        This accesses aiosqlite internals as there's no public sync close API.
+        """
+        if self._async_connection is None:
+            return
+
+        conn = self._async_connection
+        self._async_connection = None
+        self._async_initialized = False
+
+        try:
+            conn._running = False
+            if hasattr(conn, '_connection') and conn._connection:
+                conn._connection.close()
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        """Close all backend resources from sync context.
+        """
+        self._close_async_connection_sync()
+
+    async def aclose(self) -> None:
+        """Close all backend resources from async context.
         """
-        if self._connection is not None:
-            await self._connection.close()
-            self._connection = None
-            self._initialized = False
+        if self._async_connection is not None:
+            conn = self._async_connection
+            self._async_connection = None
+            self._async_initialized = False
+            await conn.close()

cachu/config.py

@@ -58,6 +58,7 @@ class CacheConfig:
     key_prefix: str = ''
     file_dir: str = '/tmp'
     redis_url: str = 'redis://localhost:6379/0'
+    lock_timeout: float = 10.0
 
 
 class ConfigRegistry:
@@ -79,6 +80,7 @@ class ConfigRegistry:
         key_prefix: str | None = None,
         file_dir: str | None = None,
         redis_url: str | None = None,
+        lock_timeout: float | None = None,
     ) -> CacheConfig:
         """Configure cache for a specific package.
         """
@@ -90,6 +92,7 @@ class ConfigRegistry:
             'key_prefix': key_prefix,
             'file_dir': str(file_dir) if file_dir else None,
             'redis_url': redis_url,
+            'lock_timeout': lock_timeout,
         }
         updates = {k: v for k, v in updates.items() if v is not None}
 
@@ -152,6 +155,7 @@ def configure(
     key_prefix: str | None = None,
     file_dir: str | None = None,
     redis_url: str | None = None,
+    lock_timeout: float | None = None,
 ) -> CacheConfig:
     """Configure cache settings for the caller's package.
 
@@ -163,12 +167,14 @@ def configure(
         key_prefix: Prefix for all cache keys (for versioning/debugging)
         file_dir: Directory for file-based caches
         redis_url: Redis connection URL (e.g., 'redis://localhost:6379/0')
+        lock_timeout: Timeout for distributed locks in seconds (default: 10.0)
     """
     return _registry.configure(
         backend=backend,
         key_prefix=key_prefix,
         file_dir=str(file_dir) if file_dir else None,
         redis_url=redis_url,
+        lock_timeout=lock_timeout,
     )