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

pulse/hooks/effects.py

@@ -1,104 +1,88 @@
 from collections.abc import Callable
-from typing import cast, override
+from typing import Any, override
 
 from pulse.hooks.core import HookMetadata, HookState, hooks
-from pulse.reactive import Effect, EffectFn, Untrack
+from pulse.reactive import AsyncEffect, Effect
 
 
-class EffectsHookState(HookState):
-	__slots__ = ("initialized", "effects", "key", "_called")  # pyright: ignore[reportUnannotatedClassAttribute]
-	initialized: bool
-	_called: bool
+class InlineEffectHookState(HookState):
+	"""Stores inline effects keyed by function identity or explicit key."""
+
+	__slots__ = ("effects", "_seen_this_render")  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	def __init__(self) -> None:
 		super().__init__()
-		self.initialized = False
-		self.effects: tuple[Effect, ...] = ()
-		self.key: str | None = None
-		self._called = False
+		self.effects: dict[tuple[str, Any], Effect | AsyncEffect] = {}
+		self._seen_this_render: set[tuple[str, Any]] = 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 = False
-
-	def replace(self, effects: list[Effect], key: str | None) -> None:
-		self.dispose_effects()
-		self.effects = tuple(effects)
-		self.key = key
-		self.initialized = True
-
-	def dispose_effects(self) -> None:
-		for effect in self.effects:
-			effect.dispose()
-		self.effects = ()
-		self.initialized = False
-		self.key = None
+		self._seen_this_render.clear()
 
 	@override
-	def dispose(self) -> None:
-		self.dispose_effects()
-
-	def ensure_not_called(self) -> None:
-		if self._called:
+	def on_render_end(self, render_cycle: int) -> None:
+		super().on_render_end(render_cycle)
+		# Dispose effects that weren't seen this render (e.g., inside conditionals that became false)
+		for key in list(self.effects.keys()):
+			if key not in self._seen_this_render:
+				self.effects[key].dispose()
+				del self.effects[key]
+
+	def get_or_create(
+		self,
+		identity: Any,
+		key: str | None,
+		factory: Callable[[], Effect | AsyncEffect],
+	) -> Effect | AsyncEffect:
+		"""Return cached effect or create a new one."""
+		# Effects with explicit keys fully bypass identity matching.
+		full_identity = self._make_key(identity, key)
+
+		if full_identity in self._seen_this_render:
+			if key is None:
+				raise RuntimeError(
+					"@ps.effect decorator called multiple times at the same location during a single render. "
+					+ "This usually happens when using @ps.effect inside a loop. "
+					+ "Use the `key` parameter to disambiguate: @ps.effect(key=unique_value)"
+				)
 			raise RuntimeError(
-				"`pulse.effects` can only be called once per component render"
+				f"@ps.effect decorator called multiple times with the same key='{key}' during a single render."
 			)
+		self._seen_this_render.add(full_identity)
 
-	def mark_called(self) -> None:
-		self._called = True
-
-
-def _build_effects(
-	fns: tuple[EffectFn, ...],
-	on_error: Callable[[Exception], None] | None,
-) -> list[Effect]:
-	effects: list[Effect] = []
-	with Untrack():
-		for fn in fns:
-			if not callable(fn):
-				raise ValueError(
-					"Only pass functions or callable objects to `ps.effects`"
-				)
-			effects.append(
-				Effect(fn, name=getattr(fn, "__name__", "effect"), on_error=on_error)
-			)
-	return effects
+		existing = self.effects.get(full_identity)
+		if existing is not None:
+			return existing
 
+		effect = factory()
+		self.effects[full_identity] = effect
+		return effect
 
-def _effects_factory(*_: object) -> HookState:
-	return EffectsHookState()
+	@override
+	def dispose(self) -> None:
+		for eff in self.effects.values():
+			eff.dispose()
+		self.effects.clear()
+		self._seen_this_render.clear()
 
 
-_effects_hook = hooks.create(
-	"pulse:core.effects",
-	_effects_factory,
+inline_effect_hook = hooks.create(
+	"pulse:core.inline_effects",
+	lambda: InlineEffectHookState(),
 	metadata=HookMetadata(
 		owner="pulse.core",
-		description="Internal storage for pulse.effects hook",
+		description="Storage for inline @ps.effect decorators in components",
 	),
 )
 
 
-def effects(
-	*fns: EffectFn,
-	on_error: Callable[[Exception], None] | None = None,
-	key: str | None = None,
-) -> None:
-	state = cast(EffectsHookState, _effects_hook())
-	state.ensure_not_called()
-
-	if not state.initialized:
-		state.replace(_build_effects(fns, on_error), key)
-		state.mark_called()
-		return
-
-	if key is not None and key != state.key:
-		state.replace(_build_effects(fns, on_error), key)
-		state.mark_called()
-		return
-
-	state.mark_called()
-
-
-__all__ = ["effects", "EffectsHookState"]
+__all__ = [
+	"InlineEffectHookState",
+	"inline_effect_hook",
+]

pulse/hooks/init.py

@@ -41,7 +41,33 @@ def previous_frame() -> types.FrameType:
 
 
 class InitContext:
-	"""Context that captures locals on first render and restores thereafter."""
+	"""Context manager for one-time initialization in components.
+
+	Variables assigned inside the block persist across re-renders. On first render,
+	the code inside runs normally and variables are captured. On subsequent renders,
+	the block is skipped and variables are restored from storage.
+
+	This class is returned by ``ps.init()`` and should be used as a context manager.
+
+	Attributes:
+		callsite: Tuple of (code object, line number) identifying the call site.
+		frame: The stack frame where init was called.
+		first_render: True if this is the first render cycle.
+		pre_keys: Set of variable names that existed before entering the block.
+		saved: Dictionary of captured variable values.
+
+	Example:
+
+	```python
+	def my_component():
+	    with ps.init():
+	        counter = 0
+	        api = ApiClient()
+	        data = fetch_initial_data()
+	    # counter, api, data retain their values across renders
+	    return m.Text(f"Counter: {counter}")
+	```
+	"""
 
 	callsite: tuple[Any, int] | None
 	frame: types.FrameType | None
@@ -113,6 +139,39 @@ class InitContext:
 
 
 def init() -> InitContext:
+	"""Context manager for one-time initialization in components.
+
+	Variables assigned inside the block persist across re-renders. Uses AST
+	rewriting to transform the code at decoration time.
+
+	Returns:
+		InitContext: Context manager that captures and restores variables.
+
+	Example:
+
+	```python
+	def my_component():
+	    with ps.init():
+	        counter = 0
+	        api = ApiClient()
+	        data = fetch_initial_data()
+	    # counter, api, data retain their values across renders
+	    return m.Text(f"Counter: {counter}")
+	```
+
+	Rules:
+		- Can only be used once per component
+		- Must be at the top level of the component function (not inside
+		  conditionals, loops, or nested functions)
+		- Cannot contain control flow (if, for, while, try, with, match)
+		- Cannot use ``as`` binding (``with ps.init() as ctx:`` not allowed)
+		- Variables are restored from first render on subsequent renders
+
+	Notes:
+		If you encounter issues with ``ps.init()`` (e.g., source code not
+		available in some deployment environments), use ``ps.setup()`` instead.
+		It provides the same functionality without AST rewriting.
+	"""
 	return InitContext()
 
 

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()