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

pulse/queries/mutation.py

@@ -22,9 +22,28 @@ P = ParamSpec("P")
 
 
 class MutationResult(Generic[T, P]):
-	"""
-	Result object for mutations that provides reactive access to mutation state
-	and is callable to execute the mutation.
+	"""Result object for mutations providing reactive state and execution.
+
+	MutationResult wraps an async mutation function and provides reactive
+	access to its execution state. It is callable to execute the mutation.
+
+	Attributes:
+		data: The last successful mutation result, or None.
+		is_running: Whether the mutation is currently executing.
+		error: The last error encountered, or None.
+
+	Example:
+
+	```python
+	# Access mutation state
+	if state.update_name.is_running:
+	    show_loading()
+	if state.update_name.error:
+	    show_error(state.update_name.error)
+
+	# Execute mutation
+	result = await state.update_name("New Name")
+	```
 	"""
 
 	_data: Signal[T | None]
@@ -40,6 +59,13 @@ class MutationResult(Generic[T, P]):
 		on_success: Callable[[T], Any] | None = None,
 		on_error: Callable[[Exception], Any] | None = None,
 	):
+		"""Initialize the mutation result.
+
+		Args:
+			fn: The bound async function to execute.
+			on_success: Optional callback invoked on successful completion.
+			on_error: Optional callback invoked on error.
+		"""
 		self._data = Signal(None, name="mutation.data")
 		self._is_running = Signal(False, name="mutation.is_running")
 		self._error = Signal(None, name="mutation.error")
@@ -49,14 +75,17 @@ class MutationResult(Generic[T, P]):
 
 	@property
 	def data(self) -> T | None:
+		"""The last successful mutation result, or None if never completed."""
 		return self._data()
 
 	@property
 	def is_running(self) -> bool:
+		"""Whether the mutation is currently executing."""
 		return self._is_running()
 
 	@property
 	def error(self) -> Exception | None:
+		"""The last error encountered, or None if no error."""
 		return self._error()
 
 	async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
@@ -78,6 +107,37 @@ class MutationResult(Generic[T, P]):
 
 
 class MutationProperty(Generic[T, TState, P], InitializableProperty):
+	"""Descriptor for state-bound mutations created by the @mutation decorator.
+
+	MutationProperty is the return type of the ``@mutation`` decorator. It acts
+	as a descriptor that creates and manages MutationResult instances for each
+	State object.
+
+	When accessed on a State instance, returns a MutationResult that can be
+	called to execute the mutation and provides reactive state properties.
+
+	Supports additional decorators for customization:
+		- ``@mutation_prop.on_success``: Handle successful mutation.
+		- ``@mutation_prop.on_error``: Handle mutation errors.
+
+	Example:
+
+	```python
+	class UserState(ps.State):
+	    @ps.mutation
+	    async def update_name(self, name: str) -> User:
+	        return await api.update_user(name=name)
+
+	    @update_name.on_success
+	    def _on_success(self, data: User):
+	        self.user.invalidate()  # Refresh user query
+
+	    @update_name.on_error
+	    def _on_error(self, error: Exception):
+	        logger.error(f"Update failed: {error}")
+	```
+	"""
+
 	_on_success_fn: Callable[[TState, T], Any] | None
 	_on_error_fn: Callable[[TState, Exception], Any] | None
 	name: str
@@ -90,13 +150,28 @@ class MutationProperty(Generic[T, TState, P], InitializableProperty):
 		on_success: OnSuccessFn[TState, T] | None = None,
 		on_error: OnErrorFn[TState] | None = None,
 	):
+		"""Initialize the mutation property.
+
+		Args:
+			name: The method name.
+			fn: The async method to wrap.
+			on_success: Optional success callback.
+			on_error: Optional error callback.
+		"""
 		self.name = name
 		self.fn = fn
 		self._on_success_fn = on_success  # pyright: ignore[reportAttributeAccessIssue]
 		self._on_error_fn = on_error  # pyright: ignore[reportAttributeAccessIssue]
 
-	# Decorator to attach an on-success handler (sync or async)
-	def on_success(self, fn: OnSuccessFn[TState, T]):
+	def on_success(self, fn: OnSuccessFn[TState, T]) -> OnSuccessFn[TState, T]:
+		"""Decorator to attach an on-success handler (sync or async).
+
+		Args:
+			fn: Callback receiving (self, data) on successful mutation.
+
+		Returns:
+			The callback function unchanged.
+		"""
 		if self._on_success_fn is not None:
 			raise RuntimeError(
 				f"Duplicate on_success() decorator for mutation '{self.name}'. Only one is allowed."
@@ -104,8 +179,15 @@ class MutationProperty(Generic[T, TState, P], InitializableProperty):
 		self._on_success_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
 		return fn
 
-	# Decorator to attach an on-error handler (sync or async)
-	def on_error(self, fn: OnErrorFn[TState]):
+	def on_error(self, fn: OnErrorFn[TState]) -> OnErrorFn[TState]:
+		"""Decorator to attach an on-error handler (sync or async).
+
+		Args:
+			fn: Callback receiving (self, error) on mutation failure.
+
+		Returns:
+			The callback function unchanged.
+		"""
 		if self._on_error_fn is not None:
 			raise RuntimeError(
 				f"Duplicate on_error() decorator for mutation '{self.name}'. Only one is allowed."
@@ -160,7 +242,45 @@ def mutation(
 
 def mutation(
 	fn: Callable[Concatenate[TState, P], Awaitable[T]] | None = None,
+) -> (
+	MutationProperty[T, TState, P]
+	| Callable[
+		[Callable[Concatenate[TState, P], Awaitable[T]]],
+		MutationProperty[T, TState, P],
+	]
 ):
+	"""Decorator for async mutations (write operations) on State methods.
+
+	Creates a mutation wrapper that tracks execution state and provides
+	callbacks for success/error handling. Unlike queries, mutations are
+	not cached and must be explicitly called.
+
+	Args:
+		fn: The async method to decorate (when used without parentheses).
+
+	Returns:
+		MutationProperty that creates MutationResult instances when accessed.
+
+	Example:
+
+	```python
+	class UserState(ps.State):
+	    @ps.mutation
+	    async def update_name(self, name: str) -> User:
+	        return await api.update_user(name=name)
+
+	    @update_name.on_success
+	    def _on_success(self, data: User):
+	        self.user.invalidate()
+	```
+
+	Calling the mutation:
+
+	```python
+	result = await state.update_name("New Name")
+	```
+	"""
+
 	def decorator(func: Callable[Concatenate[TState, P], Awaitable[T]], /):
 		sig = inspect.signature(func)
 		params = list(sig.parameters.values())

pulse/queries/query.py

@@ -48,6 +48,20 @@ RETRY_DELAY_DEFAULT = 2.0 if not is_pytest() else 0.01
 
 @dataclass(slots=True)
 class QueryConfig(Generic[T]):
+	"""Configuration options for a query.
+
+	Stores immutable configuration that controls query behavior including
+	retry logic, caching, and lifecycle callbacks.
+
+	Attributes:
+		retries: Number of retry attempts on failure (default 3).
+		retry_delay: Delay in seconds between retry attempts (default 2.0).
+		initial_data: Initial data value or factory function.
+		initial_data_updated_at: Timestamp for initial data staleness calculation.
+		gc_time: Seconds to keep unused query in cache before garbage collection.
+		on_dispose: Callback invoked when query is disposed.
+	"""
+
 	retries: int
 	retry_delay: float
 	initial_data: T | Callable[[], T] | None
@@ -57,9 +71,20 @@ class QueryConfig(Generic[T]):
 
 
 class QueryState(Generic[T]):
-	"""
-	Container for query state signals and manipulation methods.
+	"""Container for query state signals and manipulation methods.
+
+	Manages reactive signals for query data, status, errors, and retry state.
 	Used by both KeyedQuery and UnkeyedQuery via composition.
+
+	Attributes:
+		cfg: Query configuration options.
+		data: Signal containing the fetched data or None.
+		error: Signal containing the last error or None.
+		last_updated: Signal with timestamp of last successful update.
+		status: Signal with current QueryStatus ("loading", "success", "error").
+		is_fetching: Signal indicating if a fetch is in progress.
+		retries: Signal with current retry attempt count.
+		retry_reason: Signal with exception from last failed retry.
 	"""
 
 	cfg: QueryConfig[T]
@@ -900,17 +925,38 @@ class KeyedQueryResult(Generic[T], Disposable):
 
 
 class QueryProperty(Generic[T, TState], InitializableProperty):
-	"""
-	Descriptor for state-bound queries.
+	"""Descriptor for state-bound queries created by the @query decorator.
+
+	QueryProperty is the return type of the ``@query`` decorator. It acts as a
+	descriptor that creates and manages query instances for each State object.
+
+	When accessed on a State instance, returns a QueryResult with reactive
+	properties (data, status, error) and methods (refetch, invalidate, etc.).
+
+	Supports additional decorators for customization:
+		- ``@query_prop.key``: Define dynamic query key for sharing.
+		- ``@query_prop.initial_data``: Provide initial/placeholder data.
+		- ``@query_prop.on_success``: Handle successful fetch.
+		- ``@query_prop.on_error``: Handle fetch errors.
 
-	Usage:
-	    class S(ps.State):
-	        @ps.query()
-	        async def user(self) -> User: ...
+	Example:
 
-	        @user.key
-	        def _user_key(self):
-	            return ("user", self.user_id)
+	```python
+	class UserState(ps.State):
+	    user_id: str = ""
+
+	    @ps.query
+	    async def user(self) -> User:
+	        return await api.get_user(self.user_id)
+
+	    @user.key
+	    def _user_key(self):
+	        return ("user", self.user_id)
+
+	    @user.on_success
+	    def _on_user_loaded(self, data: User):
+	        print(f"Loaded user: {data.name}")
+	```
 	"""
 
 	name: str
@@ -1183,7 +1229,62 @@ def query(
 	enabled: bool = True,
 	fetch_on_mount: bool = True,
 	key: QueryKey | None = None,
+) -> (
+	QueryProperty[T, TState]
+	| Callable[[Callable[[TState], Awaitable[T]]], QueryProperty[T, TState]]
 ):
+	"""Decorator for async data fetching on State methods.
+
+	Creates a reactive query that automatically fetches data, handles loading
+	states, retries on failure, and caches results. Queries can be shared
+	across components using keys.
+
+	Args:
+		fn: The async method to decorate (when used without parentheses).
+		stale_time: Seconds before data is considered stale (default 0.0).
+		gc_time: Seconds to keep unused query in cache (default 300.0, None to disable).
+		refetch_interval: Auto-refetch interval in seconds (default None, disabled).
+		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 calculation.
+		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:
+		QueryProperty that creates QueryResult instances when accessed.
+
+	Example:
+
+	Basic usage:
+
+	```python
+	class UserState(ps.State):
+	    user_id: str = ""
+
+	    @ps.query
+	    async def user(self) -> User:
+	        return await api.get_user(self.user_id)
+	```
+
+	With options:
+
+	```python
+	@ps.query(stale_time=60, refetch_interval=300)
+	async def user(self) -> User:
+	    return await api.get_user(self.user_id)
+	```
+
+	Keyed query (shared across instances):
+
+	```python
+	@ps.query(key=("users", "current"))
+	async def current_user(self) -> User:
+	    return await api.get_current_user()
+	```
+	"""
+
 	def decorator(
 		func: Callable[[TState], Awaitable[T]], /
 	) -> QueryProperty[T, TState]:

pulse/react_component.py

@@ -1,5 +1,68 @@
-"""Thin wrappers for transpiler react_component integration."""
+"""React component helpers for Python API."""
 
-from pulse.transpiler.react_component import default_signature, react_component
+from __future__ import annotations
 
-__all__ = ["react_component", "default_signature"]
+from collections.abc import Callable
+from typing import Any, ParamSpec, overload
+
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import Element, Expr, Jsx, Node
+
+P = ParamSpec("P")
+
+
+def default_signature(
+	*children: Node, key: str | None = None, **props: Any
+) -> Element: ...
+
+
+class ReactComponent(Jsx):
+	"""JSX wrapper for React components with runtime call support."""
+
+	def __init__(self, expr: Expr) -> None:
+		if not isinstance(expr, Expr):
+			raise TypeError("ReactComponent expects an Expr")
+		if isinstance(expr, Jsx):
+			expr = expr.expr
+		super().__init__(expr)
+
+
+@overload
+def react_component(
+	expr_or_name: Expr,
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]: ...
+
+
+@overload
+def react_component(
+	expr_or_name: str, src: str, *, lazy: bool = False
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]: ...
+
+
+def react_component(
+	expr_or_name: Expr | str,
+	src: str | None = None,
+	*,
+	lazy: bool = False,
+) -> Callable[[Callable[P, Any]], Callable[P, Element]]:
+	"""Decorator for typed React component bindings."""
+	if isinstance(expr_or_name, Expr):
+		if src is not None:
+			raise TypeError("react_component expects (expr) or (name, src)")
+		if lazy:
+			raise TypeError("react_component lazy only supported with (name, src)")
+		component = ReactComponent(expr_or_name)
+	elif isinstance(expr_or_name, str):
+		if src is None:
+			raise TypeError("react_component expects (name, src)")
+		component = ReactComponent(Import(expr_or_name, src, lazy=lazy))
+	else:
+		raise TypeError("react_component expects an Expr or (name, src)")
+
+	def decorator(fn: Callable[P, Any]) -> Callable[P, Element]:
+		return component.as_(fn)
+
+	return decorator
+
+
+__all__ = ["ReactComponent", "react_component", "default_signature"]