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

pulse/hooks/core.py

@@ -31,6 +31,18 @@ MISSING: Any = object()
 
 @dataclass(slots=True)
 class HookMetadata:
+	"""Metadata for a registered hook.
+
+	Contains optional descriptive information about a hook, useful for
+	debugging and documentation.
+
+	Attributes:
+		description: Human-readable description of the hook's purpose.
+		owner: Module or package that owns this hook (e.g., "pulse.core").
+		version: Version string for the hook implementation.
+		extra: Additional metadata as a mapping.
+	"""
+
 	description: str | None = None
 	owner: str | None = None
 	version: str | None = None
@@ -38,20 +50,58 @@ class HookMetadata:
 
 
 class HookState(Disposable):
-	"""Base class returned by hook factories."""
+	"""Base class for hook state returned by hook factories.
+
+	Subclass this to create custom hook state that persists across renders.
+	Override lifecycle methods to respond to render events.
+
+	Attributes:
+		render_cycle: The current render cycle number.
+
+	Example:
+
+	```python
+	class TimerHookState(ps.hooks.State):
+	    def __init__(self):
+	        self.start_time = time.time()
+
+	    def elapsed(self) -> float:
+	        return time.time() - self.start_time
+
+	    def dispose(self) -> None:
+	        pass
+
+	_timer_hook = ps.hooks.create("my_app:timer", lambda: TimerHookState())
+
+	def use_timer() -> TimerHookState:
+	    return _timer_hook()
+	```
+	"""
 
 	render_cycle: int = 0
 
 	def on_render_start(self, render_cycle: int) -> None:
+		"""Called before each component render.
+
+		Args:
+			render_cycle: The current render cycle number.
+		"""
 		self.render_cycle = render_cycle
 
 	def on_render_end(self, render_cycle: int) -> None:
-		"""Called after the component render has completed."""
+		"""Called after the component render has completed.
+
+		Args:
+			render_cycle: The current render cycle number.
+		"""
 		...
 
 	@override
 	def dispose(self) -> None:
-		"""Called when the hook instance is discarded."""
+		"""Called when the hook instance is discarded.
+
+		Override to clean up resources (close connections, cancel tasks, etc.).
+		"""
 		...
 
 
@@ -66,11 +116,33 @@ def _default_factory() -> HookState:
 
 @dataclass(slots=True)
 class Hook(Generic[T]):
+	"""A registered hook definition.
+
+	Hooks are created via ``ps.hooks.create()`` and can be called during
+	component render to access their associated state.
+
+	Attributes:
+		name: Unique name identifying this hook.
+		factory: Function that creates new HookState instances.
+		metadata: Optional metadata about the hook.
+	"""
+
 	name: str
 	factory: HookFactory[T]
 	metadata: HookMetadata
 
 	def __call__(self, key: str | None = None) -> T:
+		"""Get or create hook state for the current component.
+
+		Args:
+			key: Optional key for multiple instances of the same hook.
+
+		Returns:
+			The hook state instance.
+
+		Raises:
+			HookError: If called outside of a render context.
+		"""
 		ctx = HookContext.require(self.name)
 		namespace = ctx.namespace_for(self)
 		state = namespace.ensure(ctx, key)
@@ -79,6 +151,17 @@ class Hook(Generic[T]):
 
 @dataclass(slots=True)
 class HookInit(Generic[T]):
+	"""Initialization context passed to hook factories.
+
+	When a hook factory accepts a single argument, it receives this object
+	containing context about the initialization.
+
+	Attributes:
+		key: Optional key if the hook was called with a specific key.
+		render_cycle: The current render cycle number.
+		definition: Reference to the Hook definition being initialized.
+	"""
+
 	key: str | None
 	render_cycle: int
 	definition: Hook[T]
@@ -178,7 +261,6 @@ class HookContext:
 		if self._token is not None:
 			HOOK_CONTEXT.reset(self._token)
 			self._token = None
-
 			for namespace in self.namespaces.values():
 				namespace.on_render_end(self.render_cycle)
 		return False
@@ -265,6 +347,19 @@ HOOK_REGISTRY: HookRegistry = HookRegistry()
 
 
 class HooksAPI:
+	"""Low-level API for creating custom hooks.
+
+	Access via ``ps.hooks``. Provides methods for registering, listing,
+	and managing hooks.
+
+	Attributes:
+		State: Alias for HookState base class.
+		Metadata: Alias for HookMetadata dataclass.
+		AlreadyRegisteredError: Exception for duplicate hook registration.
+		NotFoundError: Exception for missing hook lookup.
+		RenameCollisionError: Exception for hook rename conflicts.
+	"""
+
 	__slots__ = ()  # pyright: ignore[reportUnannotatedClassAttribute]
 
 	State: type[HookState] = HookState
@@ -281,7 +376,42 @@ class HooksAPI:
 		factory: HookFactory[T] = _default_factory,
 		*,
 		metadata: HookMetadata | None = None,
-	):
+	) -> "Hook[T]":
+		"""Register a new hook.
+
+		Args:
+			name: Unique name for the hook (e.g., "my_app:timer").
+			factory: Function that creates HookState instances. Can be a
+				zero-argument callable or accept a HookInit object.
+			metadata: Optional metadata describing the hook.
+
+		Returns:
+			Hook[T]: The registered hook, callable during component render.
+
+		Raises:
+			ValueError: If name is empty.
+			HookAlreadyRegisteredError: If a hook with this name already exists.
+			HookError: If the registry is locked.
+
+		Example:
+
+		```python
+		class TimerHookState(ps.hooks.State):
+		    def __init__(self):
+		        self.start_time = time.time()
+
+		    def elapsed(self) -> float:
+		        return time.time() - self.start_time
+
+		    def dispose(self) -> None:
+		        pass
+
+		_timer_hook = ps.hooks.create("my_app:timer", lambda: TimerHookState())
+
+		def use_timer() -> TimerHookState:
+		    return _timer_hook()
+		```
+		"""
 		return HOOK_REGISTRY.create(name, factory, metadata)
 
 	def rename(self, current: str, new: str) -> None:

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