pulse-framework 0.1.41__py3-none-any.whl → 0.1.43__py3-none-any.whl

pulse/__init__.py

@@ -72,8 +72,6 @@ from pulse.css import (
 # Decorators
 from pulse.decorators import computed as computed
 from pulse.decorators import effect as effect
-from pulse.decorators import mutation as mutation
-from pulse.decorators import query as query
 
 # Environment
 from pulse.env import PulseEnv as PulseEnv
@@ -161,6 +159,11 @@ from pulse.hooks.core import (
 # Hooks - Effects
 from pulse.hooks.effects import EffectsHookState as EffectsHookState
 from pulse.hooks.effects import effects as effects
+
+# Hooks - Init
+from pulse.hooks.init import (
+	init as init,
+)
 from pulse.hooks.runtime import (
 	GLOBAL_STATES as GLOBAL_STATES,
 )
@@ -1344,7 +1347,18 @@ from pulse.middleware import (
 
 # Plugin
 from pulse.plugin import Plugin as Plugin
-from pulse.queries.query import QueryStatus as QueryStatus
+from pulse.queries.client import QueryClient as QueryClient
+from pulse.queries.client import QueryFilter as QueryFilter
+from pulse.queries.client import queries as queries
+from pulse.queries.common import ActionError as ActionError
+from pulse.queries.common import ActionResult as ActionResult
+from pulse.queries.common import ActionSuccess as ActionSuccess
+from pulse.queries.common import QueryKey as QueryKey
+from pulse.queries.common import QueryStatus as QueryStatus
+from pulse.queries.infinite_query import infinite_query as infinite_query
+from pulse.queries.mutation import mutation as mutation
+from pulse.queries.query import QueryResult as QueryResult
+from pulse.queries.query import query as query
 
 # React component registry
 from pulse.react_component import (

pulse/context.py

@@ -2,7 +2,7 @@
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
 from types import TracebackType
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 from pulse.routing import RouteContext
 
@@ -58,10 +58,11 @@ class PulseContext:
 		exc_type: type[BaseException] | None = None,
 		exc_val: BaseException | None = None,
 		exc_tb: TracebackType | None = None,
-	):
+	) -> Literal[False]:
 		if self._token is not None:
 			PULSE_CONTEXT.reset(self._token)
 			self._token = None
+		return False
 
 
 PULSE_CONTEXT: ContextVar["PulseContext | None"] = ContextVar(

pulse/decorators.py

@@ -2,16 +2,8 @@
 
 import inspect
 from collections.abc import Awaitable, Callable
-from typing import Any, Concatenate, ParamSpec, Protocol, TypeVar, overload
+from typing import Any, ParamSpec, Protocol, TypeVar, overload
 
-from pulse.helpers import MISSING
-from pulse.queries.common import OnErrorFn, OnSuccessFn
-from pulse.queries.mutation import MutationProperty
-from pulse.queries.query import RETRY_DELAY_DEFAULT
-from pulse.queries.query_observer import (
-	QueryProperty,
-	QueryPropertyWithInitial,
-)
 from pulse.reactive import (
 	AsyncEffect,
 	AsyncEffectFn,
@@ -89,6 +81,7 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
 ) -> Effect: ...
 
 
@@ -101,6 +94,7 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
 ) -> AsyncEffect: ...
 # In practice this overload returns a StateEffect, but it gets converted into an
 # Effect at state instantiation.
@@ -117,6 +111,7 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
 ) -> EffectBuilder: ...
 
 
@@ -128,6 +123,7 @@ def effect(
 	lazy: bool = False,
 	on_error: Callable[[Exception], None] | None = None,
 	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
 ):
 	# The type checker is not happy if I don't specify the `/` here.
 	def decorator(func: Callable[..., Any], /):
@@ -146,6 +142,7 @@ def effect(
 				lazy=lazy,
 				on_error=on_error,
 				deps=deps,
+				interval=interval,
 			)
 
 		if len(params) > 0:
@@ -161,6 +158,7 @@ def effect(
 				lazy=lazy,
 				on_error=on_error,
 				deps=deps,
+				interval=interval,
 			)
 		return Effect(
 			func,  # type: ignore[arg-type]
@@ -169,169 +167,7 @@ def effect(
 			lazy=lazy,
 			on_error=on_error,
 			deps=deps,
-		)
-
-	if fn:
-		return decorator(fn)
-	return decorator
-
-
-# -----------------
-# Query decorator
-# -----------------
-
-
-# With initial (narrowed return type) - more specific overloads first
-@overload
-def query(
-	fn: Callable[[TState], Awaitable[T]],
-	*,
-	key: Callable[[TState], tuple[Any, ...]] | None = None,
-	stale_time: float = 0.0,
-	gc_time: float | None = 300.0,
-	keep_previous_data: bool = False,
-	retries: int = 3,
-	retry_delay: float | None = None,
-	initial: T | Callable[[TState], T],
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> QueryPropertyWithInitial[T, TState]: ...
-
-
-@overload
-def query(
-	fn: None = None,
-	*,
-	key: Callable[[TState], tuple[Any, ...]] | None = None,
-	stale_time: float = 0.0,
-	gc_time: float | None = 300.0,
-	keep_previous_data: bool = False,
-	retries: int = 3,
-	retry_delay: float | None = None,
-	initial: T | Callable[[TState], T],
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> Callable[
-	[Callable[[TState], Awaitable[T]]], QueryPropertyWithInitial[T, TState]
-]: ...
-
-
-@overload
-def query(
-	fn: Callable[[TState], Awaitable[T]],
-	*,
-	key: Callable[[TState], tuple[Any, ...]] | None = None,
-	stale_time: float = 0.0,
-	gc_time: float | None = 300.0,
-	keep_previous_data: bool = False,
-	retries: int = 3,
-	retry_delay: float | None = None,
-	initial: T | Callable[[TState], T] | None = ...,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> QueryProperty[T, TState]: ...
-
-
-@overload
-def query(
-	fn: None = None,
-	*,
-	key: Callable[[TState], tuple[Any, ...]] | None = None,
-	stale_time: float = 0.0,
-	gc_time: float | None = 300.0,
-	keep_previous_data: bool = False,
-	retries: int = 3,
-	retry_delay: float | None = None,
-	initial: T | Callable[[TState], T] | None = ...,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> Callable[[Callable[[TState], Awaitable[T]]], QueryProperty[T, TState]]: ...
-
-
-def query(
-	fn: Callable[[TState], Awaitable[T]] | None = None,
-	*,
-	key: Callable[[TState], tuple[Any, ...]] | None = None,
-	stale_time: float = 0.0,
-	gc_time: float | None = 300.0,
-	keep_previous_data: bool = False,
-	retries: int = 3,
-	retry_delay: float | None = None,
-	initial: T | Callable[[TState], T] | None = MISSING,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-):
-	def decorator(
-		func: Callable[[TState], Awaitable[T]], /
-	) -> QueryProperty[T, TState] | QueryPropertyWithInitial[T, TState]:
-		sig = inspect.signature(func)
-		params = list(sig.parameters.values())
-		# Only state-method form supported for now (single 'self')
-		if not (len(params) == 1 and params[0].name == "self"):
-			raise TypeError("@query currently only supports state methods (self)")
-
-		prop_cls = QueryPropertyWithInitial if initial is not None else QueryProperty
-
-		return prop_cls(
-			func.__name__,
-			func,
-			key=key,
-			stale_time=stale_time,
-			gc_time=gc_time if gc_time is not None else 300.0,
-			keep_previous_data=keep_previous_data,
-			retries=retries,
-			retry_delay=RETRY_DELAY_DEFAULT if retry_delay is None else retry_delay,
-			initial=initial,
-			on_success=on_success,
-			on_error=on_error,
-		)
-
-	if fn:
-		return decorator(fn)
-	return decorator
-
-
-# -----------------
-# Mutation decorator
-# -----------------
-@overload
-def mutation(
-	fn: Callable[Concatenate[TState, P], Awaitable[T]],
-	*,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> MutationProperty[T, TState, P]: ...
-
-
-@overload
-def mutation(
-	fn: None = None,
-	*,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-) -> Callable[
-	[Callable[Concatenate[TState, P], Awaitable[T]]], MutationProperty[T, TState, P]
-]: ...
-
-
-def mutation(
-	fn: Callable[Concatenate[TState, P], Awaitable[T]] | None = None,
-	*,
-	on_success: OnSuccessFn[TState, T] | None = None,
-	on_error: OnErrorFn[TState] | None = None,
-):
-	def decorator(func: Callable[Concatenate[TState, P], Awaitable[T]], /):
-		sig = inspect.signature(func)
-		params = list(sig.parameters.values())
-
-		if len(params) == 0 or params[0].name != "self":
-			raise TypeError("@mutation method must have 'self' as first argument")
-
-		return MutationProperty(
-			func.__name__,
-			func,
-			on_success=on_success,
-			on_error=on_error,
+			interval=interval,
 		)
 
 	if fn:

pulse/helpers.py

@@ -212,31 +212,39 @@ def later(
 	"""
 	Schedule `fn(*args, **kwargs)` to run after `delay` seconds.
 	Works with sync or async functions. Returns a TimerHandle; call .cancel() to cancel.
+
+	The callback runs with no reactive scope to avoid accidentally capturing
+	reactive dependencies from the calling context. Other context vars (like
+	PulseContext) are preserved normally.
 	"""
+
+	from pulse.reactive import Untrack
+
 	loop = asyncio.get_running_loop()
 
 	def _run():
 		try:
-			res = fn(*args, **kwargs)
-			if asyncio.iscoroutine(res):
-				task = loop.create_task(res)
-
-				def _log_task_exception(t: asyncio.Task[Any]):
-					try:
-						t.result()
-					except asyncio.CancelledError:
-						# Normal cancellation path
-						pass
-					except Exception as exc:
-						loop.call_exception_handler(
-							{
-								"message": "Unhandled exception in later() task",
-								"exception": exc,
-								"context": {"callback": fn},
-							}
-						)
-
-				task.add_done_callback(_log_task_exception)
+			with Untrack():
+				res = fn(*args, **kwargs)
+				if asyncio.iscoroutine(res):
+					task = loop.create_task(res)
+
+					def _log_task_exception(t: asyncio.Task[Any]):
+						try:
+							t.result()
+						except asyncio.CancelledError:
+							# Normal cancellation path
+							pass
+						except Exception as exc:
+							loop.call_exception_handler(
+								{
+									"message": "Unhandled exception in later() task",
+									"exception": exc,
+									"context": {"callback": fn},
+								}
+							)
+
+					task.add_done_callback(_log_task_exception)
 		except Exception as exc:
 			# Surface exceptions via the loop's exception handler and continue
 			loop.call_exception_handler(
@@ -273,9 +281,16 @@ def repeat(interval: float, fn: Callable[P, Any], *args: P.args, **kwargs: P.kwa
 	For async functions, waits for completion before starting the next delay.
 	Returns a handle with .cancel() to stop future runs.
 
+	The callback runs with no reactive scope to avoid accidentally capturing
+	reactive dependencies from the calling context. Other context vars (like
+	PulseContext) are preserved normally.
+
 	Optional kwargs:
 	- immediate: bool = False  # run once immediately before the first interval
 	"""
+
+	from pulse.reactive import Untrack
+
 	loop = asyncio.get_running_loop()
 	handle = RepeatHandle()
 
@@ -288,9 +303,10 @@ def repeat(interval: float, fn: Callable[P, Any], *args: P.args, **kwargs: P.kwa
 				if handle.cancelled:
 					break
 				try:
-					result = fn(*args, **kwargs)
-					if asyncio.iscoroutine(result):
-						await result
+					with Untrack():
+						result = fn(*args, **kwargs)
+						if asyncio.iscoroutine(result):
+							await result
 				except asyncio.CancelledError:
 					# Propagate to outer handler to finish cleanly
 					raise

pulse/hooks/core.py

@@ -3,7 +3,7 @@ import logging
 from collections.abc import Callable, Mapping
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
-from typing import Any, Generic, TypeVar, override
+from typing import Any, Generic, Literal, TypeVar, override
 
 from pulse.helpers import Disposable, call_flexible
 
@@ -40,10 +40,7 @@ class HookMetadata:
 class HookState(Disposable):
 	"""Base class returned by hook factories."""
 
-	render_cycle: int
-
-	def __init__(self) -> None:
-		self.render_cycle = 0
+	render_cycle: int = 0
 
 	def on_render_start(self, render_cycle: int) -> None:
 		self.render_cycle = render_cycle
@@ -177,13 +174,14 @@ class HookContext:
 		exc_type: type[BaseException] | None,
 		exc_val: BaseException | None,
 		exc_tb: Any,
-	):
+	) -> Literal[False]:
 		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
 
 	def namespace_for(self, hook: Hook[T]) -> HookNamespace[T]:
 		namespace = self.namespaces.get(hook.name)