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

pulse/hooks/runtime.py

@@ -18,6 +18,16 @@ from pulse.state import State
 
 
 class RedirectInterrupt(Exception):
+	"""Exception raised to interrupt render and trigger a redirect.
+
+	This exception is thrown by ``ps.redirect()`` to interrupt the current
+	render cycle and navigate to a different path.
+
+	Attributes:
+		path: The destination URL to redirect to.
+		replace: If True, replaces the current history entry instead of pushing.
+	"""
+
 	path: str
 	replace: bool
 
@@ -28,10 +38,34 @@ class RedirectInterrupt(Exception):
 
 
 class NotFoundInterrupt(Exception):
+	"""Exception raised to interrupt render and show 404 page.
+
+	This exception is thrown by ``ps.not_found()`` to interrupt the current
+	render cycle and display the 404 not found page.
+	"""
+
 	pass
 
 
 def route() -> RouteContext:
+	"""Get the current route context.
+
+	Returns:
+		RouteContext: Object with access to route parameters, path, and query.
+
+	Raises:
+		RuntimeError: If called outside of a component render context.
+
+	Example:
+
+	```python
+	def user_page():
+	    r = ps.route()
+	    user_id = r.params.get("user_id")  # From /users/:user_id
+	    page = r.query.get("page", "1")    # From ?page=2
+	    return m.Text(f"User {user_id}, Page {page}")
+	```
+	"""
 	ctx = PulseContext.get()
 	if not ctx or not ctx.route:
 		raise RuntimeError(
@@ -41,6 +75,24 @@ def route() -> RouteContext:
 
 
 def session() -> ReactiveDict[str, Any]:
+	"""Get the current user session data.
+
+	Returns:
+		ReactiveDict[str, Any]: Reactive dictionary of session data that persists
+			across page navigations.
+
+	Raises:
+		RuntimeError: If called outside of a session context.
+
+	Example:
+
+	```python
+	def my_component():
+	    sess = ps.session()
+	    sess["last_visited"] = datetime.now()
+	    return m.Text(f"Visits: {sess.get('visit_count', 0)}")
+	```
+	"""
 	ctx = PulseContext.get()
 	if not ctx.session:
 		raise RuntimeError("Could not resolve user session")
@@ -48,6 +100,14 @@ def session() -> ReactiveDict[str, Any]:
 
 
 def session_id() -> str:
+	"""Get the current session identifier.
+
+	Returns:
+		str: Unique identifier for the current user session.
+
+	Raises:
+		RuntimeError: If called outside of a session context.
+	"""
 	ctx = PulseContext.get()
 	if not ctx.session:
 		raise RuntimeError("Could not resolve user session")
@@ -55,6 +115,14 @@ def session_id() -> str:
 
 
 def websocket_id() -> str:
+	"""Get the current WebSocket connection identifier.
+
+	Returns:
+		str: Unique identifier for the current WebSocket connection.
+
+	Raises:
+		RuntimeError: If called outside of a WebSocket session context.
+	"""
 	ctx = PulseContext.get()
 	if not ctx.render:
 		raise RuntimeError("Could not resolve WebSocket session")
@@ -69,6 +137,25 @@ async def call_api(
 	body: Any | None = None,
 	credentials: str = "include",
 ) -> dict[str, Any]:
+	"""Make an API call through the client browser.
+
+	This function sends a request to the specified path via the client's browser,
+	which is useful for calling third-party APIs that require browser cookies
+	or credentials.
+
+	Args:
+		path: The URL path to call.
+		method: HTTP method (default: "POST").
+		headers: Optional HTTP headers to include in the request.
+		body: Optional request body (will be JSON serialized).
+		credentials: Credential mode for the request (default: "include").
+
+	Returns:
+		dict[str, Any]: The JSON response from the API.
+
+	Raises:
+		RuntimeError: If called outside of a Pulse callback context.
+	"""
 	ctx = PulseContext.get()
 	if ctx.render is None:
 		raise RuntimeError("call_api() must be invoked inside a Pulse callback context")
@@ -90,6 +177,19 @@ async def set_cookie(
 	samesite: Literal["lax", "strict", "none"] = "lax",
 	max_age_seconds: int = 7 * 24 * 3600,
 ) -> None:
+	"""Set a cookie on the client.
+
+	Args:
+		name: The cookie name.
+		value: The cookie value.
+		domain: Optional domain for the cookie.
+		secure: Whether the cookie should only be sent over HTTPS (default: True).
+		samesite: SameSite attribute ("lax", "strict", or "none"; default: "lax").
+		max_age_seconds: Cookie lifetime in seconds (default: 7 days).
+
+	Raises:
+		RuntimeError: If called outside of a session context.
+	"""
 	ctx = PulseContext.get()
 	if ctx.session is None:
 		raise RuntimeError("Could not resolve the user session")
@@ -104,6 +204,29 @@ async def set_cookie(
 
 
 def navigate(path: str, *, replace: bool = False, hard: bool = False) -> None:
+	"""Navigate to a new URL.
+
+	Triggers client-side navigation to the specified path. By default, uses
+	client-side routing which is faster and preserves application state.
+
+	Args:
+		path: Destination URL to navigate to.
+		replace: If True, replaces the current history entry instead of pushing
+			a new one (default: False).
+		hard: If True, performs a full page reload instead of client-side
+			navigation (default: False).
+
+	Raises:
+		RuntimeError: If called outside of a Pulse callback context.
+
+	Example:
+
+	```python
+	async def handle_login():
+	    await api.login(username, password)
+	    ps.navigate("/dashboard")
+	```
+	"""
 	ctx = PulseContext.get()
 	if ctx.render is None:
 		raise RuntimeError("navigate() must be invoked inside a Pulse callback context")
@@ -113,6 +236,32 @@ def navigate(path: str, *, replace: bool = False, hard: bool = False) -> None:
 
 
 def redirect(path: str, *, replace: bool = False) -> NoReturn:
+	"""Redirect during render (throws exception to interrupt render).
+
+	Unlike ``navigate()``, this function is intended for use during the render
+	phase to immediately redirect before the component finishes rendering.
+	It raises a ``RedirectInterrupt`` exception that is caught by the framework.
+
+	Args:
+		path: Destination URL to redirect to.
+		replace: If True, replaces the current history entry instead of pushing
+			a new one (default: False).
+
+	Raises:
+		RuntimeError: If called outside of component render.
+		RedirectInterrupt: Always raised to interrupt the render.
+
+	Example:
+
+	```python
+	def protected_page():
+	    user = get_current_user()
+	    if not user:
+	        ps.redirect("/login")  # Interrupts render
+
+	    return m.Text(f"Welcome, {user.name}")
+	```
+	"""
 	ctx = HOOK_CONTEXT.get()
 	if not ctx:
 		raise RuntimeError("redirect() must be invoked during component render")
@@ -120,6 +269,27 @@ def redirect(path: str, *, replace: bool = False) -> NoReturn:
 
 
 def not_found() -> NoReturn:
+	"""Trigger 404 during render (throws exception to interrupt render).
+
+	Interrupts the current render and displays the 404 not found page.
+	Raises a ``NotFoundInterrupt`` exception that is caught by the framework.
+
+	Raises:
+		RuntimeError: If called outside of component render.
+		NotFoundInterrupt: Always raised to trigger 404 page.
+
+	Example:
+
+	```python
+	def user_page():
+	    r = ps.route()
+	    user = get_user(r.params["id"])
+	    if not user:
+	        ps.not_found()  # Shows 404 page
+
+	    return m.Text(user.name)
+	```
+	"""
 	ctx = HOOK_CONTEXT.get()
 	if not ctx:
 		raise RuntimeError("not_found() must be invoked during component render")
@@ -127,6 +297,15 @@ def not_found() -> NoReturn:
 
 
 def server_address() -> str:
+	"""Get the server's public address.
+
+	Returns:
+		str: The server's public address (e.g., "https://example.com").
+
+	Raises:
+		RuntimeError: If called outside of a Pulse render/callback context
+			or if the server address is not configured.
+	"""
 	ctx = PulseContext.get()
 	if ctx.render is None:
 		raise RuntimeError(
@@ -140,6 +319,15 @@ def server_address() -> str:
 
 
 def client_address() -> str:
+	"""Get the client's IP address.
+
+	Returns:
+		str: The client's IP address.
+
+	Raises:
+		RuntimeError: If called outside of a Pulse render/callback context
+			or if the client address is not available.
+	"""
 	ctx = PulseContext.get()
 	if ctx.render is None:
 		raise RuntimeError(
@@ -157,17 +345,70 @@ S = TypeVar("S", covariant=True, bound=State)
 
 
 class GlobalStateAccessor(Protocol, Generic[P, S]):
+	"""Protocol for global state accessor functions.
+
+	A callable that returns the shared state instance, optionally scoped
+	by an instance ID.
+	"""
+
 	def __call__(
 		self, id: str | None = None, *args: P.args, **kwargs: P.kwargs
 	) -> S: ...
 
 
 GLOBAL_STATES: dict[str, State] = {}
+"""Global dictionary storing state instances keyed by their qualified names."""
 
 
 def global_state(
 	factory: Callable[P, S] | type[S], key: str | None = None
 ) -> GlobalStateAccessor[P, S]:
+	"""Create a globally shared state accessor.
+
+	Creates a decorator or callable that provides access to a shared state
+	instance. The state is shared across all components that use the same
+	accessor.
+
+	Can be used as a decorator on a State class or with a factory function.
+
+	Args:
+		factory: State class or factory function that creates the state instance.
+		key: Optional custom key for the global state. If not provided, a key
+			is derived from the factory's module and qualified name.
+
+	Returns:
+		GlobalStateAccessor: A callable that returns the shared state instance.
+			Call with ``id=`` parameter for per-entity global state.
+
+	Example:
+
+	```python
+	@ps.global_state
+	class AppSettings(ps.State):
+	    theme: str = "light"
+	    language: str = "en"
+
+	def settings_panel():
+	    settings = AppSettings()  # Same instance across all components
+	    return m.Select(
+	        value=settings.theme,
+	        data=["light", "dark"],
+	        on_change=lambda v: setattr(settings, "theme", v),
+	    )
+	```
+
+	With instance ID for per-entity global state:
+
+	```python
+	@ps.global_state
+	class UserCache(ps.State):
+	    data: dict = {}
+
+	def user_profile(user_id: str):
+	    cache = UserCache(id=user_id)  # Shared per user_id
+	    return m.Text(cache.data.get("name", "Loading..."))
+	```
+	"""
 	if isinstance(factory, type):
 		cls = factory
 

pulse/hooks/setup.py

@@ -11,6 +11,20 @@ T = TypeVar("T")
 
 
 class SetupHookState(HookState):
+	"""Internal hook state for the setup hook.
+
+	Manages the initialization, argument tracking, and lifecycle of
+	setup-created values.
+
+	Attributes:
+		value: The value returned by the setup function.
+		initialized: Whether setup has been called at least once.
+		args: List of signals tracking positional argument values.
+		kwargs: Dict of signals tracking keyword argument values.
+		effects: List of effects created during setup execution.
+		key: Optional key for re-initialization control.
+	"""
+
 	__slots__ = (  # pyright: ignore[reportUnannotatedClassAttribute]
 		"value",
 		"initialized",
@@ -141,6 +155,46 @@ _setup_hook = hooks.create(
 
 
 def setup(init_func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+	"""One-time initialization that persists across renders.
+
+	Calls the init function on first render and caches the result. On subsequent
+	renders, returns the cached value without re-running the function.
+
+	This is the lower-level alternative to ``ps.init()`` that doesn't require
+	AST rewriting and works in all environments.
+
+	Args:
+		init_func: Function to call on first render. Its return value is cached.
+		*args: Positional arguments passed to init_func. Changes to these are
+			tracked via reactive signals.
+		**kwargs: Keyword arguments passed to init_func. Changes to these are
+			tracked via reactive signals.
+
+	Returns:
+		The value returned by init_func (cached on first render).
+
+	Raises:
+		RuntimeError: If called more than once per component render.
+		RuntimeError: If the number or names of arguments change between renders.
+
+	Example:
+
+	```python
+	@ps.component
+	def Counter():
+	    def init():
+	        return CounterState(), expensive_calculation()
+
+	    state, value = ps.setup(init)
+
+	    return ps.div(f"Count: {state.count}")
+	```
+
+	Notes:
+		- ``ps.init()`` is syntactic sugar that transforms into ``ps.setup()`` calls
+		- Use ``ps.setup()`` directly when AST rewriting is problematic
+		- Arguments must be consistent across renders (same count and names)
+	"""
 	state = _setup_hook()
 	state.ensure_not_called()
 
@@ -166,6 +220,29 @@ def setup(init_func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
 
 
 def setup_key(key: str) -> None:
+	"""Set a key for the next setup call to control re-initialization.
+
+	When the key changes between renders, the setup function is re-run
+	and a new value is created. This is useful for resetting state when
+	a prop changes.
+
+	Args:
+		key: String key that, when changed, triggers re-initialization
+			of the subsequent setup call.
+
+	Raises:
+		TypeError: If key is not a string.
+		RuntimeError: If called after setup() in the same render.
+
+	Example:
+
+	```python
+	def user_profile(user_id: str):
+	    ps.setup_key(user_id)  # Re-run setup when user_id changes
+	    data = ps.setup(lambda: fetch_user_data(user_id))
+	    return m.Text(data.name)
+	```
+	"""
 	if not isinstance(key, str):
 		raise TypeError("setup_key() requires a string key")
 	state = _setup_hook()

pulse/hooks/stable.py

@@ -8,6 +8,17 @@ TCallable = TypeVar("TCallable", bound=Callable[..., Any])
 
 
 class StableEntry:
+	"""Container for a stable value and its wrapper function.
+
+	Holds a value and a wrapper function that always delegates to the
+	current value, allowing the wrapper reference to remain stable while
+	the underlying value can change.
+
+	Attributes:
+		value: The current wrapped value.
+		wrapper: Stable function that delegates to the current value.
+	"""
+
 	__slots__ = ("value", "wrapper")  # pyright: ignore[reportUnannotatedClassAttribute]
 	value: Any
 	wrapper: Callable[..., Any]
@@ -25,6 +36,13 @@ class StableEntry:
 
 
 class StableRegistry(HookState):
+	"""Internal hook state that stores stable entries by key.
+
+	Maintains a dictionary of StableEntry objects, allowing stable
+	wrappers to persist across renders while their underlying values
+	can be updated.
+	"""
+
 	__slots__ = ("entries",)  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	def __init__(self) -> None:
@@ -58,7 +76,46 @@ def stable(key: str, value: TCallable) -> TCallable: ...
 def stable(key: str, value: T) -> Callable[[], T]: ...
 
 
-def stable(key: str, value: Any = MISSING):
+def stable(key: str, value: Any = MISSING) -> Any:
+	"""Return a stable wrapper that always calls the latest value.
+
+		Creates a wrapper function that maintains a stable reference across renders
+		while delegating to the current value. Useful for event handlers and callbacks
+		that need to stay referentially stable.
+
+		Args:
+			key: Unique identifier for this stable value within the component.
+			value: Optional value or callable to wrap. If provided, updates the
+				stored value and returns the wrapper. If omitted, returns the
+				existing wrapper for the key.
+
+		Returns:
+			A stable wrapper function that delegates to the current value. If the
+			value is callable, the wrapper calls it with any provided arguments.
+			If not callable, the wrapper returns the value directly.
+
+		Raises:
+			ValueError: If key is empty.
+			KeyError: If value is not provided and no entry exists for the key.
+
+		Example:
+
+		```python
+		def my_component():
+		    s = ps.state("data", lambda: DataState())
+
+		    # Without stable, this would create a new function each render
+		    handle_click = ps.stable("click", lambda: s.increment())
+
+		    return m.Button("Click", on_click=handle_click)
+		```
+
+		Use Cases:
+			- Event handlers passed to child components to prevent unnecessary re-renders
+			- Callbacks registered with external systems
+			- Any function reference that needs to stay stable across renders
+	) -> Any:
+	"""
 	if not key:
 		raise ValueError("stable() requires a non-empty string key")
 

pulse/hooks/state.py

@@ -1,6 +1,9 @@
+import inspect
 from collections.abc import Callable
-from typing import TypeVar, override
+from types import CodeType, FrameType
+from typing import Any, TypeVar, override
 
+from pulse.component import is_component_code
 from pulse.hooks.core import HookMetadata, HookState, hooks
 from pulse.state import State
 
@@ -8,42 +11,71 @@ S = TypeVar("S", bound=State)
 
 
 class StateHookState(HookState):
+	"""Internal hook state for managing State instances across renders.
+
+	Stores State instances keyed by string identifier and tracks which keys
+	have been accessed during the current render cycle.
+	"""
+
 	__slots__ = ("instances", "called_keys")  # pyright: ignore[reportUnannotatedClassAttribute]
-	instances: dict[str, State]
-	called_keys: set[str]
+	instances: dict[tuple[str, Any], State]
+	called_keys: set[tuple[str, Any]]
 
 	def __init__(self) -> None:
 		super().__init__()
 		self.instances = {}
 		self.called_keys = set()
 
+	def _make_key(self, identity: Any, key: str | None) -> tuple[str, Any]:
+		if key is None:
+			return ("code", identity)
+		return ("key", key)
+
 	@override
 	def on_render_start(self, render_cycle: int) -> None:
 		super().on_render_start(render_cycle)
 		self.called_keys.clear()
 
-	def get_or_create_state(self, key: str, arg: State | Callable[[], State]) -> State:
-		if key in self.called_keys:
+	def get_or_create_state(
+		self,
+		identity: Any,
+		key: str | None,
+		arg: State | Callable[[], State],
+	) -> State:
+		full_identity = self._make_key(identity, key)
+		if full_identity in self.called_keys:
+			if key is None:
+				raise RuntimeError(
+					"`pulse.state` can only be called once per component render at the same location. "
+					+ "Use the `key` parameter to disambiguate: ps.state(..., key=unique_value)"
+				)
 			raise RuntimeError(
 				f"`pulse.state` can only be called once per component render with key='{key}'"
 			)
-		self.called_keys.add(key)
+		self.called_keys.add(full_identity)
 
-		existing = self.instances.get(key)
+		existing = self.instances.get(full_identity)
 		if existing is not None:
 			# Dispose any State instances passed directly as args that aren't being used
 			if isinstance(arg, State) and arg is not existing:
-				try:
-					if not arg.__disposed__:
-						arg.dispose()
-				except RuntimeError:
-					# Already disposed, ignore
-					pass
+				arg.dispose()
+			if existing.__disposed__:
+				key_label = f"key='{key}'" if key is not None else "callsite"
+				raise RuntimeError(
+					"`pulse.state` found a disposed cached State for "
+					+ key_label
+					+ ". Do not dispose states returned by `pulse.state`."
+				)
 			return existing
 
 		# Create new state
 		instance = _instantiate_state(arg)
-		self.instances[key] = instance
+		if instance.__disposed__:
+			raise RuntimeError(
+				"`pulse.state` received a disposed State instance. "
+				+ "Do not dispose states passed to `pulse.state`."
+			)
+		self.instances[full_identity] = instance
 		return instance
 
 	@override
@@ -71,6 +103,26 @@ def _state_factory():
 	return StateHookState()
 
 
+def _frame_offset(frame: FrameType) -> int:
+	offset = frame.f_lasti
+	if offset < 0:
+		offset = frame.f_lineno
+	return offset
+
+
+def collect_component_identity(
+	frame: FrameType,
+) -> tuple[tuple[CodeType, int], ...]:
+	identity: list[tuple[CodeType, int]] = []
+	cursor: FrameType | None = frame
+	while cursor is not None:
+		identity.append((cursor.f_code, _frame_offset(cursor)))
+		if is_component_code(cursor.f_code):
+			return tuple(identity)
+		cursor = cursor.f_back
+	return tuple(identity[:1])
+
+
 _state_hook = hooks.create(
 	"pulse:core.state",
 	_state_factory,
@@ -81,25 +133,60 @@ _state_hook = hooks.create(
 )
 
 
-def state(key: str, arg: S | Callable[[], S]) -> S:
-	"""Get or create a state instance associated with the given key.
+def state(
+	arg: S | Callable[[], S],
+	*,
+	key: str | None = None,
+) -> S:
+	"""Get or create a state instance associated with a key or callsite.
 
 	Args:
-		key: A unique string key identifying this state within the component.
 		arg: A State instance or a callable that returns a State instance.
+		key: Optional key to disambiguate multiple calls from the same location.
 
 	Returns:
-		The state instance (same instance on subsequent renders with the same key).
+		The same State instance on subsequent renders with the same key.
 
 	Raises:
 		ValueError: If key is empty.
 		RuntimeError: If called more than once per render with the same key.
 		TypeError: If arg is not a State or callable returning a State.
+
+	Example:
+
+	```python
+	def counter():
+	    s = ps.state("counter", lambda: CounterState())
+	    return m.Button(f"Count: {s.count}", on_click=lambda: s.increment())
+	```
+
+	Notes:
+		- Key must be non-empty string
+		- Can only be called once per render with the same key
+		- Factory is only called on first render; subsequent renders return cached instance
+		- State is disposed when component unmounts
 	"""
-	if not key:
+	if key is not None and not isinstance(key, str):
+		raise TypeError("state() key must be a string")
+
+	if key == "":
 		raise ValueError("state() requires a non-empty string key")
+
+	resolved_key = key
+	resolved_arg = arg
+
+	identity: Any
+	if resolved_key is None:
+		frame = inspect.currentframe()
+		assert frame is not None
+		caller = frame.f_back
+		assert caller is not None
+		identity = collect_component_identity(caller)
+	else:
+		identity = resolved_key
+
 	hook_state = _state_hook()
-	return hook_state.get_or_create_state(key, arg)  # pyright: ignore[reportReturnType]
+	return hook_state.get_or_create_state(identity, resolved_key, resolved_arg)  # pyright: ignore[reportReturnType]
 
 
 __all__ = ["state", "StateHookState"]