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

pulse/components/if_.py

@@ -1,3 +1,8 @@
+"""Conditional rendering component.
+
+Provides a declarative way to conditionally render elements based on a condition.
+"""
+
 from collections.abc import Iterable
 from typing import Any, TypeVar
 
@@ -37,15 +42,33 @@ def If(
 	then: T1,
 	else_: T2 = None,
 ) -> T1 | T2:
-	"""Conditional rendering helper that returns either then or else_ based on condition.
+	"""Conditional rendering helper.
+
+	Returns `then` if the condition is truthy, otherwise returns `else_`.
+	Automatically unwraps reactive values (Signal, Computed) before evaluation.
 
 	Args:
-	    condition: Value to test truthiness
-	    then: Element to render if condition is truthy
-	    else_: Optional element to render if condition is falsy
+		condition: A boolean or reactive value to evaluate. Supports `Signal[bool]`
+			and `Computed[bool]` which are automatically unwrapped.
+		then: Element to render when condition is truthy.
+		else_: Element to render when condition is falsy. Defaults to None.
 
 	Returns:
-	    The then value if condition is truthy, else_ if provided and condition is falsy, None otherwise
+		The `then` value if condition is truthy, otherwise `else_`.
+
+	Example:
+		Basic conditional::
+
+			ps.If(
+				user.is_admin,
+				then=AdminPanel(),
+				else_=ps.p("Access denied"),
+			)
+
+		With reactive condition::
+
+			is_visible = ps.Signal(True)
+			ps.If(is_visible, then=ps.div("Content"))
 	"""
 	# Unwrap reactive condition if needed and coerce to bool explicitly with guards
 	if isinstance(condition, (Signal, Computed)):

pulse/components/react_router.py

@@ -1,12 +1,19 @@
+"""React Router components for client-side navigation.
+
+Provides Pulse bindings for react-router's Link and Outlet components.
+"""
+
 from typing import Literal, TypedDict, Unpack
 
 from pulse.dom.props import HTMLAnchorProps
+from pulse.react_component import react_component
 from pulse.transpiler import Import
 from pulse.transpiler.nodes import Node
-from pulse.transpiler.react_component import react_component
 
 
 class LinkPath(TypedDict):
+	"""TypedDict for Link's `to` prop when using an object instead of string."""
+
 	pathname: str
 	search: str
 	hash: str
@@ -27,12 +34,63 @@ def Link(
 	state: dict[str, object] | None = None,
 	viewTransition: bool | None = None,
 	**props: Unpack[HTMLAnchorProps],
-): ...
+) -> None:
+	"""Client-side navigation link using react-router.
+
+	Renders an anchor tag that performs client-side navigation without a full
+	page reload. Supports prefetching and various navigation behaviors.
+
+	Args:
+		*children: Content to render inside the link.
+		key: React reconciliation key.
+		to: The target URL path (e.g., "/dashboard", "/users/123").
+		discover: Route discovery behavior. "render" discovers on render,
+			"none" disables discovery.
+		prefetch: Prefetch strategy. "intent" (default) prefetches on hover/focus,
+			"render" prefetches immediately, "viewport" when visible, "none" disables.
+		preventScrollReset: If True, prevents scroll position reset on navigation.
+		relative: Path resolution mode. "route" resolves relative to route hierarchy,
+			"path" resolves relative to URL path.
+		reloadDocument: If True, performs a full page navigation instead of SPA.
+		replace: If True, replaces current history entry instead of pushing.
+		state: Arbitrary state to pass to the destination location.
+		viewTransition: If True, enables View Transitions API for the navigation.
+		**props: Additional HTML anchor attributes (className, onClick, etc.).
+
+	Example:
+		Basic navigation::
+
+			ps.Link(to="/dashboard")["Go to Dashboard"]
+
+		With prefetching disabled::
+
+			ps.Link(to="/settings", prefetch="none")["Settings"]
+	"""
+	...
 
 
 # @react_component(Import("Outlet", "react-router", version="^7"))
 @react_component(Import("Outlet", "react-router"))
-def Outlet(key: str | None = None): ...
+def Outlet(key: str | None = None) -> None:
+	"""Renders the matched child route's element.
+
+	Outlet is used in parent route components to render their child routes.
+	It acts as a placeholder where nested route content will be displayed.
+
+	Args:
+		key: React reconciliation key.
+
+	Example:
+		Layout with outlet for child routes::
+
+			@ps.component
+			def Layout():
+				return ps.div(
+					ps.nav("Navigation"),
+					ps.Outlet(),  # Child route renders here
+				)
+	"""
+	...
 
 
 __all__ = ["Link", "Outlet"]

pulse/context.py

@@ -16,9 +16,23 @@ if TYPE_CHECKING:
 class PulseContext:
 	"""Composite context accessible to hooks and internals.
 
-	- session: per-user session ReactiveDict
-	- render: per-connection RenderSession
-	- route: active RouteContext for this render/effect scope
+	Manages per-request state via context variables. Provides access to the
+	application instance, user session, render session, and route context.
+
+	Attributes:
+		app: Application instance.
+		session: Per-user session (UserSession or None).
+		render: Per-connection render session (RenderSession or None).
+		route: Active route context (RouteContext or None).
+
+	Example:
+		```python
+		ctx = PulseContext(app=app, session=session)
+		with ctx:
+			# Context is active here
+			current = PulseContext.get()
+		# Previous context restored
+		```
 	"""
 
 	app: "App"
@@ -28,7 +42,15 @@ class PulseContext:
 	_token: "Token[PulseContext | None] | None" = None
 
 	@classmethod
-	def get(cls):
+	def get(cls) -> "PulseContext":
+		"""Get the current context.
+
+		Returns:
+			Current PulseContext instance.
+
+		Raises:
+			RuntimeError: If no context is active.
+		"""
 		ctx = PULSE_CONTEXT.get()
 		if ctx is None:
 			raise RuntimeError("Internal error: PULSE_CONTEXT is not set")
@@ -40,7 +62,19 @@ class PulseContext:
 		session: "UserSession | None" = None,
 		render: "RenderSession | None" = None,
 		route: "RouteContext | None" = None,
-	):
+	) -> "PulseContext":
+		"""Create a new context with updated values.
+
+		Inherits unspecified values from the current context.
+
+		Args:
+			session: New session (optional, inherits if not provided).
+			render: New render session (optional, inherits if not provided).
+			route: New route context (optional, inherits if not provided).
+
+		Returns:
+			New PulseContext instance with updated values.
+		"""
 		ctx = cls.get()
 		return PulseContext(
 			app=ctx.app,

pulse/cookies.py

@@ -14,6 +14,26 @@ if TYPE_CHECKING:
 
 @dataclass
 class Cookie:
+	"""Configuration for HTTP cookies used in session management.
+
+	Attributes:
+		name: Cookie name.
+		domain: Cookie domain. Set automatically in subdomain mode.
+		secure: HTTPS-only flag. Auto-resolved from server address if None.
+		samesite: SameSite attribute ("lax", "strict", or "none").
+		max_age_seconds: Cookie lifetime in seconds (default 7 days).
+
+	Example:
+		```python
+		cookie = Cookie(
+			name="session",
+			secure=True,
+			samesite="strict",
+			max_age_seconds=3600,
+		)
+		```
+	"""
+
 	name: str
 	_: KW_ONLY
 	domain: str | None = None
@@ -22,18 +42,45 @@ class Cookie:
 	max_age_seconds: int = 7 * 24 * 3600
 
 	def get_from_fastapi(self, request: Request) -> str | None:
-		"""Extract sid from a FastAPI Request (by reading Cookie header)."""
+		"""Extract cookie value from a FastAPI Request.
+
+		Reads the Cookie header and parses it to find this cookie's value.
+
+		Args:
+			request: FastAPI/Starlette Request object.
+
+		Returns:
+			Cookie value if found, None otherwise.
+		"""
 		header = request.headers.get("cookie")
 		cookies = parse_cookie_header(header)
 		return cookies.get(self.name)
 
 	def get_from_socketio(self, environ: dict[str, Any]) -> str | None:
-		"""Extract sid from a socket.io environ mapping."""
+		"""Extract cookie value from a Socket.IO environ mapping.
+
+		Args:
+			environ: Socket.IO environ dictionary.
+
+		Returns:
+			Cookie value if found, None otherwise.
+		"""
 		raw = environ.get("HTTP_COOKIE") or environ.get("COOKIE")
 		cookies = parse_cookie_header(raw)
 		return cookies.get(self.name)
 
-	async def set_through_api(self, value: str):
+	async def set_through_api(self, value: str) -> None:
+		"""Set the cookie on the client via WebSocket.
+
+		Must be called during a callback context.
+
+		Args:
+			value: Cookie value to set.
+
+		Raises:
+			RuntimeError: If Cookie.secure is not resolved (ensure App.setup()
+				ran first).
+		"""
 		if self.secure is None:
 			raise RuntimeError(
 				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
@@ -48,7 +95,17 @@ class Cookie:
 		)
 
 	def set_on_fastapi(self, response: Response, value: str) -> None:
-		"""Set the session cookie on a FastAPI Response-like object."""
+		"""Set the cookie on a FastAPI Response object.
+
+		Configured with httponly=True and path="/".
+
+		Args:
+			response: FastAPI Response object.
+			value: Cookie value to set.
+
+		Raises:
+			RuntimeError: If Cookie.secure is not resolved.
+		"""
 		if self.secure is None:
 			raise RuntimeError(
 				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
@@ -67,10 +124,31 @@ class Cookie:
 
 @dataclass
 class SetCookie(Cookie):
+	"""Extended Cookie dataclass that includes the cookie value.
+
+	Used for setting cookies with a specific value. Inherits all configuration
+	from Cookie.
+
+	Attributes:
+		value: The cookie value to set.
+	"""
+
 	value: str
 
 	@classmethod
 	def from_cookie(cls, cookie: Cookie, value: str) -> "SetCookie":
+		"""Create a SetCookie from an existing Cookie configuration.
+
+		Args:
+			cookie: Cookie configuration to copy settings from.
+			value: Cookie value to set.
+
+		Returns:
+			SetCookie instance with the same configuration and specified value.
+
+		Raises:
+			RuntimeError: If cookie.secure is not resolved.
+		"""
 		if cookie.secure is None:
 			raise RuntimeError(
 				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
@@ -111,6 +189,18 @@ def session_cookie(
 
 
 class CORSOptions(TypedDict, total=False):
+	"""TypedDict for CORS middleware configuration.
+
+	Attributes:
+		allow_origins: List of allowed origins. Use ['*'] for all. Default: ().
+		allow_methods: List of allowed HTTP methods. Default: ('GET',).
+		allow_headers: List of allowed HTTP headers. Default: ().
+		allow_credentials: Whether to allow credentials. Default: False.
+		allow_origin_regex: Regex pattern for allowed origins. Default: None.
+		expose_headers: List of headers to expose to browser. Default: ().
+		max_age: Browser CORS cache duration in seconds. Default: 600.
+	"""
+
 	allow_origins: Sequence[str]
 	"List of allowed origins. Use ['*'] to allow all origins. Default: ()"
 
@@ -207,6 +297,20 @@ def cors_options(mode: "PulseMode", server_address: str) -> CORSOptions:
 
 
 def parse_cookie_header(header: str | None) -> dict[str, str]:
+	"""Parse a raw Cookie header string into a dictionary.
+
+	Args:
+		header: Raw Cookie header string (e.g., "session=abc123; theme=dark").
+
+	Returns:
+		Dictionary of cookie name-value pairs.
+
+	Example:
+		```python
+		cookies = parse_cookie_header("session=abc123; theme=dark")
+		# {"session": "abc123", "theme": "dark"}
+		```
+	"""
 	cookies: dict[str, str] = {}
 	if not header:
 		return cookies

pulse/decorators.py

@@ -2,8 +2,11 @@
 
 import inspect
 from collections.abc import Awaitable, Callable
-from typing import Any, ParamSpec, Protocol, TypeVar, overload
+from typing import Any, ParamSpec, Protocol, TypeVar, cast, overload
 
+from pulse.hooks.core import HOOK_CONTEXT
+from pulse.hooks.effects import inline_effect_hook
+from pulse.hooks.state import collect_component_identity
 from pulse.reactive import (
 	AsyncEffect,
 	AsyncEffectFn,
@@ -20,10 +23,6 @@ TState = TypeVar("TState", bound=State)
 P = ParamSpec("P")
 
 
-# -> @ps.computed The chalenge is:
-# - We want to turn regular functions with no arguments into a Computed object
-# - We want to turn state methods into a ComputedProperty (which wraps a
-#   Computed, but gives it access to the State object).
 @overload
 def computed(fn: Callable[[], T], *, name: str | None = None) -> Computed[T]: ...
 @overload
@@ -36,7 +35,61 @@ def computed(
 ) -> Callable[[Callable[[], T]], Computed[T]]: ...
 
 
-def computed(fn: Callable[..., Any] | None = None, *, name: str | None = None):
+def computed(
+	fn: Callable[..., Any] | None = None,
+	*,
+	name: str | None = None,
+) -> (
+	Computed[T]
+	| ComputedProperty[T]
+	| Callable[[Callable[..., Any]], Computed[T] | ComputedProperty[T]]
+):
+	"""
+	Decorator for computed (derived) properties.
+
+	Creates a cached, reactive value that automatically recalculates when its
+	dependencies change. The computed tracks which Signals/Computeds are read
+	during execution and subscribes to them.
+
+	Can be used in two ways:
+	1. On a State method (with single `self` argument) - creates a ComputedProperty
+	2. As a standalone function (with no arguments) - creates a Computed
+
+	Args:
+		fn: The function to compute the value. Must take no arguments (standalone) or only `self` (State method).
+		name: Optional debug name for the computed. Defaults to the function name.
+
+	Returns:
+		Computed wrapper or decorator depending on usage.
+
+	Raises:
+		TypeError: If the function takes arguments other than `self`.
+
+	Example:
+		On a State method:
+
+		    class MyState(ps.State):
+		        count: int = 0
+
+		        @ps.computed
+		        def doubled(self):
+		            return self.count * 2
+
+		As a standalone computed:
+
+		    signal = Signal(5)
+
+		    @ps.computed
+		    def doubled():
+		        return signal() * 2
+
+		With explicit name:
+
+		    @ps.computed(name="my_computed")
+		    def doubled(self):
+		        return self.count * 2
+	"""
+
 	# The type checker is not happy if I don't specify the `/` here.
 	def decorator(fn: Callable[..., Any], /):
 		sig = inspect.signature(fn)
@@ -81,7 +134,9 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	update_deps: bool | None = None,
 	interval: float | None = None,
+	key: str | None = None,
 ) -> Effect: ...
 
 
@@ -94,7 +149,9 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	update_deps: bool | None = None,
 	interval: float | None = None,
+	key: str | None = None,
 ) -> AsyncEffect: ...
 # In practice this overload returns a StateEffect, but it gets converted into an
 # Effect at state instantiation.
@@ -111,7 +168,9 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	update_deps: bool | None = None,
 	interval: float | None = None,
+	key: str | None = None,
 ) -> EffectBuilder: ...
 
 
@@ -123,17 +182,86 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	update_deps: bool | None = None,
 	interval: float | None = None,
+	key: str | None = None,
 ):
-	# The type checker is not happy if I don't specify the `/` here.
+	"""
+	Decorator for side effects that run when dependencies change.
+
+	Creates an effect that automatically re-runs when any of its tracked
+	dependencies change. Dependencies are automatically tracked by observing
+	which Signals/Computeds are read during execution.
+
+	Can be used in two ways:
+	1. On a State method (with single `self` argument) - creates a StateEffect
+	2. As a standalone function (with no arguments) - creates an Effect
+
+	Supports both sync and async functions. Async effects cannot use `immediate=True`.
+
+	Args:
+		fn: The effect function. Must take no arguments (standalone) or only
+		        `self` (State method). Can return a cleanup function.
+		name: Optional debug name. Defaults to "ClassName.method_name" or function name.
+		immediate: If True, run synchronously when scheduled instead of batching.
+		        Only valid for sync effects.
+		lazy: If True, don't run on creation; wait for first dependency change.
+		on_error: Callback invoked if the effect throws an exception.
+		deps: Explicit list of dependencies. If provided, auto-tracking is disabled
+		        and the effect only re-runs when these specific dependencies change.
+		interval: Re-run interval in seconds. Creates a polling effect that runs
+		        periodically regardless of dependency changes.
+
+	Returns:
+		Effect, AsyncEffect, or StateEffect depending on usage.
+
+	Raises:
+		TypeError: If the function takes arguments other than `self`.
+		ValueError: If `immediate=True` is used with an async function.
+
+	Example:
+		State method effect:
+
+		    class MyState(ps.State):
+		        count: int = 0
+
+		        @ps.effect
+		        def log_changes(self):
+		            print(f"Count is {self.count}")
+
+		Async effect:
+
+		    class MyState(ps.State):
+		        query: str = ""
+
+		        @ps.effect
+		        async def fetch_data(self):
+		            data = await api.fetch(self.query)
+		            self.data = data
+
+		Effect with cleanup:
+
+		    @ps.effect
+		    def subscribe(self):
+		        unsub = event_bus.subscribe(self.handle)
+		        return unsub  # Called before next run or on dispose
+
+		Polling effect:
+
+		    @ps.effect(interval=5.0)
+		    async def poll_status(self):
+		        self.status = await api.get_status()
+	"""
+
 	def decorator(func: Callable[..., Any], /):
 		sig = inspect.signature(func)
 		params = list(sig.parameters.values())
 
-		# Disallow intermediate + async
+		# Disallow immediate + async
 		if immediate and inspect.iscoroutinefunction(func):
 			raise ValueError("Async effects cannot have immediate=True")
 
+		# State method - unchanged behavior
 		if len(params) == 1 and params[0].name == "self":
 			return StateEffect(
 				func,
@@ -142,34 +270,75 @@ def effect(
 				lazy=lazy,
 				on_error=on_error,
 				deps=deps,
+				update_deps=update_deps,
 				interval=interval,
 			)
 
-		if len(params) > 0:
+		# Allow params with defaults (used for variable binding in loops)
+		# Reject only if there are required params (no default)
+		required_params = [p for p in params if p.default is inspect.Parameter.empty]
+		if required_params:
 			raise TypeError(
-				f"@effect: Function '{func.__name__}' must take no arguments or a single 'self' argument"
+				f"@effect: Function '{func.__name__}' must take no arguments, a single 'self' argument, "
+				+ "or only arguments with defaults (for variable binding)"
 			)
 
-		# This is a standalone effect function. Choose subclass based on async-ness
-		if inspect.iscoroutinefunction(func):
-			return AsyncEffect(
+		# Check if we're in a hook context (component render)
+		ctx = HOOK_CONTEXT.get()
+
+		def create_effect() -> Effect | AsyncEffect:
+			if inspect.iscoroutinefunction(func):
+				return AsyncEffect(
+					func,  # type: ignore[arg-type]
+					name=name or func.__name__,
+					lazy=lazy,
+					on_error=on_error,
+					deps=deps,
+					update_deps=update_deps,
+					interval=interval,
+				)
+			return Effect(
 				func,  # type: ignore[arg-type]
 				name=name or func.__name__,
+				immediate=immediate,
 				lazy=lazy,
 				on_error=on_error,
 				deps=deps,
+				update_deps=update_deps,
 				interval=interval,
 			)
-		return Effect(
-			func,  # type: ignore[arg-type]
-			name=name or func.__name__,
-			immediate=immediate,
-			lazy=lazy,
-			on_error=on_error,
-			deps=deps,
-			interval=interval,
-		)
-
-	if fn:
+
+		if ctx is None:
+			# Not in component - create standalone effect (current behavior)
+			return create_effect()
+
+		# In component render - use inline caching
+
+		# Get the frame where the decorator was applied.
+		# When called as `@ps.effect` (no parens), the call stack is:
+		#   decorator -> effect -> component
+		# When called as `@ps.effect(...)` (with parens), the stack is:
+		#   decorator -> component
+		# We detect which case by checking if the immediate caller is effect().
+		frame = inspect.currentframe()
+		assert frame is not None
+		caller = frame.f_back
+		assert caller is not None
+		# If the immediate caller is the effect function itself, go back one more
+		if (
+			caller.f_code.co_name == "effect"
+			and "decorators" in caller.f_code.co_filename
+		):
+			caller = caller.f_back
+			assert caller is not None
+		if key is None:
+			identity = collect_component_identity(caller)
+		else:
+			identity = key
+
+		state = inline_effect_hook()
+		return state.get_or_create(cast(Any, identity), key, create_effect)
+
+	if fn is not None:
 		return decorator(fn)
 	return decorator