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

cachu/backends/sqlite.py

@@ -0,0 +1,240 @@
+"""SQLite-based cache backend.
+"""
+import fnmatch
+import pickle
+import sqlite3
+import threading
+import time
+from collections.abc import Iterator
+from typing import Any
+
+from . import NO_VALUE, Backend
+
+
+class SqliteBackend(Backend):
+    """SQLite file-based cache backend.
+    """
+
+    def __init__(self, filepath: str) -> None:
+        self._filepath = filepath
+        self._lock = threading.RLock()
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Initialize database schema.
+        """
+        with self._lock:
+            conn = sqlite3.connect(self._filepath)
+            try:
+                conn.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
+                    )
+                ''')
+                conn.execute('''
+                    CREATE INDEX IF NOT EXISTS idx_cache_expires
+                    ON cache(expires_at)
+                ''')
+                conn.commit()
+            finally:
+                conn.close()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get a database connection.
+        """
+        return sqlite3.connect(self._filepath)
+
+    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()
+            try:
+                cursor = conn.execute(
+                    'SELECT value, expires_at FROM cache WHERE key = ?',
+                    (key,),
+                )
+                row = cursor.fetchone()
+
+                if row is None:
+                    return NO_VALUE
+
+                value_blob, expires_at = row
+                if time.time() > expires_at:
+                    conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                    conn.commit()
+                    return NO_VALUE
+
+                return pickle.loads(value_blob)
+            except Exception:
+                return NO_VALUE
+            finally:
+                conn.close()
+
+    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()
+            try:
+                cursor = conn.execute(
+                    'SELECT value, created_at, expires_at FROM cache WHERE key = ?',
+                    (key,),
+                )
+                row = cursor.fetchone()
+
+                if row is None:
+                    return NO_VALUE, None
+
+                value_blob, created_at, expires_at = row
+                if time.time() > expires_at:
+                    conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                    conn.commit()
+                    return NO_VALUE, None
+
+                return pickle.loads(value_blob), created_at
+            except Exception:
+                return NO_VALUE, None
+            finally:
+                conn.close()
+
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        value_blob = pickle.dumps(value)
+
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                conn.execute(
+                    '''INSERT OR REPLACE INTO cache (key, value, created_at, expires_at)
+                       VALUES (?, ?, ?, ?)''',
+                    (key, value_blob, now, now + ttl),
+                )
+                conn.commit()
+            finally:
+                conn.close()
+
+    def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                conn.execute('DELETE FROM cache WHERE key = ?', (key,))
+                conn.commit()
+            except Exception:
+                pass
+            finally:
+                conn.close()
+
+    def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                if pattern is None:
+                    cursor = conn.execute('SELECT COUNT(*) FROM cache')
+                    count = cursor.fetchone()[0]
+                    conn.execute('DELETE FROM cache')
+                    conn.commit()
+                    return count
+
+                glob_pattern = self._fnmatch_to_glob(pattern)
+                cursor = conn.execute(
+                    'SELECT COUNT(*) FROM cache WHERE key GLOB ?',
+                    (glob_pattern,),
+                )
+                count = cursor.fetchone()[0]
+                conn.execute('DELETE FROM cache WHERE key GLOB ?', (glob_pattern,))
+                conn.commit()
+                return count
+            except Exception:
+                return 0
+            finally:
+                conn.close()
+
+    def keys(self, pattern: str | None = None) -> Iterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        now = time.time()
+
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                if pattern is None:
+                    cursor = conn.execute(
+                        'SELECT key FROM cache WHERE expires_at > ?',
+                        (now,),
+                    )
+                else:
+                    glob_pattern = self._fnmatch_to_glob(pattern)
+                    cursor = conn.execute(
+                        'SELECT key FROM cache WHERE key GLOB ? AND expires_at > ?',
+                        (glob_pattern, now),
+                    )
+
+                all_keys = [row[0] for row in cursor.fetchall()]
+            finally:
+                conn.close()
+
+        for key in all_keys:
+            yield key
+
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        now = time.time()
+
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                if pattern is None:
+                    cursor = conn.execute(
+                        'SELECT COUNT(*) FROM cache WHERE expires_at > ?',
+                        (now,),
+                    )
+                else:
+                    glob_pattern = self._fnmatch_to_glob(pattern)
+                    cursor = conn.execute(
+                        'SELECT COUNT(*) FROM cache WHERE key GLOB ? AND expires_at > ?',
+                        (glob_pattern, now),
+                    )
+
+                return cursor.fetchone()[0]
+            except Exception:
+                return 0
+            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.
+        """
+        return pattern
+
+    def cleanup_expired(self) -> int:
+        """Remove expired entries. Returns count of removed entries.
+        """
+        now = time.time()
+
+        with self._lock:
+            conn = self._get_connection()
+            try:
+                cursor = conn.execute(
+                    'SELECT COUNT(*) FROM cache WHERE expires_at <= ?',
+                    (now,),
+                )
+                count = cursor.fetchone()[0]
+                conn.execute('DELETE FROM cache WHERE expires_at <= ?', (now,))
+                conn.commit()
+                return count
+            finally:
+                conn.close()

cachu/decorator.py

@@ -4,9 +4,9 @@ import logging
 import os
 import threading
 import time
+from collections.abc import Callable
 from functools import wraps
 from typing import Any
-from collections.abc import Callable
 
 from .backends import NO_VALUE, Backend
 from .backends.file import FileBackend
@@ -39,11 +39,11 @@ def _get_backend(package: str | None, backend_type: str, ttl: int) -> Backend:
             backend = MemoryBackend()
         elif backend_type == 'file':
             if ttl < 60:
-                filename = f'cache{ttl}sec'
+                filename = f'cache{ttl}sec.db'
             elif ttl < 3600:
-                filename = f'cache{ttl // 60}min'
+                filename = f'cache{ttl // 60}min.db'
             else:
-                filename = f'cache{ttl // 3600}hour'
+                filename = f'cache{ttl // 3600}hour.db'
 
             if package:
                 filename = f'{package}_{filename}'
@@ -61,7 +61,7 @@ def _get_backend(package: str | None, backend_type: str, ttl: int) -> Backend:
         return backend
 
 
-def get_backend(backend_type: str | None = None, package: str | None = None, ttl: int = 300) -> Backend:
+def get_backend(backend_type: str | None = None, package: str | None = None, *, ttl: int) -> Backend:
     """Get a backend instance.
 
     Args:

{cachu-0.1.3.dist-info → cachu-0.2.1.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cachu
-Version: 0.1.3
-Summary: Flexible caching library built on dogpile.cache
+Version: 0.2.1
+Summary: Flexible caching library with sync and async support for memory, file (SQLite), and Redis backends
 Author: bissli
 License-Expression: 0BSD
 Project-URL: Repository, https://github.com/bissli/cachu.git
@@ -9,13 +9,17 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: dogpile.cache
 Requires-Dist: func-timeout
+Provides-Extra: async
+Requires-Dist: aiosqlite; extra == "async"
 Provides-Extra: redis
-Requires-Dist: redis; extra == "redis"
+Requires-Dist: redis>=4.2.0; extra == "redis"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: pytest-mock; extra == "test"
-Requires-Dist: redis; extra == "test"
+Requires-Dist: redis>=4.2.0; extra == "test"
 Requires-Dist: testcontainers[redis]; extra == "test"
+Requires-Dist: aiosqlite; extra == "test"
 
 # cachu
 
@@ -71,13 +75,13 @@ cachu.configure(
 
 ### Configuration Options
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `backend` | `'memory'` | Default backend type |
-| `key_prefix` | `''` | Prefix for all cache keys (useful for versioning) |
-| `file_dir` | `'/tmp'` | Directory for file-based caches |
-| `redis_url` | `'redis://localhost:6379/0'` | Redis connection URL |
-| `redis_distributed` | `False` | Enable distributed locks for Redis |
+| Option              | Default                      | Description                                       |
+| ------------------- | ---------------------------- | ------------------------------------------------- |
+| `backend`           | `'memory'`                   | Default backend type                              |
+| `key_prefix`        | `''`                         | Prefix for all cache keys (useful for versioning) |
+| `file_dir`          | `'/tmp'`                     | Directory for file-based caches                   |
+| `redis_url`         | `'redis://localhost:6379/0'` | Redis connection URL                              |
+| `redis_distributed` | `False`                      | Enable distributed locks for Redis                |
 
 ### Package Isolation
 
@@ -300,12 +304,12 @@ cache_clear()
 
 **Clearing behavior:**
 
-| `ttl` | `tag` | `backend` | Behavior |
-|-------|-------|-----------|----------|
-| `300` | `None` | `'memory'` | All keys in 300s memory region |
-| `300` | `'users'` | `'memory'` | Only "users" tag in 300s memory region |
-| `None` | `None` | `'memory'` | All memory regions |
-| `None` | `'users'` | `None` | "users" tag across all backends |
+| `ttl`  | `tag`     | `backend`  | Behavior                               |
+| ------ | --------- | ---------- | -------------------------------------- |
+| `300`  | `None`    | `'memory'` | All keys in 300s memory region         |
+| `300`  | `'users'` | `'memory'` | Only "users" tag in 300s memory region |
+| `None` | `None`    | `'memory'` | All memory regions                     |
+| `None` | `'users'` | `None`     | "users" tag across all backends        |
 
 ### Cross-Module Clearing
 
@@ -363,6 +367,38 @@ if cachu.is_disabled():
     print("Caching is disabled")
 ```
 
+## Async Support
+
+The library provides full async/await support with matching APIs:
+
+```python
+from cachu import async_cache, async_cache_get, async_cache_set, async_cache_delete
+from cachu import async_cache_clear, async_cache_info
+
+@async_cache(ttl=300, backend='memory')
+async def get_user(user_id: int) -> dict:
+    return await fetch_from_database(user_id)
+
+# Usage
+user = await get_user(123)  # Cache miss
+user = await get_user(123)  # Cache hit
+
+# Per-call control works the same way
+user = await get_user(123, _skip_cache=True)
+user = await get_user(123, _overwrite_cache=True)
+
+# CRUD operations
+cached = await async_cache_get(get_user, user_id=123)
+await async_cache_set(get_user, {'id': 123, 'name': 'Test'}, user_id=123)
+await async_cache_delete(get_user, user_id=123)
+await async_cache_clear(backend='memory', ttl=300)
+
+# Statistics
+info = await async_cache_info(get_user)
+```
+
+All decorator options (`ttl`, `backend`, `tag`, `exclude`, `cache_if`, `validate`, `package`) work identically to the sync version.
+
 ## Advanced
 
 ### Direct Backend Access
@@ -397,25 +433,40 @@ from cachu import (
     enable,
     is_disabled,
 
-    # Decorator
+    # Sync Decorator
     cache,
 
-    # CRUD Operations
+    # Sync CRUD Operations
     cache_get,
     cache_set,
     cache_delete,
     cache_clear,
     cache_info,
 
+    # Async Decorator
+    async_cache,
+
+    # Async CRUD Operations
+    async_cache_get,
+    async_cache_set,
+    async_cache_delete,
+    async_cache_clear,
+    async_cache_info,
+
     # Advanced
     get_backend,
+    get_async_backend,
     get_redis_client,
+    Backend,
+    AsyncBackend,
+    clear_async_backends,
 )
 ```
 
 ## Features
 
-- **Multiple backends**: Memory, file (DBM), and Redis
+- **Multiple backends**: Memory, file (SQLite), and Redis
+- **Async support**: Full async/await API with `@async_cache` decorator
 - **Flexible TTL**: Configure different TTLs for different use cases
 - **Tags**: Organize and selectively clear cache entries
 - **Package isolation**: Each package gets isolated configuration

cachu-0.2.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+cachu/__init__.py,sha256=-eqMY3cCuepixdZ-FefQsRXPufVSgrEMlYkYwylSlTM,1286
+cachu/async_decorator.py,sha256=Jx2fHESLlld7NZiD2-6kcozukJtp5efnt4cMhntDDRA,8939
+cachu/async_operations.py,sha256=eVqhZk3FVLNip_abjnCzG8AajzvJTtXbpL--dpMXBlc,5597
+cachu/config.py,sha256=KtcDGpSTJmjRrcNLz9_Om3O814oJJ3p8gntB84Pd6Dk,5922
+cachu/decorator.py,sha256=RHwDRZxZfOkBgEK1XgRyis22bxQ0ba0X4NtHBd9FTb4,8161
+cachu/keys.py,sha256=fwwNOpnDJFCIWZoQ5UGJWhJa6xu36hsBsURI-n2NJKU,3557
+cachu/operations.py,sha256=t42_Er-O59vrwFa5jdf4yq3Jr4li2l7php4yMVJnxPs,5588
+cachu/types.py,sha256=FghBN5GhxnrpuT4WUL9iNnAfdoH__cw9_Ag4kHbIXq4,723
+cachu/backends/__init__.py,sha256=Jn2yBAMmJ8d0J_NyjOtxRt7UTyMLf1rlY8QJ049hXE8,1318
+cachu/backends/async_base.py,sha256=oZ3K3PhsYkbgZxFLFk3_NbxBxtNopqS90HZBizwg_q8,1394
+cachu/backends/async_memory.py,sha256=SQvSHeWbySa52BnQLF75nhVXgsydubNu84a8hvSzQSc,3457
+cachu/backends/async_redis.py,sha256=8kefPIoIJDAZ6C6HJCvHqKFMDS10sJYh8YcJMpXpQm8,4455
+cachu/backends/async_sqlite.py,sha256=r-c1cNVl6JEApMGhw8Qw7843Vuj_LVRAM-MGgoIjah0,8423
+cachu/backends/file.py,sha256=Pu01VtgHDgK6ev5hqyZXuJRCSB2VbNKHQ4w4nNKNyeI,298
+cachu/backends/memory.py,sha256=kIgrVU8k_3Aquyj2PDf8IPbTjCITM_0V5GU47m3fJmo,3138
+cachu/backends/redis.py,sha256=yE5rEBgOij9QOeC1VhWdIbGCgi442q-aWfmbbG4aNSE,3858
+cachu/backends/sqlite.py,sha256=whduN5G_bN6ZJNuCBwbraDcadv_sg0j-OEiFnP8EEsk,7803
+cachu-0.2.1.dist-info/METADATA,sha256=XZxtIkb4Mqd3Mbbw0DAlyfW5N1NJeUKiEPP6ybzIS8Q,11992
+cachu-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cachu-0.2.1.dist-info/top_level.txt,sha256=g80nNoMvLMzhSwQWV-JotCBqtsLAHeFMBo_g8hCK8hQ,6
+cachu-0.2.1.dist-info/RECORD,,

{cachu-0.1.3.dist-info → cachu-0.2.1.dist-info}/WHEEL

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