pulse-framework 0.1.70__py3-none-any.whl → 0.1.72__py3-none-any.whl

pulse/queries/client.py

@@ -4,7 +4,7 @@ from typing import Any, TypeVar, overload
 
 from pulse.context import PulseContext
 from pulse.helpers import MISSING
-from pulse.queries.common import ActionResult, QueryKey
+from pulse.queries.common import ActionResult, Key, QueryKey, QueryKeys, normalize_key
 from pulse.queries.infinite_query import InfiniteQuery, Page
 from pulse.queries.query import KeyedQuery
 from pulse.queries.store import QueryStore
@@ -13,34 +13,32 @@ T = TypeVar("T")
 
 # Query filter types
 QueryFilter = (
-	QueryKey  # exact key match
-	| list[QueryKey]  # explicit list of keys
-	| Callable[[QueryKey], bool]  # predicate function
+	QueryKey  # exact key match (tuple or list)
+	| QueryKeys  # explicit set of keys
+	| Callable[[Key], bool]  # predicate function
 )
 
 
 def _normalize_filter(
 	filter: QueryFilter | None,
-) -> Callable[[QueryKey], bool] | None:
-	"""Convert any QueryFilter to a predicate function."""
+) -> tuple[Key | None, Callable[[Key], bool] | None]:
+	"""Return normalized exact key (if any) and a predicate for filtering."""
 	if filter is None:
-		return None
-	if isinstance(filter, tuple):
-		# Exact key match
-		exact_key = filter
-		return lambda k: k == exact_key
-	if isinstance(filter, list):
-		# List of keys
-		key_set = set(filter)
-		return lambda k: k in key_set
-	# Already a callable predicate
-	return filter
-
-
-def _prefix_filter(prefix: tuple[Any, ...]) -> Callable[[QueryKey], bool]:
+		return None, None
+	if callable(filter):
+		return None, filter
+	if isinstance(filter, QueryKeys):
+		key_set = set(filter.keys)
+		return None, lambda k: k in key_set
+	exact_key = normalize_key(filter)
+	return exact_key, lambda k: k == exact_key
+
+
+def _prefix_filter(prefix: QueryKey) -> Callable[[Key], bool]:
 	"""Create a predicate that matches keys starting with the given prefix."""
-	prefix_len = len(prefix)
-	return lambda k: len(k) >= prefix_len and k[:prefix_len] == prefix
+	normalized = normalize_key(prefix)
+	prefix_len = len(normalized)
+	return lambda k: len(k) >= prefix_len and k[:prefix_len] == normalized
 
 
 class QueryClient:
@@ -120,7 +118,7 @@ class QueryClient:
 		Get all queries matching the filter.
 
 		Args:
-			filter: Optional filter - can be an exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all queries.
 			include_infinite: Whether to include infinite queries (default True).
 
@@ -128,9 +126,16 @@ class QueryClient:
 			List of matching Query or InfiniteQuery instances.
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[KeyedQuery[Any] | InfiniteQuery[Any, Any]] = []
 
+		if exact_key is not None:
+			if include_infinite:
+				entry = store.get_any(exact_key)
+			else:
+				entry = store.get(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if predicate is not None and not predicate(key):
 				continue
@@ -144,16 +149,20 @@ class QueryClient:
 		"""Get all regular queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all regular queries.
 
 		Returns:
 			List of matching KeyedQuery instances (excludes infinite queries).
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[KeyedQuery[Any]] = []
 
+		if exact_key is not None:
+			entry = store.get(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if isinstance(entry, InfiniteQuery):
 				continue
@@ -169,16 +178,20 @@ class QueryClient:
 		"""Get all infinite queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, returns all infinite queries.
 
 		Returns:
 			List of matching InfiniteQuery instances.
 		"""
 		store = self._get_store()
-		predicate = _normalize_filter(filter)
+		exact_key, predicate = _normalize_filter(filter)
 		results: list[InfiniteQuery[Any, Any]] = []
 
+		if exact_key is not None:
+			entry = store.get_infinite(exact_key)
+			return [entry] if entry is not None else []
+
 		for key, entry in store.items():
 			if not isinstance(entry, InfiniteQuery):
 				continue
@@ -239,7 +252,7 @@ class QueryClient:
 	@overload
 	def set_data(
 		self,
-		key_or_filter: list[QueryKey] | Callable[[QueryKey], bool],
+		key_or_filter: QueryKeys | Callable[[Key], bool],
 		data: Callable[[Any], Any],
 		*,
 		updated_at: float | dt.datetime | None = None,
@@ -247,7 +260,7 @@ class QueryClient:
 
 	def set_data(
 		self,
-		key_or_filter: QueryKey | list[QueryKey] | Callable[[QueryKey], bool],
+		key_or_filter: QueryKey | QueryKeys | Callable[[Key], bool],
 		data: Any | Callable[[Any], Any],
 		*,
 		updated_at: float | dt.datetime | None = None,
@@ -266,16 +279,15 @@ class QueryClient:
 		Returns:
 			bool if exact key, int count if filter.
 		"""
-		# Single key case
-		if isinstance(key_or_filter, tuple):
-			query = self.get(key_or_filter)
+		exact_key, predicate = _normalize_filter(key_or_filter)
+		if exact_key is not None:
+			query = self.get(exact_key)
 			if query is None:
 				return False
 			query.set_data(data, updated_at=updated_at)
 			return True
 
-		# Filter case
-		queries = self.get_queries(key_or_filter)
+		queries = self.get_queries(predicate)
 		for q in queries:
 			q.set_data(data, updated_at=updated_at)
 		return len(queries)
@@ -319,17 +331,14 @@ class QueryClient:
 	@overload
 	def invalidate(
 		self,
-		key_or_filter: list[QueryKey] | Callable[[QueryKey], bool] | None = None,
+		key_or_filter: QueryKeys | Callable[[Key], bool] | None = None,
 		*,
 		cancel_refetch: bool = False,
 	) -> int: ...
 
 	def invalidate(
 		self,
-		key_or_filter: QueryKey
-		| list[QueryKey]
-		| Callable[[QueryKey], bool]
-		| None = None,
+		key_or_filter: QueryKey | QueryKeys | Callable[[Key], bool] | None = None,
 		*,
 		cancel_refetch: bool = False,
 	) -> bool | int:
@@ -346,20 +355,19 @@ class QueryClient:
 		Returns:
 			bool if exact key, int count if filter/None.
 		"""
-		# Single key case
-		if isinstance(key_or_filter, tuple):
-			query = self.get(key_or_filter)
+		exact_key, predicate = _normalize_filter(key_or_filter)
+		if exact_key is not None:
+			query = self.get(exact_key)
 			if query is not None:
 				query.invalidate(cancel_refetch=cancel_refetch)
 				return True
-			inf_query = self.get_infinite(key_or_filter)
+			inf_query = self.get_infinite(exact_key)
 			if inf_query is not None:
 				inf_query.invalidate(cancel_fetch=cancel_refetch)
 				return True
 			return False
 
-		# Filter case
-		queries = self.get_all(key_or_filter)
+		queries = self.get_all(predicate)
 		for q in queries:
 			if isinstance(q, InfiniteQuery):
 				q.invalidate(cancel_fetch=cancel_refetch)
@@ -369,14 +377,14 @@ class QueryClient:
 
 	def invalidate_prefix(
 		self,
-		prefix: tuple[Any, ...],
+		prefix: QueryKey,
 		*,
 		cancel_refetch: bool = False,
 	) -> int:
 		"""Invalidate all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 			cancel_refetch: Cancel in-flight requests before refetch.
 
 		Returns:
@@ -429,7 +437,7 @@ class QueryClient:
 		"""Refetch all queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, refetches all queries.
 			cancel_refetch: Cancel in-flight requests before refetching.
 
@@ -450,14 +458,14 @@ class QueryClient:
 
 	async def refetch_prefix(
 		self,
-		prefix: tuple[Any, ...],
+		prefix: QueryKey,
 		*,
 		cancel_refetch: bool = True,
 	) -> list[ActionResult[Any]]:
 		"""Refetch all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 			cancel_refetch: Cancel in-flight requests before refetching.
 
 		Returns:
@@ -524,7 +532,7 @@ class QueryClient:
 		"""Remove all queries matching the filter.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, removes all queries.
 
 		Returns:
@@ -535,11 +543,11 @@ class QueryClient:
 			q.dispose()
 		return len(queries)
 
-	def remove_prefix(self, prefix: tuple[Any, ...]) -> int:
+	def remove_prefix(self, prefix: QueryKey) -> int:
 		"""Remove all queries whose keys start with the given prefix.
 
 		Args:
-			prefix: Tuple prefix to match against query keys.
+			prefix: Key prefix to match against query keys.
 
 		Returns:
 			Count of removed queries.
@@ -554,7 +562,7 @@ class QueryClient:
 		"""Check if any query matching the filter is currently fetching.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, checks all queries.
 
 		Returns:
@@ -570,7 +578,7 @@ class QueryClient:
 		"""Check if any query matching the filter is in loading state.
 
 		Args:
-			filter: Optional filter - exact key, list of keys, or predicate.
+			filter: Optional filter - exact key, QueryKeys, or predicate.
 				If None, checks all queries.
 
 		Returns:

pulse/queries/common.py

@@ -9,6 +9,8 @@ from typing import (
 	ParamSpec,
 	TypeAlias,
 	TypeVar,
+	final,
+	override,
 )
 
 from pulse.state import State
@@ -18,13 +20,74 @@ TState = TypeVar("TState", bound="State")
 P = ParamSpec("P")
 R = TypeVar("R")
 
-QueryKey: TypeAlias = tuple[Hashable, ...]
-"""Tuple of hashable values identifying a query in the store.
+
+@final
+class Key(tuple[Hashable, ...]):
+	"""Normalized query key with a precomputed hash."""
+
+	_hash: int = 0
+
+	def __new__(cls, key: "QueryKey"):
+		if isinstance(key, Key):
+			return key
+		if isinstance(key, (list, tuple)):
+			parts = tuple(key)
+			try:
+				key_hash = hash(parts)
+			except TypeError as e:
+				raise TypeError(
+					f"Query key contains unhashable value: {e}.\n\n"
+					+ "Keys must contain only hashable values (strings, numbers, tuples).\n"
+					+ f"Got: {key!r}\n\n"
+					+ "If using a dict or list inside the key, convert it to a tuple:\n"
+					+ "    key=('users', tuple(user_ids))  # instead of list"
+				) from None
+			obj = super().__new__(cls, parts)
+			obj._hash = key_hash
+			return obj
+		raise TypeError(
+			f"Query key must be a tuple or list, got {type(key).__name__}: {key!r}\n\n"
+			+ "Examples of valid keys:\n"
+			+ "    key=('users',)           # single-element tuple\n"
+			+ "    key=('user', user_id)    # tuple with dynamic value\n"
+			+ "    key=['posts', 'feed']    # list form also works"
+		)
+
+	@override
+	def __hash__(self) -> int:
+		return self._hash
+
+
+QueryKey: TypeAlias = tuple[Hashable, ...] | list[Hashable] | Key  # pyright: ignore[reportImplicitStringConcatenation]
+"""List/tuple of hashable values identifying a query in the store.
 
 Used to uniquely identify queries for caching, deduplication, and invalidation.
-Keys are hierarchical tuples like ``("user", user_id)`` or ``("posts", "feed")``.
+Keys are hierarchical lists/tuples like ``("user", user_id)`` or ``["posts", "feed"]``.
+Lists are normalized to a tuple-backed Key internally.
 """
 
+
+def normalize_key(key: QueryKey) -> Key:
+	"""Convert a query key to a normalized key for use as a dict key."""
+	return Key(key)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class QueryKeys:
+	"""Wrapper for selecting multiple query keys."""
+
+	keys: tuple[Key, ...]
+
+	def __init__(self, *keys: QueryKey):
+		object.__setattr__(self, "keys", tuple(normalize_key(key) for key in keys))
+
+
+def keys(*query_keys: QueryKey) -> QueryKeys:
+	"""Create a QueryKeys wrapper for filtering by multiple keys."""
+	return QueryKeys(*query_keys)
+
+
 QueryStatus: TypeAlias = Literal["loading", "success", "error"]
 """Current status of a query.
 

pulse/queries/infinite_query.py

@@ -27,11 +27,13 @@ from pulse.queries.common import (
 	ActionError,
 	ActionResult,
 	ActionSuccess,
+	Key,
 	OnErrorFn,
 	OnSuccessFn,
 	QueryKey,
 	QueryStatus,
 	bind_state,
+	normalize_key,
 )
 from pulse.queries.query import RETRY_DELAY_DEFAULT, QueryConfig
 from pulse.reactive import Computed, Effect, Signal, Untrack
@@ -115,6 +117,7 @@ class RefetchPage(Generic[T, TParam]):
 	fetch_fn: Callable[[TParam], Awaitable[T]]
 	param: TParam
 	observer: "InfiniteQueryResult[T, TParam] | None" = None
+	clear: bool = False
 	future: "asyncio.Future[ActionResult[T | None]]" = field(
 		default_factory=asyncio.Future
 	)
@@ -141,7 +144,7 @@ class InfiniteQueryConfig(QueryConfig[list[Page[T, TParam]]], Generic[T, TParam]
 class InfiniteQuery(Generic[T, TParam], Disposable):
 	"""Paginated query that stores data as a list of Page(data, param)."""
 
-	key: QueryKey
+	key: Key
 	cfg: InfiniteQueryConfig[T, TParam]
 
 	@property
@@ -248,7 +251,7 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		gc_time: float = 300.0,
 		on_dispose: Callable[[Any], None] | None = None,
 	):
-		self.key = key
+		self.key = normalize_key(key)
 
 		self.cfg = InfiniteQueryConfig(
 			retries=retries,
@@ -305,7 +308,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		for obs in self._observers:
 			if obs._on_success is not None:  # pyright: ignore[reportPrivateUsage]
-				await maybe_await(call_flexible(obs._on_success, self.pages))  # pyright: ignore[reportPrivateUsage]
+				with Untrack():
+					await maybe_await(call_flexible(obs._on_success, self.pages))  # pyright: ignore[reportPrivateUsage]
 
 	async def _commit_error(self, error: Exception):
 		"""Commit error state and run error callbacks."""
@@ -313,7 +317,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		for obs in self._observers:
 			if obs._on_error is not None:  # pyright: ignore[reportPrivateUsage]
-				await maybe_await(call_flexible(obs._on_error, error))  # pyright: ignore[reportPrivateUsage]
+				with Untrack():
+					await maybe_await(call_flexible(obs._on_error, error))  # pyright: ignore[reportPrivateUsage]
 
 	def _commit_sync(self):
 		"""Synchronous commit - updates state based on current pages."""
@@ -427,7 +432,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		self._cancel_observer_actions(observer)
 
 		if len(self._observers) == 0:
-			self.schedule_gc()
+			if not self.__disposed__:
+				self.schedule_gc()
 
 	def invalidate(
 		self,
@@ -703,8 +709,8 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 
 		page = await action.fetch_fn(action.param)
 
-		if idx is None:
-			# Page doesn't exist - jump to this page, clearing existing pages
+		if action.clear or idx is None:
+			# clear=True or page doesn't exist - replace all pages with just this one
 			self.pages.clear()
 			self.pages.append(Page(page, action.param))
 		else:
@@ -782,12 +788,13 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		*,
 		observer: "InfiniteQueryResult[T, TParam] | None" = None,
 		cancel_fetch: bool = False,
+		clear: bool = False,
 	) -> ActionResult[T | None]:
 		"""
 		Refetch a page by its param. Queued for sequential execution.
 
-		If the page doesn't exist, clears existing pages and loads the requested
-		page as the new starting point.
+		If the page doesn't exist or clear=True, clears existing pages and loads
+		the requested page as the new starting point.
 
 		Note: Prefer calling refetch_page() on InfiniteQueryResult to ensure the
 		correct fetch function is used. When called directly on InfiniteQuery, uses
@@ -795,7 +802,7 @@ class InfiniteQuery(Generic[T, TParam], Disposable):
 		"""
 		fn = fetch_fn if fetch_fn is not None else self.fn
 		action: RefetchPage[T, TParam] = RefetchPage(
-			fetch_fn=fn, param=param, observer=observer
+			fetch_fn=fn, param=param, observer=observer, clear=clear
 		)
 		return await self._enqueue(action, cancel_fetch=cancel_fetch)
 
@@ -1019,12 +1026,22 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 		page_param: TParam,
 		*,
 		cancel_fetch: bool = False,
+		clear: bool = False,
 	) -> ActionResult[T | None]:
+		"""Fetch a specific page by its param.
+
+		Args:
+			page_param: The page parameter to fetch.
+			cancel_fetch: Cancel any in-flight fetches before starting.
+			clear: If True, clears all other pages and keeps only the fetched page.
+				Useful for resetting pagination to a specific page.
+		"""
 		return await self._query().refetch_page(
 			page_param,
 			fetch_fn=self._fetch_fn,
 			observer=self,
 			cancel_fetch=cancel_fetch,
+			clear=clear,
 		)
 
 	def set_initial_data(
@@ -1149,7 +1166,7 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		Callable[[TState, list[Page[T, TParam]]], TParam | None] | None
 	)
 	_max_pages: int
-	_key: QueryKey | Callable[[TState], QueryKey] | None
+	_key: Key | Callable[[TState], Key] | None
 	# Not using OnSuccessFn and OnErrorFn since unions of callables are not well
 	# supported in the type system. We just need to be careful to use
 	# call_flexible to invoke these functions.
@@ -1193,7 +1210,17 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		self._on_success_fn = None
 		self._on_error_fn = None
 		self._initial_data = MISSING
-		self._key = key
+		if key is None:
+			self._key = None
+		elif callable(key):
+			key_fn = key
+
+			def normalized_key(state: TState) -> Key:
+				return normalize_key(key_fn(state))
+
+			self._key = normalized_key
+		else:
+			self._key = normalize_key(key)
 		self._initial_data_updated_at = initial_data_updated_at
 		self._enabled = enabled
 		self._fetch_on_mount = fetch_on_mount
@@ -1204,7 +1231,11 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 			raise RuntimeError(
 				f"Cannot use @{self.name}.key decorator when a key is already provided to @infinite_query(key=...)."
 			)
-		self._key = fn
+
+		def normalized_key(state: TState) -> Key:
+			return normalize_key(fn(state))
+
+		self._key = normalized_key
 		return fn
 
 	def on_success(self, fn: OnSuccessFn[TState, list[T]]):
@@ -1278,8 +1309,17 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 		)
 
 		if self._key is None:
+			# pyright: ignore[reportImplicitStringConcatenation]
 			raise RuntimeError(
-				f"key is required for infinite query '{self.name}'. Provide a key via @infinite_query(key=...) or @{self.name}.key decorator."
+				f"Missing query key for @infinite_query '{self.name}'. "
+				+ "A key is required to cache and share query results.\n\n"
+				+ f"Fix: Add key=(...) to the decorator or use the @{self.name}.key decorator:\n\n"
+				+ "    @ps.infinite_query(initial_page_param=..., key=('my_query',))\n"
+				+ f"    async def {self.name}(self, param): ...\n\n"
+				+ "Or with a dynamic key:\n\n"
+				+ f"    @{self.name}.key\n"
+				+ f"    def _{self.name}_key(self):\n"
+				+ "        return ('my_query', self.some_param)"
 			)
 		raw_initial = (
 			call_flexible(self._initial_data, state)
@@ -1384,6 +1424,7 @@ class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
 def infinite_query(
 	fn: Callable[[TState, TParam], Awaitable[T]],
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1395,7 +1436,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> InfiniteQueryProperty[T, TParam, TState]: ...
 
 
@@ -1403,6 +1443,7 @@ def infinite_query(
 def infinite_query(
 	fn: None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1414,7 +1455,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> Callable[
 	[Callable[[TState, Any], Awaitable[T]]],
 	InfiniteQueryProperty[T, TParam, TState],
@@ -1424,6 +1464,7 @@ def infinite_query(
 def infinite_query(
 	fn: Callable[[TState, TParam], Awaitable[T]] | None = None,
 	*,
+	key: QueryKey | Callable[[TState], QueryKey] | None = None,
 	initial_page_param: TParam,
 	max_pages: int = 0,
 	stale_time: float = 0.0,
@@ -1435,7 +1476,6 @@ def infinite_query(
 	initial_data_updated_at: float | dt.datetime | None = None,
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
-	key: QueryKey | None = None,
 ) -> (
 	InfiniteQueryProperty[T, TParam, TState]
 	| Callable[
@@ -1449,7 +1489,8 @@ def infinite_query(
 	pagination. Data is stored as a list of pages, each with its data and the
 	parameter used to fetch it.
 
-	Requires ``@query_prop.key`` and ``@query_prop.get_next_page_param`` decorators.
+	Requires a key (``key=`` or ``@query_prop.key``) and
+	``@query_prop.get_next_page_param`` decorator.
 
 	Args:
 		fn: The async method to decorate (when used without parentheses).