pulse-framework 0.1.54__py3-none-any.whl → 0.1.56__py3-none-any.whl

pulse/queries/client.py

@@ -6,6 +6,7 @@ from pulse.context import PulseContext
 from pulse.queries.common import ActionResult, QueryKey
 from pulse.queries.infinite_query import InfiniteQuery, Page
 from pulse.queries.query import KeyedQuery
+from pulse.queries.store import QueryStore
 
 T = TypeVar("T")
 
@@ -42,17 +43,41 @@ def _prefix_filter(prefix: tuple[Any, ...]) -> Callable[[QueryKey], bool]:
 
 
 class QueryClient:
-	"""
-	Client for managing queries and infinite queries in a session.
+	"""Client for managing queries and infinite queries in a session.
 
 	Provides methods to get, set, invalidate, and refetch queries by key
-	or using filter predicates.
+	or using filter predicates. Automatically resolves to the current
+	RenderSession's query store.
+
+	Access via ``ps.queries`` singleton:
+
+	Example:
+
+	```python
+	# Get query data
+	user = ps.queries.get_data(("user", user_id))
 
-	Automatically resolves to the current RenderSession's query store.
+	# Invalidate queries by prefix
+	ps.queries.invalidate_prefix(("users",))
+
+	# Set data optimistically
+	ps.queries.set_data(("user", user_id), updated_user)
+
+	# Check if any query is fetching
+	if ps.queries.is_fetching(("user", user_id)):
+	    show_loading()
+	```
 	"""
 
-	def _get_store(self):
-		"""Get the query store from the current PulseContext."""
+	def _get_store(self) -> QueryStore:
+		"""Get the query store from the current PulseContext.
+
+		Returns:
+			The QueryStore from the active render session.
+
+		Raises:
+			RuntimeError: If no render session is available.
+		"""
 		render = PulseContext.get().render
 		if render is None:
 			raise RuntimeError("No render session available")
@@ -62,12 +87,26 @@ class QueryClient:
 	# Query accessors
 	# ─────────────────────────────────────────────────────────────────────────
 
-	def get(self, key: QueryKey):
-		"""Get an existing regular query by key, or None if not found."""
+	def get(self, key: QueryKey) -> KeyedQuery[Any] | None:
+		"""Get an existing regular query by key.
+
+		Args:
+			key: The query key tuple to look up.
+
+		Returns:
+			The KeyedQuery instance, or None if not found.
+		"""
 		return self._get_store().get(key)
 
-	def get_infinite(self, key: QueryKey):
-		"""Get an existing infinite query by key, or None if not found."""
+	def get_infinite(self, key: QueryKey) -> InfiniteQuery[Any, Any] | None:
+		"""Get an existing infinite query by key.
+
+		Args:
+			key: The query key tuple to look up.
+
+		Returns:
+			The InfiniteQuery instance, or None if not found.
+		"""
 		return self._get_store().get_infinite(key)
 
 	def get_all(
@@ -101,7 +140,15 @@ class QueryClient:
 		return results
 
 	def get_queries(self, filter: QueryFilter | None = None) -> list[KeyedQuery[Any]]:
-		"""Get all regular queries matching the filter."""
+		"""Get all regular queries matching the filter.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, 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)
 		results: list[KeyedQuery[Any]] = []
@@ -118,7 +165,15 @@ class QueryClient:
 	def get_infinite_queries(
 		self, filter: QueryFilter | None = None
 	) -> list[InfiniteQuery[Any, Any]]:
-		"""Get all infinite queries matching the filter."""
+		"""Get all infinite queries matching the filter.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, or predicate.
+				If None, returns all infinite queries.
+
+		Returns:
+			List of matching InfiniteQuery instances.
+		"""
 		store = self._get_store()
 		predicate = _normalize_filter(filter)
 		results: list[InfiniteQuery[Any, Any]] = []
@@ -137,14 +192,28 @@ class QueryClient:
 	# ─────────────────────────────────────────────────────────────────────────
 
 	def get_data(self, key: QueryKey) -> Any | None:
-		"""Get the data for a query by key. Returns None if not found or no data."""
+		"""Get the data for a query by key.
+
+		Args:
+			key: The query key tuple to look up.
+
+		Returns:
+			The query data, or None if query not found or has no data.
+		"""
 		query = self.get(key)
 		if query is None:
 			return None
 		return query.data.read()
 
 	def get_infinite_data(self, key: QueryKey) -> list[Page[Any, Any]] | None:
-		"""Get the pages for an infinite query by key."""
+		"""Get the pages for an infinite query by key.
+
+		Args:
+			key: The query key tuple to look up.
+
+		Returns:
+			List of Page objects, or None if query not found.
+		"""
 		query = self.get_infinite(key)
 		if query is None:
 			return None
@@ -215,7 +284,16 @@ class QueryClient:
 		*,
 		updated_at: float | dt.datetime | None = None,
 	) -> bool:
-		"""Set pages for an infinite query by key."""
+		"""Set pages for an infinite query by key.
+
+		Args:
+			key: The query key tuple.
+			pages: New pages list or updater function.
+			updated_at: Optional timestamp to set.
+
+		Returns:
+			True if query was found and updated, False otherwise.
+		"""
 		query = self.get_infinite(key)
 		if query is None:
 			return False
@@ -291,11 +369,21 @@ class QueryClient:
 		*,
 		cancel_refetch: bool = False,
 	) -> int:
-		"""
-		Invalidate all queries whose keys start with the given prefix.
+		"""Invalidate all queries whose keys start with the given prefix.
+
+		Args:
+			prefix: Tuple prefix to match against query keys.
+			cancel_refetch: Cancel in-flight requests before refetch.
+
+		Returns:
+			Count of invalidated queries.
 
 		Example:
-			ps.queries.invalidate_prefix(("users",))  # invalidates ("users",), ("users", 1), etc.
+
+		```python
+		# Invalidates ("users",), ("users", 1), ("users", 2, "posts"), etc.
+		ps.queries.invalidate_prefix(("users",))
+		```
 		"""
 		return self.invalidate(_prefix_filter(prefix), cancel_refetch=cancel_refetch)
 
@@ -309,10 +397,14 @@ class QueryClient:
 		*,
 		cancel_refetch: bool = True,
 	) -> ActionResult[Any] | None:
-		"""
-		Refetch a query by key and return the result.
+		"""Refetch a query by key and return the result.
 
-		Returns None if the query doesn't exist.
+		Args:
+			key: The query key tuple to refetch.
+			cancel_refetch: Cancel in-flight request before refetching (default True).
+
+		Returns:
+			ActionResult with data or error, or None if query doesn't exist.
 		"""
 		query = self.get(key)
 		if query is not None:
@@ -330,10 +422,15 @@ class QueryClient:
 		*,
 		cancel_refetch: bool = True,
 	) -> list[ActionResult[Any]]:
-		"""
-		Refetch all queries matching the filter.
+		"""Refetch all queries matching the filter.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, or predicate.
+				If None, refetches all queries.
+			cancel_refetch: Cancel in-flight requests before refetching.
 
-		Returns list of ActionResult for each refetched query.
+		Returns:
+			List of ActionResult for each refetched query.
 		"""
 		queries = self.get_all(filter)
 		results: list[ActionResult[Any]] = []
@@ -353,7 +450,15 @@ class QueryClient:
 		*,
 		cancel_refetch: bool = True,
 	) -> list[ActionResult[Any]]:
-		"""Refetch all queries whose keys start with the given prefix."""
+		"""Refetch all queries whose keys start with the given prefix.
+
+		Args:
+			prefix: Tuple prefix to match against query keys.
+			cancel_refetch: Cancel in-flight requests before refetching.
+
+		Returns:
+			List of ActionResult for each refetched query.
+		"""
 		return await self.refetch_all(
 			_prefix_filter(prefix), cancel_refetch=cancel_refetch
 		)
@@ -369,7 +474,16 @@ class QueryClient:
 		*,
 		updated_at: float | dt.datetime | None = None,
 	) -> bool:
-		"""Set error state on a query by key."""
+		"""Set error state on a query by key.
+
+		Args:
+			key: The query key tuple.
+			error: The exception to set.
+			updated_at: Optional timestamp to set.
+
+		Returns:
+			True if query was found and error was set, False otherwise.
+		"""
 		query = self.get(key)
 		if query is not None:
 			query.set_error(error, updated_at=updated_at)
@@ -387,10 +501,13 @@ class QueryClient:
 	# ─────────────────────────────────────────────────────────────────────────
 
 	def remove(self, key: QueryKey) -> bool:
-		"""
-		Remove a query from the store, disposing it.
+		"""Remove a query from the store, disposing it.
+
+		Args:
+			key: The query key tuple to remove.
 
-		Returns True if query existed and was removed.
+		Returns:
+			True if query existed and was removed, False otherwise.
 		"""
 		store = self._get_store()
 		entry = store.get_any(key)
@@ -400,10 +517,14 @@ class QueryClient:
 		return True
 
 	def remove_all(self, filter: QueryFilter | None = None) -> int:
-		"""
-		Remove all queries matching the filter.
+		"""Remove all queries matching the filter.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, or predicate.
+				If None, removes all queries.
 
-		Returns count of removed queries.
+		Returns:
+			Count of removed queries.
 		"""
 		queries = self.get_all(filter)
 		for q in queries:
@@ -411,7 +532,14 @@ class QueryClient:
 		return len(queries)
 
 	def remove_prefix(self, prefix: tuple[Any, ...]) -> int:
-		"""Remove all queries whose keys start with the given prefix."""
+		"""Remove all queries whose keys start with the given prefix.
+
+		Args:
+			prefix: Tuple prefix to match against query keys.
+
+		Returns:
+			Count of removed queries.
+		"""
 		return self.remove_all(_prefix_filter(prefix))
 
 	# ─────────────────────────────────────────────────────────────────────────
@@ -419,7 +547,15 @@ class QueryClient:
 	# ─────────────────────────────────────────────────────────────────────────
 
 	def is_fetching(self, filter: QueryFilter | None = None) -> bool:
-		"""Check if any query matching the filter is currently fetching."""
+		"""Check if any query matching the filter is currently fetching.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, or predicate.
+				If None, checks all queries.
+
+		Returns:
+			True if any matching query is fetching.
+		"""
 		queries = self.get_all(filter)
 		for q in queries:
 			if q.is_fetching():
@@ -427,7 +563,15 @@ class QueryClient:
 		return False
 
 	def is_loading(self, filter: QueryFilter | None = None) -> bool:
-		"""Check if any query matching the filter is in loading state."""
+		"""Check if any query matching the filter is in loading state.
+
+		Args:
+			filter: Optional filter - exact key, list of keys, or predicate.
+				If None, checks all queries.
+
+		Returns:
+			True if any matching query has status "loading".
+		"""
 		queries = self.get_all(filter)
 		for q in queries:
 			if isinstance(q, InfiniteQuery):
@@ -442,10 +586,13 @@ class QueryClient:
 	# ─────────────────────────────────────────────────────────────────────────
 
 	async def wait(self, key: QueryKey) -> ActionResult[Any] | None:
-		"""
-		Wait for a query to complete and return the result.
+		"""Wait for a query to complete and return the result.
 
-		Returns None if the query doesn't exist.
+		Args:
+			key: The query key tuple to wait for.
+
+		Returns:
+			ActionResult with data or error, or None if query doesn't exist.
 		"""
 		query = self.get(key)
 		if query is not None:
@@ -458,5 +605,5 @@ class QueryClient:
 		return None
 
 
-# Singleton instance
+# Singleton instance accessible via ps.queries
 queries = QueryClient()

pulse/queries/common.py

@@ -19,13 +19,41 @@ P = ParamSpec("P")
 R = TypeVar("R")
 
 QueryKey: TypeAlias = tuple[Hashable, ...]
+"""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")``.
+"""
+
 QueryStatus: TypeAlias = Literal["loading", "success", "error"]
+"""Current status of a query.
+
+Values:
+    - ``"loading"``: Query is fetching data (initial load or refetch).
+    - ``"success"``: Query has successfully fetched data.
+    - ``"error"``: Query encountered an error during fetch.
+"""
 
 
-# Discriminated union result types for query actions
 @dataclass(slots=True, frozen=True)
 class ActionSuccess(Generic[T]):
-	"""Successful query action result."""
+	"""Successful query action result.
+
+	Returned by query operations like ``refetch()`` and ``wait()`` when the
+	operation completes successfully.
+
+	Attributes:
+		data: The fetched data of type T.
+		status: Always ``"success"`` for discriminated union matching.
+
+	Example:
+
+	```python
+	result = await state.user.refetch()
+	if result.status == "success":
+	    print(result.data)
+	```
+	"""
 
 	data: T
 	status: Literal["success"] = "success"
@@ -33,13 +61,34 @@ class ActionSuccess(Generic[T]):
 
 @dataclass(slots=True, frozen=True)
 class ActionError:
-	"""Failed query action result."""
+	"""Failed query action result.
+
+	Returned by query operations like ``refetch()`` and ``wait()`` when the
+	operation fails after exhausting retries.
+
+	Attributes:
+		error: The exception that caused the failure.
+		status: Always ``"error"`` for discriminated union matching.
+
+	Example:
+
+	```python
+	result = await state.user.refetch()
+	if result.status == "error":
+	    print(f"Failed: {result.error}")
+	```
+	"""
 
 	error: Exception
 	status: Literal["error"] = "error"
 
 
 ActionResult: TypeAlias = ActionSuccess[T] | ActionError
+"""Union type for query action results.
+
+Either ``ActionSuccess[T]`` with data or ``ActionError`` with an exception.
+Use the ``status`` field to discriminate between success and error cases.
+"""
 
 OnSuccessFn = Callable[[TState], Any] | Callable[[TState, T], Any]
 OnErrorFn = Callable[[TState], Any] | Callable[[TState, Exception], Any]

pulse/queries/infinite_query.py

@@ -44,6 +44,26 @@ TState = TypeVar("TState", bound=State)
 
 
 class Page(NamedTuple, Generic[T, TParam]):
+	"""Named tuple representing a page in an infinite query.
+
+	Each page contains the fetched data and the parameter used to fetch it,
+	enabling cursor-based or offset-based pagination.
+
+	Attributes:
+		data: The fetched page data of type T.
+		param: The page parameter (cursor, offset, etc.) used to fetch this page.
+
+	Example:
+
+	```python
+	# Access pages from infinite query result
+	for page in state.posts.data:
+	    print(f"Page param: {page.param}")
+	    for post in page.data:
+	        print(post.title)
+	```
+	"""
+
 	data: T
 	param: TParam
 
@@ -714,8 +734,39 @@ def none_if_missing(value: Any):
 
 
 class InfiniteQueryResult(Generic[T, TParam], Disposable):
-	"""
-	Observer wrapper for InfiniteQuery with lifecycle and stale tracking.
+	"""Observer wrapper for InfiniteQuery with lifecycle and stale tracking.
+
+	InfiniteQueryResult provides the interface for interacting with paginated
+	queries. It manages observation lifecycle, staleness tracking, and exposes
+	reactive properties and methods for pagination.
+
+	Attributes:
+		data: List of Page objects or None if not loaded.
+		pages: List of page data only (without params) or None.
+		page_params: List of page parameters only or None.
+		error: The last error encountered, or None.
+		status: Current QueryStatus ("loading", "success", "error").
+		is_loading: Whether status is "loading".
+		is_success: Whether status is "success".
+		is_error: Whether status is "error".
+		is_fetching: Whether any fetch is in progress.
+		has_next_page: Whether more pages are available forward.
+		has_previous_page: Whether previous pages are available.
+		is_fetching_next_page: Whether fetching the next page.
+		is_fetching_previous_page: Whether fetching the previous page.
+
+	Example:
+
+	```python
+	# Access infinite query result
+	if state.posts.is_loading:
+	    show_skeleton()
+	elif state.posts.data:
+	    for page in state.posts.data:
+	        render_posts(page.data)
+	    if state.posts.has_next_page:
+	        Button("Load More", on_click=state.posts.fetch_next_page)
+	```
 	"""
 
 	_query: Computed[InfiniteQuery[T, TParam]]
@@ -957,6 +1008,47 @@ class InfiniteQueryResult(Generic[T, TParam], Disposable):
 
 
 class InfiniteQueryProperty(Generic[T, TParam, TState], InitializableProperty):
+	"""Descriptor for state-bound infinite queries created by the @infinite_query decorator.
+
+	InfiniteQueryProperty is the return type of the ``@infinite_query`` decorator.
+	It acts as a descriptor that creates and manages InfiniteQueryResult instances
+	for each State object.
+
+	When accessed on a State instance, returns an InfiniteQueryResult with reactive
+	properties for pagination state and methods for fetching pages.
+
+	Required decorators:
+		- ``@infinite_query_prop.key``: Define the query key (required).
+		- ``@infinite_query_prop.get_next_page_param``: Define how to get next page param.
+
+	Optional decorators:
+		- ``@infinite_query_prop.get_previous_page_param``: For bi-directional pagination.
+		- ``@infinite_query_prop.on_success``: Handle successful fetch.
+		- ``@infinite_query_prop.on_error``: Handle fetch errors.
+
+	Example:
+
+	```python
+	class FeedState(ps.State):
+	    feed_type: str = "home"
+
+	    @ps.infinite_query(initial_page_param=None)
+	    async def posts(self, cursor: str | None) -> list[Post]:
+	        return await api.get_posts(cursor=cursor)
+
+	    @posts.key
+	    def _posts_key(self):
+	        return ("feed", self.feed_type)
+
+	    @posts.get_next_page_param
+	    def _next_cursor(self, pages: list[Page]) -> str | None:
+	        if not pages:
+	            return None
+	        last = pages[-1]
+	        return last.data[-1].id if last.data else None
+	```
+	"""
+
 	name: str
 	_fetch_fn: "Callable[[TState, TParam], Awaitable[T]]"
 	_keep_alive: bool
@@ -1233,7 +1325,67 @@ def infinite_query(
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
 	key: QueryKey | None = None,
+) -> (
+	InfiniteQueryProperty[T, TParam, TState]
+	| Callable[
+		[Callable[[TState, Any], Awaitable[T]]],
+		InfiniteQueryProperty[T, TParam, TState],
+	]
 ):
+	"""Decorator for paginated queries on State methods.
+
+	Creates a reactive infinite query that supports cursor-based or offset-based
+	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.
+
+	Args:
+		fn: The async method to decorate (when used without parentheses).
+		initial_page_param: The parameter for fetching the first page (required).
+		max_pages: Maximum pages to keep in memory (0 = unlimited).
+		stale_time: Seconds before data is considered stale (default 0.0).
+		gc_time: Seconds to keep unused query in cache (default 300.0).
+		refetch_interval: Auto-refetch interval in seconds (default None).
+		keep_previous_data: Keep previous data while refetching (default False).
+		retries: Number of retry attempts on failure (default 3).
+		retry_delay: Delay between retries in seconds (default 2.0).
+		initial_data_updated_at: Timestamp for initial data staleness.
+		enabled: Whether query is enabled (default True).
+		fetch_on_mount: Fetch when component mounts (default True).
+		key: Static query key for sharing across instances.
+
+	Returns:
+		InfiniteQueryProperty that creates InfiniteQueryResult instances when accessed.
+
+	Example:
+
+	```python
+	class FeedState(ps.State):
+	    @ps.infinite_query(initial_page_param=None, key=("feed",))
+	    async def posts(self, cursor: str | None) -> list[Post]:
+	        return await api.get_posts(cursor=cursor)
+
+	    @posts.key
+	    def _posts_key(self):
+	        return ("feed", self.feed_type)
+
+	    @posts.get_next_page_param
+	    def _next_cursor(self, pages: list[Page]) -> str | None:
+	        if not pages:
+	            return None
+	        last = pages[-1]
+	        return last.data[-1].id if last.data else None
+
+	    @posts.get_previous_page_param
+	    def _prev_cursor(self, pages: list[Page]) -> str | None:
+	        if not pages:
+	            return None
+	        first = pages[0]
+	        return first.data[0].id if first.data else None
+	```
+	"""
+
 	def decorator(
 		func: Callable[[TState, TParam], Awaitable[T]], /
 	) -> InfiniteQueryProperty[T, TParam, TState]: