pystackquery 1.0.1__py3-none-any.whl

pystackquery/__init__.py

@@ -0,0 +1,77 @@
+"""
+PyStackQuery - Async state management and caching for Python.
+
+Inspired by TanStack Query, this library provides a robust L1/L2 caching
+architecture designed for async Python applications (FastAPI, CLI, GUI).
+
+Core Features:
+    - SWR (Stale-While-Revalidate) caching logic
+    - Background L2 hydration (Redis, SQLite, etc.)
+    - Request deduplication and exponential backoff retries
+    - Reactive state observers with synchronous subscription
+    - Mutations with optimistic update support
+
+Example:
+    from pystackquery import QueryClient, QueryOptions
+
+    client = QueryClient()
+
+    # Create a reactive observer
+    observer = client.watch(
+        QueryOptions(query_key=("users",), query_fn=fetch_users)
+    )
+
+    # Subscribe is synchronous
+    unsubscribe = observer.subscribe(lambda state: print(state.data))
+"""
+
+from .cache import QueryCache
+from .client import QueryClient, QueryClientConfig
+from .convenience import CachedQuery, dependent_query, parallel_queries, query
+from .helpers import default_retry_delay, hash_key, partial_match
+from .mutation import Mutation
+from .observer import QueryObserver
+from .options import MutationOptions, QueryOptions
+from .query import Query
+from .state import (
+    FetchStatus,
+    MutationState,
+    MutationStatus,
+    QueryState,
+    QueryStatus,
+)
+from .types import QueryKey, StorageBackend
+
+__version__ = "1.0.1"
+
+__all__ = [
+    # Client
+    "QueryClient",
+    "QueryClientConfig",
+    # Query
+    "Query",
+    "QueryOptions",
+    "QueryObserver",
+    "QueryState",
+    "QueryStatus",
+    "FetchStatus",
+    # Mutation
+    "Mutation",
+    "MutationOptions",
+    "MutationState",
+    "MutationStatus",
+    # Cache
+    "QueryCache",
+    # Types
+    "QueryKey",
+    "StorageBackend",
+    # Helpers
+    "hash_key",
+    "partial_match",
+    "default_retry_delay",
+    # Convenience
+    "parallel_queries",
+    "dependent_query",
+    "query",
+    "CachedQuery",
+]

pystackquery/cache.py

@@ -0,0 +1,135 @@
+"""
+Query cache with LRU eviction.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+from typing import TYPE_CHECKING, cast
+
+from .helpers import partial_match
+from .types import QueryKey, StorageBackend
+
+if TYPE_CHECKING:
+    from .query import Query
+
+logger = logging.getLogger("pystackquery")
+
+
+class QueryCache:
+    """
+    In-memory cache (L1) for Query instances.
+
+    Optionally manages a secondary persistent storage (L2).
+
+    Features:
+        - O(1) lookup and insertion
+        - LRU eviction when max_size is reached
+        - Partial key matching for bulk invalidation
+
+    Attributes:
+        max_size: Maximum number of queries to cache in memory.
+        storage: Optional persistent storage backend.
+    """
+
+    __slots__ = ("_queries", "_max_size", "storage")
+
+    def __init__(
+        self,
+        max_size: int = 1000,
+        storage: StorageBackend | None = None,
+    ) -> None:
+        """
+        Initialize the cache.
+
+        Args:
+            max_size: Maximum number of queries to store in L1.
+            storage: Optional L2 storage backend.
+        """
+        # We store queries as object to avoid Any, but cast when retrieving
+        self._queries: OrderedDict[str, Query[object]] = OrderedDict()
+        self._max_size: int = max_size
+        self.storage: StorageBackend | None = storage
+
+    def get[T](self, key_hash: str) -> Query[T] | None:
+        """
+        Get a query from L1 by its key hash.
+
+        Moves the query to the end (most recently used).
+
+        Args:
+            key_hash: The hash of the query key.
+
+        Returns:
+            The Query if found in L1, None otherwise.
+        """
+        if key_hash in self._queries:
+            self._queries.move_to_end(key_hash)
+            return cast("Query[T]", self._queries[key_hash])
+        return None
+
+    def add[T](self, query: Query[T]) -> None:
+        """
+        Add a query to the cache.
+
+        Evicts the least recently used query if cache is full.
+
+        Args:
+            query: The Query to add.
+        """
+        if len(self._queries) >= self._max_size:
+            _, evicted = self._queries.popitem(last=False)
+            evicted.destroy()
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug("LRU eviction: %s", evicted.key)
+
+        self._queries[query.key_hash] = cast("Query[object]", query)
+
+        # Wire up GC removal callback
+        def gc_ready() -> None:
+            self.remove(query.key_hash)
+
+        query._notify_gc_ready = gc_ready
+
+    def remove(self, key_hash: str) -> None:
+        """
+        Remove a query from the cache.
+
+        Args:
+            key_hash: The hash of the query key.
+        """
+        if key_hash in self._queries:
+            query = self._queries.pop(key_hash)
+            query.destroy()
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug("Removed query %s from cache", query.key)
+
+    def find_all(self, filter_key: QueryKey | None = None) -> list[Query[object]]:
+        """
+        Find all queries matching the filter.
+
+        Args:
+            filter_key: If provided, only return queries where filter_key
+                       is a prefix of the query key. If None, return all.
+
+        Returns:
+            List of matching queries.
+        """
+        if filter_key is None:
+            return list(self._queries.values())
+        return [q for q in self._queries.values() if partial_match(filter_key, q.key)]
+
+    def clear(self) -> None:
+        """Remove all queries from the cache."""
+        for query in self._queries.values():
+            query.destroy()
+        self._queries.clear()
+
+    def __len__(self) -> int:
+        """Return the number of cached queries."""
+        return len(self._queries)
+
+    def __contains__(self, key_hash: str) -> bool:
+        """Check if a query is in the cache."""
+        return key_hash in self._queries

pystackquery/client.py

@@ -0,0 +1,219 @@
+"""
+QueryClient - Central orchestrator for state management and caching.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import cast
+
+from .cache import QueryCache
+from .helpers import default_retry_delay, hash_key
+from .mutation import Mutation
+from .observer import QueryObserver
+from .options import MutationOptions, QueryOptions
+from .query import Query
+from .state import FetchStatus, QueryState, QueryStatus
+from .types import QueryKey, RetryDelayFn, StorageBackend
+
+logger = logging.getLogger("pystackquery")
+
+
+@dataclass
+class QueryClientConfig:
+    """
+    Global defaults for the client instance. Individual queries can override these.
+    """
+    stale_time: float = 0.0
+    gc_time: float = 300.0
+    retry: int = 3
+    retry_delay: RetryDelayFn = field(default_factory=lambda: default_retry_delay)
+    cache_max_size: int = 1000
+    storage: StorageBackend | None = None
+
+
+class QueryClient:
+    """
+    Main entry point for PyStackQuery.
+    Manages the dual-tier cache (L1 memory, L2 persistent).
+    """
+
+    __slots__ = ("_config", "_cache")
+
+    def __init__(self, config: QueryClientConfig | None = None) -> None:
+        self._config: QueryClientConfig = config or QueryClientConfig()
+        self._cache: QueryCache = QueryCache(
+            max_size=self._config.cache_max_size, storage=self._config.storage
+        )
+
+    @property
+    def cache(self) -> QueryCache:
+        return self._cache
+
+    def _get_or_create_query[T](self, options: QueryOptions[T]) -> Query[T]:
+        """
+        Retrieves a query from L1 or creates it fresh.
+        If L2 storage exists, a background hydration task is kicked off immediately.
+        """
+        key_hash = options.get_key_hash()
+
+        # L1 Hit (Fastest)
+        existing: Query[T] | None = self._cache.get(key_hash)
+        if existing is not None:
+            return existing
+
+        # Cache Miss - Setup new instance and start hydration
+        query: Query[T] = self._create_query_instance(options)
+        self._cache.add(query)
+
+        if self._cache.storage:
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(query.hydrate())
+            except RuntimeError:
+                pass # Sync context or loop shutting down
+
+        return query
+
+    def _create_query_instance[T](self, options: QueryOptions[T]) -> Query[T]:
+        """Inherits client-level defaults for query instances."""
+        if options.stale_time == 0.0 and self._config.stale_time != 0.0:
+            options.stale_time = self._config.stale_time
+        if options.gc_time == 300.0 and self._config.gc_time != 300.0:
+            options.gc_time = self._config.gc_time
+        if options.retry == 3 and self._config.retry != 3:
+            options.retry = self._config.retry
+
+        return Query(options, storage=self._cache.storage)
+
+    async def fetch_query[T](self, options: QueryOptions[T]) -> T:
+        """
+        Implementation of the Stale-While-Revalidate (SWR) pattern.
+        Ensures L2 hydration is settled before checking data availability.
+        """
+        query: Query[T] = self._get_or_create_query(options)
+
+        # Ensure L2 hydration settles so we don't double-fetch cold data
+        await asyncio.sleep(0)
+        await query.wait_for_hydration()
+
+        if query.state.data is not None:
+            if not query.is_stale():
+                return query.state.data
+
+            # Data exists but is stale - return it and trigger background refresh
+            asyncio.create_task(query.fetch())
+            return query.state.data
+
+        # Cold fetch (Miss)
+        return await query.fetch()
+
+    async def prefetch_query[T](self, options: QueryOptions[T]) -> None:
+        """Warms up the cache for a key without blocking for the result."""
+        query: Query[T] = self._get_or_create_query(options)
+        await query.wait_for_hydration()
+        if query.state.data is None or query.is_stale():
+            try:
+                await query.fetch()
+            except Exception:
+                pass # Prefetches fail silently
+
+    async def get_query_data_async[T](self, key: QueryKey) -> T | None:
+        """Checks both memory and persistence for data."""
+        key_hash = hash_key(key)
+        existing: Query[object] | None = self._cache.get(key_hash)
+        if existing:
+            return cast(T, existing.state.data)
+
+        if self._cache.storage:
+            try:
+                serialized = await self._cache.storage.get(key_hash)
+                if serialized:
+                    state_dict = cast(dict[str, object], json.loads(serialized))
+                    return cast(T, state_dict.get("data"))
+            except Exception:
+                pass
+        return None
+
+    def get_query_data[T](self, key: QueryKey) -> T | None:
+        """Memory-only data retrieval."""
+        query: Query[object] | None = self._cache.get(hash_key(key))
+        return cast(T, query.state.data) if query else None
+
+    def set_query_data[T](self, key: QueryKey, data: T) -> None:
+        """Manual cache injection. Triggers persistence to L2."""
+        query: Query[object] | None = self._cache.get(hash_key(key))
+        if query:
+            query._dispatch(
+                status=QueryStatus.SUCCESS,
+                data=data,
+                data_updated_at=time.time(),
+            )
+
+    def get_query_state[
+        T, TError: Exception
+    ](self, key: QueryKey) -> QueryState[T, TError] | None:
+        query: Query[object] | None = self._cache.get(hash_key(key))
+        return cast(QueryState[T, TError], query.state) if query else None
+
+    async def invalidate_queries(
+        self,
+        filter_key: QueryKey | None = None,
+        *,
+        refetch: bool = True,
+    ) -> None:
+        """
+        Marks matching queries as stale (data_updated_at=0).
+        Active observers will trigger an immediate refetch.
+        """
+        queries = self._cache.find_all(filter_key)
+        tasks: list[asyncio.Task[object]] = []
+
+        for query in queries:
+            query._dispatch(data_updated_at=0.0) # Mark stale in L1/L2
+            if refetch and query.observer_count > 0:
+                tasks.append(asyncio.create_task(query.fetch()))
+
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    def remove_queries(self, filter_key: QueryKey | None = None) -> None:
+        """Hard removal from L1 cache."""
+        queries = self._cache.find_all(filter_key)
+        for q in queries:
+            self._cache.remove(q.key_hash)
+
+    def reset_queries(self, filter_key: QueryKey | None = None) -> None:
+        """Reverts queries to IDLE state."""
+        queries = self._cache.find_all(filter_key)
+        for q in queries:
+            q._dispatch(
+                status=QueryStatus.IDLE,
+                fetch_status=FetchStatus.IDLE,
+                data=None,
+                error=None,
+                data_updated_at=None,
+                error_updated_at=None,
+                fetch_failure_count=0,
+                fetch_failure_reason=None,
+            )
+
+    def watch[T](self, options: QueryOptions[T]) -> QueryObserver[T]:
+        """Creates a reactive observer for the given options."""
+        return QueryObserver(client=self, options=options)
+
+    def mutation[TInput, TData](
+        self,
+        options: MutationOptions[TInput, TData],
+    ) -> Mutation[TInput, TData]:
+        return Mutation(options=options, client=self)
+
+    def clear(self) -> None:
+        """Wipe memory cache."""
+        self._cache.clear()
+
+

pystackquery/convenience.py

@@ -0,0 +1,159 @@
+"""
+Convenience functions and decorators for common patterns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import cast
+
+from .client import QueryClient
+from .options import QueryOptions
+from .types import QueryKey
+
+
+async def parallel_queries(
+    client: QueryClient,
+    *options_list: QueryOptions[object],
+) -> list[object]:
+    """
+    Execute multiple queries in parallel.
+
+    All queries are fetched concurrently, and results are returned
+    in the same order as the options.
+
+    Args:
+        client: The QueryClient to use.
+        *options_list: Query configurations to execute.
+
+    Returns:
+        List of results in the same order as inputs.
+
+    Example:
+        user, posts, stats = await parallel_queries(
+            client,
+            QueryOptions(("user", uid), get_user),
+            QueryOptions(("posts", uid), get_posts),
+            QueryOptions(("stats", uid), get_stats),
+        )
+    """
+    return await asyncio.gather(*(client.fetch_query(opts) for opts in options_list))
+
+
+async def dependent_query[T](
+    client: QueryClient,
+    depends_on: QueryOptions[T],
+    then: Callable[[T], QueryOptions[object]],
+) -> object:
+    """
+    Execute a query that depends on the result of another query.
+
+    First fetches the parent query, then uses its result to construct
+    and fetch the child query.
+
+    Args:
+        client: The QueryClient to use.
+        depends_on: The parent query to fetch first.
+        then: Function that takes parent data and returns child options.
+
+    Returns:
+        The child query result.
+
+    Example:
+        posts = await dependent_query(
+            client,
+            depends_on=QueryOptions(("user", uid), get_user),
+            then=lambda user: QueryOptions(
+                ("posts", user.id),
+                lambda: get_posts(user.id)
+            ),
+        )
+    """
+    parent_data = await client.fetch_query(depends_on)
+    child_options = then(parent_data)
+    return await client.fetch_query(child_options)
+
+
+class CachedQuery[T]:
+    """
+    A cached query wrapper that provides caching utilities.
+
+    Created by the @query decorator.
+    """
+
+    __slots__ = ("_client", "_options")
+
+    def __init__(
+        self,
+        client: QueryClient,
+        options: QueryOptions[T],
+    ) -> None:
+        self._client: QueryClient = client
+        self._options: QueryOptions[T] = options
+
+    async def __call__(self) -> T:
+        """Execute the cached query."""
+        return await self._client.fetch_query(self._options)
+
+    async def invalidate(self) -> None:
+        """Invalidate the cache for this query."""
+        await self._client.invalidate_queries(self._options.query_key)
+
+    def get_data(self) -> T | None:
+        """Get the currently cached data."""
+        return cast(T, self._client.get_query_data(self._options.query_key))
+
+    @property
+    def options(self) -> QueryOptions[T]:
+        """Get the query options."""
+        return self._options
+
+
+def query[T](
+    client: QueryClient,
+    key: QueryKey,
+    *,
+    stale_time: float = 0.0,
+    gc_time: float = 300.0,
+    retry: int = 3,
+) -> Callable[[Callable[[], Awaitable[T]]], CachedQuery[T]]:
+    """
+    Decorator that wraps an async function with caching.
+
+    Provides a simple way to add caching to existing async functions.
+
+    Args:
+        client: The QueryClient to use.
+        key: The query key for caching.
+        stale_time: Seconds before data is stale (default: 0).
+        gc_time: Seconds before cache entry is collected (default: 300).
+        retry: Retry attempts on failure (default: 3).
+
+    Returns:
+        Decorator function.
+
+    Example:
+        @query(client, ("users",), stale_time=60)
+        async def get_users():
+            return await http_get("/api/users")
+
+        # Now calling get_users() goes through the cache
+        users = await get_users()
+
+        # Access utilities
+        await get_users.invalidate()  # Invalidate cache
+        get_users.get_data()          # Get cached data
+    """
+
+    def decorator(fn: Callable[[], Awaitable[T]]) -> CachedQuery[T]:
+        options = QueryOptions(
+            query_key=key,
+            query_fn=fn,
+            stale_time=stale_time,
+            gc_time=gc_time,
+            retry=retry,
+        )
+        return CachedQuery(client, options)
+
+    return decorator

pystackquery/helpers.py

@@ -0,0 +1,63 @@
+"""
+Helper utilities for PyStackQuery.
+"""
+
+from __future__ import annotations
+
+from .types import QueryKey
+
+
+def hash_key(key: QueryKey) -> str:
+    """
+    Create a string hash for a query key.
+
+    Uses simple string conversion for speed.
+    Tuples are hashable and their string representation is stable.
+
+    Args:
+        key: The query key tuple.
+
+    Returns:
+        String representation of the key for cache lookup.
+    """
+    return str(key)
+
+
+def partial_match(filter_key: QueryKey, target_key: QueryKey) -> bool:
+    """
+    Check if filter_key is a prefix of target_key.
+
+    Enables invalidating groups of related queries.
+
+    Args:
+        filter_key: The prefix to match.
+        target_key: The full key to check against.
+
+    Returns:
+        True if filter_key is a prefix of target_key.
+
+    Examples:
+        >>> partial_match(("todos",), ("todos", "active"))
+        True
+        >>> partial_match(("todos",), ("users",))
+        False
+        >>> partial_match(("todos", "active"), ("todos",))
+        False
+    """
+    if len(filter_key) > len(target_key):
+        return False
+    return target_key[: len(filter_key)] == filter_key
+
+
+def default_retry_delay(attempt: int) -> float:
+    """
+    Default exponential backoff retry delay.
+
+    Args:
+        attempt: Zero-indexed retry attempt number.
+
+    Returns:
+        Delay in seconds, capped at 30 seconds.
+    """
+    delay = 1.0 * (2**attempt)
+    return delay if delay < 30.0 else 30.0