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

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

pulse/env.py

@@ -18,6 +18,13 @@ from typing import Literal
 
 # Types
 PulseEnv = Literal["dev", "ci", "prod"]
+"""Environment type for the Pulse application.
+
+Values:
+    "dev": Development environment with hot reload and debugging.
+    "ci": Continuous integration environment for testing.
+    "prod": Production environment with optimizations enabled.
+"""
 
 # Keys
 ENV_PULSE_ENV = "PULSE_ENV"
@@ -31,6 +38,28 @@ ENV_PULSE_DISABLE_CODEGEN = "PULSE_DISABLE_CODEGEN"
 
 
 class EnvVars:
+	"""Singleton accessor for Pulse environment variables.
+
+	Provides typed getters and setters for all Pulse-related environment
+	variables. Access via the `env` singleton instance.
+
+	Example:
+		```python
+		from pulse.env import env
+
+		env.pulse_env = "prod"
+		if env.pulse_env == "dev":
+		    print(f"Running on {env.pulse_host}:{env.pulse_port}")
+		```
+
+	Attributes:
+		pulse_env: Current environment ("dev", "ci", "prod").
+		pulse_host: Server hostname. Defaults to "localhost".
+		pulse_port: Server port number. Defaults to 8000.
+		pulse_secret: Secret key for JWT session signing.
+		codegen_disabled: If True, skip code generation.
+	"""
+
 	def _get(self, key: str) -> str | None:
 		return os.environ.get(key)
 
@@ -117,8 +146,33 @@ class EnvVars:
 
 # Singleton
 env = EnvVars()
+"""Singleton instance for accessing Pulse environment variables.
+
+Example:
+    ```python
+    from pulse.env import env
+
+    env.pulse_env = "prod"
+    print(env.pulse_host)  # "localhost"
+    print(env.pulse_port)  # 8000
+    ```
+"""
+
+
+def mode() -> PulseEnv:
+	"""Returns the current pulse_env value.
+
+	Shorthand for `env.pulse_env`.
+
+	Returns:
+		The current environment: "dev", "ci", or "prod".
 
+	Example:
+		```python
+		from pulse.env import mode
 
-# Commonly used helpesr
-def mode():
+		if mode() == "dev":
+		    enable_debug_toolbar()
+		```
+	"""
 	return env.pulse_env

pulse/form.py

@@ -42,8 +42,16 @@ __all__ = [
 	"FormStorage",
 	"internal_forms_hook",
 ]
+
 FormValue = str | UploadFile
+"""Individual form field value: ``str | UploadFile``."""
+
 FormData = dict[str, FormValue | list[FormValue]]
+"""Parsed form submission data.
+
+Values are either single or multiple (for repeated field names).
+Type alias for ``dict[str, FormValue | list[FormValue]]``.
+"""
 
 
 @react_component(Import("PulseForm", "pulse-ui-client"))
@@ -56,6 +64,16 @@ def client_form_component(
 
 @dataclass
 class FormRegistration:
+	"""Internal registration info for a form.
+
+	Attributes:
+		id: Unique form identifier.
+		render_id: Associated render session ID.
+		route_path: Route path this form is bound to.
+		session_id: Associated user session ID.
+		on_submit: Async callback for form submission.
+	"""
+
 	id: str
 	render_id: str
 	route_path: str
@@ -64,6 +82,12 @@ class FormRegistration:
 
 
 class FormRegistry(Disposable):
+	"""Internal class managing form registrations.
+
+	Not typically used directly. Forms are registered automatically via
+	``ps.Form`` or ``ManualForm``.
+	"""
+
 	def __init__(self, render: "RenderSession") -> None:
 		self._render: "RenderSession" = render
 		self._handlers: dict[str, FormRegistration] = {}
@@ -75,6 +99,17 @@ class FormRegistry(Disposable):
 		session_id: str,
 		on_submit: Callable[[FormData], Awaitable[None]],
 	) -> FormRegistration:
+		"""Register a form handler.
+
+		Args:
+			render_id: Render session ID.
+			route_id: Route path.
+			session_id: User session ID.
+			on_submit: Async callback for form submission.
+
+		Returns:
+			FormRegistration with generated form ID.
+		"""
 		registration = FormRegistration(
 			uuid.uuid4().hex,
 			render_id=render_id,
@@ -86,10 +121,16 @@ class FormRegistry(Disposable):
 		return registration
 
 	def unregister(self, form_id: str) -> None:
+		"""Unregister a form handler.
+
+		Args:
+			form_id: The form ID to unregister.
+		"""
 		self._handlers.pop(form_id, None)
 
 	@override
 	def dispose(self) -> None:
+		"""Clean up all registered forms."""
 		self._handlers.clear()
 
 	async def handle_submit(
@@ -98,6 +139,20 @@ class FormRegistry(Disposable):
 		request: Request,
 		session: "UserSession",
 	) -> Response:
+		"""Handle incoming form submission.
+
+		Args:
+			form_id: The form ID being submitted.
+			request: The HTTP request.
+			session: The user session.
+
+		Returns:
+			HTTP response (204 on success).
+
+		Raises:
+			HTTPException: If form not found (404), session mismatch (403),
+				or route unmounted (410).
+		"""
 		registration = self._handlers.get(form_id)
 		if registration is None:
 			raise HTTPException(status_code=404, detail="Unknown form submission")
@@ -139,6 +194,16 @@ class FormRegistry(Disposable):
 
 
 def normalize_form_data(raw: StarletteFormData) -> FormData:
+	"""Convert Starlette FormData to normalized FormData dict.
+
+	Handles multiple values for the same key and filters out empty file uploads.
+
+	Args:
+		raw: Starlette FormData from request.form().
+
+	Returns:
+		Normalized FormData dictionary.
+	"""
 	normalized: FormData = {}
 	for key, value in raw.multi_items():
 		item: FormValue
@@ -163,6 +228,11 @@ def normalize_form_data(raw: StarletteFormData) -> FormData:
 
 
 class PulseFormProps(HTMLFormProps, total=False):
+	"""Form props that exclude action, method, encType, and onSubmit.
+
+	These props are auto-generated by Pulse for form handling.
+	"""
+
 	action: Never  # pyright: ignore[reportIncompatibleVariableOverride]
 	method: Never  # pyright: ignore[reportIncompatibleVariableOverride]
 	encType: Never  # pyright: ignore[reportIncompatibleVariableOverride]
@@ -174,7 +244,48 @@ def Form(
 	key: str,
 	onSubmit: EventHandler1[FormData] | None = None,
 	**props: Unpack[PulseFormProps],  # pyright: ignore[reportGeneralTypeIssues]
-):
+) -> Node:
+	"""Server-registered HTML form component.
+
+	Automatically wires up form submission to a Python handler. Uses
+	``multipart/form-data`` encoding to support file uploads.
+
+	Args:
+		*children: Form content (inputs, buttons, etc.).
+		key: Unique form identifier (required, non-empty string).
+		onSubmit: Submit handler receiving parsed FormData.
+		**props: Standard HTML form props (except action, method, encType, onSubmit).
+
+	Returns:
+		Form node.
+
+	Raises:
+		ValueError: If key is empty or onSubmit is not callable.
+		RuntimeError: If called outside a component render.
+
+	Example:
+
+	```python
+	async def handle_submit(data: ps.FormData):
+	    name = data.get("name")  # str
+	    file = data.get("avatar")  # UploadFile
+	    await save_user(name, file)
+
+	def my_form():
+	    return ps.Form(
+	        m.TextInput(name="name", label="Name"),
+	        m.FileInput(name="avatar", label="Avatar"),
+	        m.Button("Submit", type="submit"),
+	        key="user-form",
+	        onSubmit=handle_submit,
+	    )
+	```
+
+	Note:
+		- ``key`` must be unique within the render.
+		- Cannot override ``action``, ``method``, ``encType``, or ``onSubmit`` via props.
+		- Handler receives parsed form data as a ``FormData`` dict.
+	"""
 	if not isinstance(key, str) or not key:
 		raise ValueError("ps.Form requires a non-empty string key")
 	if not callable(onSubmit):
@@ -197,6 +308,15 @@ def Form(
 
 
 class GeneratedFormProps(TypedDict):
+	"""Form props generated by ``ManualForm.props()``.
+
+	Attributes:
+		action: Form submission URL.
+		method: HTTP method ("POST").
+		encType: Encoding type ("multipart/form-data").
+		onSubmit: Submission trigger callback.
+	"""
+
 	action: str
 	method: str
 	encType: str
@@ -204,11 +324,51 @@ class GeneratedFormProps(TypedDict):
 
 
 class ManualForm(Disposable):
+	"""Low-level form handler for custom form implementations.
+
+	Use when you need more control over form rendering than ``ps.Form`` provides.
+
+	Attributes:
+		is_submitting: Whether the form is currently submitting.
+		registration: Form registration info (raises if disposed).
+
+	Example:
+
+	```python
+	def custom_form():
+	    manual = ManualForm(on_submit=handle_data)
+
+	    # Option 1: Render directly
+	    return manual(
+	        m.TextInput(name="field"),
+	        m.Button("Submit", type="submit"),
+	        key="my-form",
+	    )
+
+	    # Option 2: Use props manually
+	    form_props = manual.props()
+	    return m.form(
+	        m.TextInput(name="field"),
+	        m.Button("Submit", type="submit"),
+	        **form_props,
+	    )
+	```
+	"""
+
 	_submit_signal: Signal[bool]
 	_render: "RenderSession"
 	_registration: FormRegistration | None
 
 	def __init__(self, on_submit: EventHandler1[FormData] | None = None) -> None:
+		"""Initialize a manual form handler.
+
+		Args:
+			on_submit: Optional submit handler receiving parsed FormData.
+
+		Raises:
+			RuntimeError: If called outside a render pass, route context,
+				or user session.
+		"""
 		ctx = PulseContext.get()
 		render = ctx.render
 		route = ctx.route
@@ -238,19 +398,30 @@ class ManualForm(Disposable):
 		return on_submit_handler
 
 	@property
-	def is_submitting(self):
+	def is_submitting(self) -> bool:
+		"""Whether the form is currently submitting."""
 		return self._submit_signal.read()
 
 	@property
-	def registration(self):
+	def registration(self) -> FormRegistration:
+		"""Form registration info.
+
+		Raises:
+			ValueError: If the form has been disposed.
+		"""
 		if self._registration is None:
 			raise ValueError("This form has been disposed")
 		return self._registration
 
-	def _start_submit(self):
+	def _start_submit(self) -> None:
 		self._submit_signal.write(True)
 
 	def props(self) -> GeneratedFormProps:
+		"""Get form props for manual binding to a form element.
+
+		Returns:
+			Dict with action, method, encType, and onSubmit props.
+		"""
 		return {
 			"action": f"{server_address()}/pulse/forms/{self._render.id}/{self.registration.id}",
 			"method": "POST",
@@ -263,22 +434,44 @@ class ManualForm(Disposable):
 		*children: Node,
 		key: str | None = None,
 		**props: Unpack[PulseFormProps],
-	):
+	) -> Node:
+		"""Render as a form element with children.
+
+		Args:
+			*children: Form content.
+			key: Optional element key.
+			**props: Additional form props.
+
+		Returns:
+			Form node with auto-generated submission props.
+		"""
 		props.update(self.props())  # pyright: ignore[reportCallIssue, reportArgumentType]
 		return client_form_component(*children, key=key, **props)
 
 	@override
 	def dispose(self) -> None:
+		"""Unregister the form and clean up."""
 		if self._registration is None:
 			return
 		self._render.forms.unregister(self._registration.id)
 		self._registration = None
 
 	def update(self, on_submit: EventHandler1[FormData] | None) -> None:
+		"""Update the submit handler.
+
+		Args:
+			on_submit: New submit handler.
+		"""
 		self.registration.on_submit = self.wrap_on_submit(on_submit)
 
 
 class FormStorage(HookState):
+	"""Internal hook state for managing form lifecycle within renders.
+
+	Not typically used directly. Manages form persistence and cleanup across
+	render cycles.
+	"""
+
 	__slots__ = ("forms", "prev_forms", "render_mark")  # pyright: ignore[reportUnannotatedClassAttribute]
 	render_mark: int
 

pulse/helpers.py

@@ -252,7 +252,13 @@ def later(
 
 	from pulse.reactive import Untrack
 
-	loop = asyncio.get_running_loop()
+	try:
+		loop = asyncio.get_running_loop()
+	except RuntimeError:
+		try:
+			loop = asyncio.get_event_loop()
+		except RuntimeError as exc:
+			raise RuntimeError("later() requires an event loop") from exc
 
 	def _run():
 		try: