cachetout 0.1.0__tar.gz

cachetout-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.3
+Name: cachetout
+Version: 0.1.0
+Summary: A persistent, type-safe caching library for Python
+Author: Thomas Leese
+Author-email: Thomas Leese <thomas@leese.io>
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: platformdirs>=4.11.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Cachetout
+
+A persistent, type-safe caching library for Python.
+
+## Installation
+
+```shell
+pip install cachetout
+```
+
+## Usage
+
+### `Cache` class
+
+```python
+from cachetout import Cache
+
+# Create a cache (uses SQLite backend by default)
+cache = Cache("my_app_cache")
+
+# Store a value
+cache.set("user:123", {"name": "Alice", "age": 30})
+
+# Retrieve a value
+user = cache.get("user:123", type=dict)
+print(user)  # {'name': 'Alice', 'age': 30}
+
+# Delete a value
+cache.delete("user:123")
+```
+
+### `cache` decorator
+
+```python
+from datetime import timedelta
+from cachetout import cache
+
+@cache(expires_in=timedelta(hours=1))
+def fetch_user_data(user_id: int) -> dict:
+    # This function will only be called once per user_id per hour
+    print("Fetching data from API...")
+    return {"id": user_id, "data": "..."}
+
+# First call: fetches from source
+result1 = fetch_user_data(123)
+
+# Second call with same args: returns cached result
+result2 = fetch_user_data(123)
+```
+
+### Serialisation
+
+The library uses [msgspec] for serialisation, which respects the Python type hints:
+
+```python
+from dataclasses import dataclass
+from cachetout import Cache
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+
+cache = Cache("user_cache")
+
+# Store a dataclass instance
+user = User(id=1, name="Alice", email="alice@example.com")
+cache.set("user_1", user)
+
+# Retrieve with type hint
+retrieved: User = cache.get("user_1", type=User)
+print(retrieved.name)  # "Alice"
+```
+
+[msgspec]: https://msgspec.dev/
+
+### Expiration
+
+Set expiration when storing values:
+
+```python
+from datetime import datetime, timedelta, UTC
+from cachetout import Cache
+
+cache = Cache("temp_cache")
+
+# Expire in 1 hour
+cache.set("temp_data", "value", expires_at=datetime.now(tz=UTC) + timedelta(hours=1))
+
+# Or use timedelta with decorator
+@cache(expires_in=timedelta(minutes=30))
+def get_stock_price(symbol: str) -> float:
+    return fetch_from_api(symbol)
+```
+
+## Development
+
+### Tests
+
+```shell
+$ uv run pytest
+```
+
+### Linting
+
+```shell
+$ uv run ruff format
+$ uv run ruff check
+$ uv run ty check
+```

cachetout-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Cachetout
+
+A persistent, type-safe caching library for Python.
+
+## Installation
+
+```shell
+pip install cachetout
+```
+
+## Usage
+
+### `Cache` class
+
+```python
+from cachetout import Cache
+
+# Create a cache (uses SQLite backend by default)
+cache = Cache("my_app_cache")
+
+# Store a value
+cache.set("user:123", {"name": "Alice", "age": 30})
+
+# Retrieve a value
+user = cache.get("user:123", type=dict)
+print(user)  # {'name': 'Alice', 'age': 30}
+
+# Delete a value
+cache.delete("user:123")
+```
+
+### `cache` decorator
+
+```python
+from datetime import timedelta
+from cachetout import cache
+
+@cache(expires_in=timedelta(hours=1))
+def fetch_user_data(user_id: int) -> dict:
+    # This function will only be called once per user_id per hour
+    print("Fetching data from API...")
+    return {"id": user_id, "data": "..."}
+
+# First call: fetches from source
+result1 = fetch_user_data(123)
+
+# Second call with same args: returns cached result
+result2 = fetch_user_data(123)
+```
+
+### Serialisation
+
+The library uses [msgspec] for serialisation, which respects the Python type hints:
+
+```python
+from dataclasses import dataclass
+from cachetout import Cache
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+
+cache = Cache("user_cache")
+
+# Store a dataclass instance
+user = User(id=1, name="Alice", email="alice@example.com")
+cache.set("user_1", user)
+
+# Retrieve with type hint
+retrieved: User = cache.get("user_1", type=User)
+print(retrieved.name)  # "Alice"
+```
+
+[msgspec]: https://msgspec.dev/
+
+### Expiration
+
+Set expiration when storing values:
+
+```python
+from datetime import datetime, timedelta, UTC
+from cachetout import Cache
+
+cache = Cache("temp_cache")
+
+# Expire in 1 hour
+cache.set("temp_data", "value", expires_at=datetime.now(tz=UTC) + timedelta(hours=1))
+
+# Or use timedelta with decorator
+@cache(expires_in=timedelta(minutes=30))
+def get_stock_price(symbol: str) -> float:
+    return fetch_from_api(symbol)
+```
+
+## Development
+
+### Tests
+
+```shell
+$ uv run pytest
+```
+
+### Linting
+
+```shell
+$ uv run ruff format
+$ uv run ruff check
+$ uv run ty check
+```

cachetout-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "cachetout"
+version = "0.1.0"
+description = "A persistent, type-safe caching library for Python"
+readme = "README.md"
+authors = [
+    { name = "Thomas Leese", email = "thomas@leese.io" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "msgspec>=0.21.1",
+    "platformdirs>=4.11.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "freezegun>=1.5.5",
+    "pytest>=9.1.1",
+    "ruff>=0.16.0",
+    "ty>=0.0.63",
+]

cachetout-0.1.0/src/cachetout/__init__.py

@@ -0,0 +1,7 @@
+from .cache import Cache
+from .functools import cache
+
+__all__ = [
+    "Cache",
+    "cache",
+]

cachetout-0.1.0/src/cachetout/backends/abc.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class Backend(ABC):
+    @abstractmethod
+    def get(self, key: bytes, *, default: bytes | None = None) -> bytes | None: ...
+
+    @abstractmethod
+    def set(
+        self, key: bytes, value: bytes, *, expires_at: datetime | None = None
+    ) -> None: ...
+
+    @abstractmethod
+    def delete(self, key: bytes) -> bool: ...

cachetout-0.1.0/src/cachetout/backends/memory.py

@@ -0,0 +1,54 @@
+from datetime import UTC, datetime
+from threading import Lock
+
+from .abc import Backend
+
+
+class MemoryBackend(Backend):
+    def __init__(self):
+        self._lock = Lock()
+        self._data: dict[bytes, bytes] = {}
+        self._expirations: dict[bytes, datetime] = {}
+
+    def get(self, key: bytes, *, default: bytes | None = None) -> bytes | None:
+        with self._lock:
+            value = self._data.get(key, default)
+
+            try:
+                expires_at = self._expirations[key]
+                if expires_at < datetime.now(tz=UTC):
+                    self._delete(key)
+                    value = default
+            except KeyError:
+                pass
+
+        return value
+
+    def set(
+        self, key: bytes, value: bytes, *, expires_at: datetime | None = None
+    ) -> None:
+        with self._lock:
+            self._data[key] = value
+
+            if expires_at is not None:
+                self._expirations[key] = expires_at
+            else:
+                self._delete_expiration(key)
+
+    def delete(self, key: bytes) -> bool:
+        with self._lock:
+            return self._delete(key)
+
+    def _delete(self, key: bytes) -> bool:
+        try:
+            del self._data[key]
+            self._delete_expiration(key)
+            return True
+        except KeyError:
+            return False
+
+    def _delete_expiration(self, key: bytes):
+        try:
+            del self._expirations[key]
+        except KeyError:
+            pass

cachetout-0.1.0/src/cachetout/backends/sqlite.py

@@ -0,0 +1,61 @@
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .abc import Backend
+
+
+class SQLiteBackend(Backend):
+    create_table_sql = """
+                       CREATE TABLE IF NOT EXISTS cache(
+                           key BLOB PRIMARY KEY NOT NULL,
+                           value BLOB NOT NULL,
+                           expires_at TIMESTAMP
+                       )
+                       """
+
+    def __init__(self, *, path: Path):
+        self.connection = sqlite3.connect(path)
+        self.cursor = self.connection.cursor()
+
+        self.cursor.execute(self.create_table_sql)
+        self.connection.commit()
+
+    def get(self, key: bytes, *, default: bytes | None = None) -> bytes | None:
+        self.cursor.execute("SELECT value, expires_at FROM cache WHERE key = ?", (key,))
+        row = self.cursor.fetchone()
+
+        if row is None:
+            return default
+
+        value, expires_at_isoformat = row
+
+        if expires_at_isoformat is not None and datetime.fromisoformat(
+            expires_at_isoformat
+        ) < datetime.now(tz=UTC):
+            self.delete(key)
+            return default
+
+        return value
+
+    def set(
+        self, key: bytes, value: bytes, *, expires_at: datetime | None = None
+    ) -> None:
+        expires_at_isoformat = (
+            expires_at.isoformat() if expires_at is not None else None
+        )
+
+        self.cursor.execute(
+            """
+            INSERT INTO cache (key, value, expires_at)
+            VALUES (?, ?, ?)
+            ON CONFLICT(key) DO UPDATE SET value = ?, expires_at = ?
+            """,
+            (key, value, expires_at_isoformat, value, expires_at_isoformat),
+        )
+        self.connection.commit()
+
+    def delete(self, key: bytes) -> bool:
+        self.cursor.execute("DELETE FROM cache WHERE key = ?", (key,))
+        self.connection.commit()
+        return self.cursor.rowcount > 0

cachetout-0.1.0/src/cachetout/cache.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+from typing import TypeVar
+
+import msgspec.msgpack
+import platformdirs
+
+from .backends.abc import Backend
+from .backends.sqlite import SQLiteBackend
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class Cache:
+    def __init__(
+        self, name: str, app_name: str | None = None, backend: Backend | None = None
+    ):
+        self.name = name
+
+        if backend is not None:
+            self.backend = backend
+        else:
+            base_path = platformdirs.user_cache_path(app_name or name)
+            path = base_path / f"{name}.db"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            self.backend = SQLiteBackend(path=path)
+
+        self.encoder = msgspec.msgpack.Encoder()
+
+    def get(self, key: K, *, type: type[V], default: V | None = None) -> V | None:
+        encoded_key = self.encoder.encode(key)
+
+        value = self.backend.get(encoded_key)
+        if value is None:
+            return default
+
+        return msgspec.msgpack.decode(value, type=type)
+
+    def set(self, key: K, value: V, *, expires_at: datetime | None = None) -> None:
+        encoded_key = self.encoder.encode(key)
+        encoded_value = self.encoder.encode(value)
+
+        self.backend.set(encoded_key, encoded_value, expires_at=expires_at)
+
+    def delete(self, key: K) -> bool:
+        encoded_key = self.encoder.encode(key)
+        return self.backend.delete(encoded_key)

cachetout-0.1.0/src/cachetout/functools.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from functools import wraps
+from inspect import signature
+from typing import Any
+
+from cachetout.backends.abc import Backend
+
+from .cache import Cache
+
+DEFAULT = object()
+
+
+@dataclass
+class Key:
+    args: tuple[Any]
+    kwargs: dict[str, Any]
+
+
+def cache(*args, **kwargs):
+    name: str | None = kwargs.get("name")
+    app_name: str | None = kwargs.get("app_name")
+    backend: Backend | None = kwargs.get("backend")
+    expires_in: timedelta | None = kwargs.get("expires_in")
+
+    def decorator(f):
+        cache = Cache(name or f.__name__, app_name=app_name, backend=backend)
+        sig = signature(f)
+
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            key = Key(args, kwargs)
+
+            value = cache.get(key, default=DEFAULT, type=sig.return_annotation)
+            if value is DEFAULT:
+                value = f(*args, **kwargs)
+
+                if expires_in is not None:
+                    expires_at = datetime.now(tz=UTC) + expires_in
+                else:
+                    expires_at = None
+
+                cache.set(key, value, expires_at=expires_at)
+
+            return value
+
+        return wrapper
+
+    if len(args) == 1 and callable(args[0]):
+        return decorator(args[0])
+    else:
+        return decorator