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

pulse/codegen/codegen.py

@@ -24,13 +24,32 @@ logger = logging.getLogger(__file__)
 
 @dataclass
 class CodegenConfig:
-	"""
-	Configuration for code generation.
+	"""Configuration for code generation output paths.
+
+	Controls where generated React Router files are written. All paths
+	can be relative (resolved against base_dir) or absolute.
+
+	Args:
+		web_dir: Root directory for web output. Defaults to "web".
+		pulse_dir: Subdirectory for generated Pulse files. Defaults to "pulse".
+		base_dir: Base directory for resolving relative paths. If not provided,
+			resolved from PULSE_APP_FILE, PULSE_APP_DIR, or cwd.
 
 	Attributes:
-	    web_dir (str): Root directory for the web output.
-	    pulse_dir (str): Name of the Pulse app directory.
-	    pulse_path (Path): Full path to the generated app directory.
+		web_dir: Root directory for web output.
+		pulse_dir: Subdirectory name for generated files.
+		base_dir: Explicit base directory, if provided.
+
+	Example:
+		```python
+		app = ps.App(
+		    codegen=ps.CodegenConfig(
+		        web_dir="frontend",
+		        pulse_dir="generated",
+		    ),
+		)
+		# Generated files will be at: frontend/app/generated/
+		```
 	"""
 
 	web_dir: Path | str = "web"
@@ -46,11 +65,14 @@ class CodegenConfig:
 	def resolved_base_dir(self) -> Path:
 		"""Resolve the base directory where relative paths should be anchored.
 
-		Precedence:
-		  1) Explicit `base_dir` if provided
-		  2) Env var `PULSE_APP_FILE` (directory of the file)
-		  3) Env var `PULSE_APP_DIR`
-		  4) Current working directory
+		Returns:
+			Resolved base directory path.
+
+		Resolution precedence:
+			1. Explicit `base_dir` if provided
+			2. Directory of PULSE_APP_FILE env var
+			3. PULSE_APP_DIR env var
+			4. Current working directory
 		"""
 		if isinstance(self.base_dir, Path):
 			return self.base_dir
@@ -64,7 +86,11 @@ class CodegenConfig:
 
 	@property
 	def web_root(self) -> Path:
-		"""Absolute path to the web root directory (e.g. `<app_dir>/pulse-web`)."""
+		"""Absolute path to the web root directory.
+
+		Returns:
+			Absolute path to web_dir (e.g., `<base_dir>/web`).
+		"""
 		wd = Path(self.web_dir)
 		if wd.is_absolute():
 			return wd
@@ -72,7 +98,12 @@ class CodegenConfig:
 
 	@property
 	def pulse_path(self) -> Path:
-		"""Full path to the generated app directory."""
+		"""Full path to the generated Pulse app directory.
+
+		Returns:
+			Absolute path where generated files are written
+			(e.g., `<web_root>/app/<pulse_dir>`).
+		"""
 		return self.web_root / "app" / self.pulse_dir
 
 

pulse/component.py

@@ -1,7 +1,14 @@
+"""Component definition and VDOM node types for Pulse.
+
+This module provides the core component abstraction for building Pulse UIs,
+including the `@component` decorator and the `Component` class.
+"""
+
 from __future__ import annotations
 
 from collections.abc import Callable
 from inspect import Parameter, signature
+from types import CodeType
 from typing import Any, Generic, ParamSpec, TypeVar, overload, override
 
 from pulse.code_analysis import is_stub_function
@@ -19,14 +26,47 @@ from pulse.transpiler.vdom import VDOMNode
 P = ParamSpec("P")
 _T = TypeVar("_T")
 
+_COMPONENT_CODES: set[CodeType] = set()
+
+
+def is_component_code(code: CodeType) -> bool:
+	return code in _COMPONENT_CODES
+
 
 class Component(Generic[P]):
+	"""A callable wrapper that turns a function into a Pulse component.
+
+	Component instances are created by the `@component` decorator. When called,
+	they return a `PulseNode` that represents the component in the virtual DOM.
+
+	Attributes:
+		name: Display name of the component (defaults to function name).
+		fn: The underlying render function (lazily initialized for stubs).
+
+	Example:
+
+	```python
+	@ps.component
+	def Card(title: str):
+	    return ps.div(ps.h3(title))
+
+	Card(title="Hello")  # Returns a PulseNode
+	Card(title="Hello", key="card-1")  # With reconciliation key
+	```
+	"""
+
 	_raw_fn: Callable[P, Any]
 	_fn: Callable[P, Any] | None
 	name: str
 	_takes_children: bool | None
 
 	def __init__(self, fn: Callable[P, Any], name: str | None = None) -> None:
+		"""Initialize a Component.
+
+		Args:
+			fn: The function to wrap as a component.
+			name: Custom display name. Defaults to the function's `__name__`.
+		"""
 		self._raw_fn = fn
 		self.name = name or _infer_component_name(fn)
 		# Only lazy-init for stubs (avoid heavy work for JS module bindings)
@@ -37,15 +77,31 @@ class Component(Generic[P]):
 		else:
 			self._fn = rewrite_init_blocks(fn)
 			self._takes_children = _takes_children(fn)
+			_COMPONENT_CODES.add(self._fn.__code__)
 
 	@property
 	def fn(self) -> Callable[P, Any]:
+		"""The render function (lazily initialized for stub functions)."""
 		if self._fn is None:
 			self._fn = rewrite_init_blocks(self._raw_fn)
 			self._takes_children = _takes_children(self._raw_fn)
+			_COMPONENT_CODES.add(self._fn.__code__)
 		return self._fn
 
 	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> PulseNode:
+		"""Invoke the component to create a PulseNode.
+
+		Args:
+			*args: Positional arguments passed to the component function.
+			**kwargs: Keyword arguments passed to the component function.
+				The special `key` kwarg is used for reconciliation.
+
+		Returns:
+			A PulseNode representing this component invocation in the VDOM.
+
+		Raises:
+			ValueError: If `key` is provided but is not a string.
+		"""
 		key = kwargs.get("key")
 		if key is not None and not isinstance(key, str):
 			raise ValueError("key must be a string or None")
@@ -85,6 +141,53 @@ def component(
 def component(
 	fn: Callable[P, Any] | None = None, *, name: str | None = None
 ) -> Component[P] | Callable[[Callable[P, Any]], Component[P]]:
+	"""Decorator that creates a Pulse component from a function.
+
+	Can be used with or without parentheses. The decorated function becomes
+	callable and returns a `PulseNode` when invoked.
+
+	Args:
+		fn: Function to wrap as a component. When used as `@component` without
+			parentheses, this is the decorated function.
+		name: Custom component name for debugging/dev tools. Defaults to the
+			function's `__name__`.
+
+	Returns:
+		A `Component` instance if `fn` is provided, otherwise a decorator.
+
+	Example:
+
+	Basic usage:
+
+	```python
+	@ps.component
+	def Card(title: str):
+	    return ps.div(ps.h3(title))
+	```
+
+	With custom name:
+
+	```python
+	@ps.component(name="MyCard")
+	def card_impl(title: str):
+	    return ps.div(ps.h3(title))
+	```
+
+	With children (use `*children` parameter):
+
+	```python
+	@ps.component
+	def Container(*children):
+	    return ps.div(*children, className="container")
+
+	# Children can be passed via subscript syntax:
+	Container()[
+	    Card(title="First"),
+	    Card(title="Second"),
+	]
+	```
+	"""
+
 	def decorator(fn: Callable[P, Any]) -> Component[P]:
 		return Component(fn, name)
 
@@ -130,4 +233,5 @@ __all__ = [
 	"Primitive",
 	"VDOMNode",
 	"component",
+	"is_component_code",
 ]

pulse/components/for_.py

@@ -1,3 +1,8 @@
+"""For loop component for mapping items to elements.
+
+Provides a declarative way to render lists, similar to JavaScript's Array.map().
+"""
+
 from collections.abc import Callable, Iterable
 from inspect import Parameter, signature
 from typing import TYPE_CHECKING, Any, TypeVar, overload
@@ -27,11 +32,32 @@ def For(items: Iterable[T], fn: Callable[[T, int], Element]) -> list[Element]: .
 
 
 def For(items: Iterable[T], fn: Callable[..., Element]) -> list[Element]:
-	"""Map items to elements, passing `(item)` or `(item, index)`.
+	"""Map items to elements, like JavaScript's Array.map().
+
+	Iterates over `items` and calls `fn` for each one, returning a list of
+	elements. The mapper function can accept either one argument (item) or
+	two arguments (item, index).
+
+	Args:
+		items: Iterable of items to map over.
+		fn: Mapper function that receives `(item)` or `(item, index)` and
+			returns an Element. If `fn` has a `*args` parameter, it receives
+			both item and index.
+
+	Returns:
+		A list of Elements, one for each item.
+
+	Example:
+		Single argument (item only)::
+
+			ps.For(users, lambda user: UserCard(user=user, key=user.id))
+
+		With index::
+
+			ps.For(items, lambda item, i: ps.li(f"{i}: {item}", key=str(i)))
 
-	The callable `fn` may accept either a single positional argument (the item)
-	or two positional arguments (the item and its index), similar to JavaScript's
-	Array.map. If `fn` declares `*args`, it will receive `(item, index)`.
+	Note:
+		In transpiled `@javascript` code, `For` compiles to `.map()`.
 	"""
 	try:
 		sig = signature(fn)

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