pulse-framework 0.1.42__tar.gz → 0.1.43__tar.gz

{pulse_framework-0.1.42 → pulse_framework-0.1.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.42
+Version: 0.1.43
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: websockets>=12.0
 Requires-Dist: fastapi>=0.104.0

{pulse_framework-0.1.42 → pulse_framework-0.1.43}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pulse-framework"
-version = "0.1.42"
+version = "0.1.43"
 description = "Pulse - Full-stack framework for building real-time React applications in Python"
 readme = "README.md"
 requires-python = ">=3.11"

{pulse_framework-0.1.42 → pulse_framework-0.1.43}/src/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
@@ -1349,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_framework-0.1.43/src/pulse/decorators.py

@@ -0,0 +1,175 @@
+# Separate file from reactive.py due to needing to import from state too
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, Protocol, TypeVar, overload
+
+from pulse.reactive import (
+	AsyncEffect,
+	AsyncEffectFn,
+	Computed,
+	Effect,
+	EffectCleanup,
+	EffectFn,
+	Signal,
+)
+from pulse.state import ComputedProperty, State, StateEffect
+
+T = TypeVar("T")
+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
+def computed(
+	fn: Callable[[TState], T], *, name: str | None = None
+) -> ComputedProperty[T]: ...
+@overload
+def computed(
+	fn: None = None, *, name: str | None = None
+) -> Callable[[Callable[[], T]], Computed[T]]: ...
+
+
+def computed(fn: Callable[..., Any] | None = None, *, name: str | None = None):
+	# The type checker is not happy if I don't specify the `/` here.
+	def decorator(fn: Callable[..., Any], /):
+		sig = inspect.signature(fn)
+		params = list(sig.parameters.values())
+		# Check if it's a method with exactly one argument called 'self'
+		if len(params) == 1 and params[0].name == "self":
+			return ComputedProperty(fn.__name__, fn)
+		# If it has any arguments at all, it's not allowed (except for 'self')
+		if len(params) > 0:
+			raise TypeError(
+				f"@computed: Function '{fn.__name__}' must take no arguments or a single 'self' argument"
+			)
+		return Computed(fn, name=name or fn.__name__)
+
+	if fn is not None:
+		return decorator(fn)
+	else:
+		return decorator
+
+
+StateEffectFn = Callable[[TState], EffectCleanup | None]
+AsyncStateEffectFn = Callable[[TState], Awaitable[EffectCleanup | None]]
+
+
+class EffectBuilder(Protocol):
+	@overload
+	def __call__(self, fn: EffectFn | StateEffectFn[Any]) -> Effect: ...
+	@overload
+	def __call__(self, fn: AsyncEffectFn | AsyncStateEffectFn[Any]) -> AsyncEffect: ...
+	def __call__(
+		self,
+		fn: EffectFn | StateEffectFn[Any] | AsyncEffectFn | AsyncStateEffectFn[Any],
+	) -> Effect | AsyncEffect: ...
+
+
+@overload
+def effect(
+	fn: EffectFn,
+	*,
+	name: str | None = None,
+	immediate: bool = False,
+	lazy: bool = False,
+	on_error: Callable[[Exception], None] | None = None,
+	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
+) -> Effect: ...
+
+
+@overload
+def effect(
+	fn: AsyncEffectFn,
+	*,
+	name: str | None = None,
+	immediate: bool = False,
+	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.
+@overload
+def effect(fn: StateEffectFn[Any]) -> Effect: ...
+@overload
+def effect(fn: AsyncStateEffectFn[Any]) -> AsyncEffect: ...
+@overload
+def effect(
+	fn: None = None,
+	*,
+	name: str | None = None,
+	immediate: bool = False,
+	lazy: bool = False,
+	on_error: Callable[[Exception], None] | None = None,
+	deps: list[Signal[Any] | Computed[Any]] | None = None,
+	interval: float | None = None,
+) -> EffectBuilder: ...
+
+
+def effect(
+	fn: Callable[..., Any] | None = None,
+	*,
+	name: str | None = None,
+	immediate: bool = False,
+	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], /):
+		sig = inspect.signature(func)
+		params = list(sig.parameters.values())
+
+		# Disallow intermediate + async
+		if immediate and inspect.iscoroutinefunction(func):
+			raise ValueError("Async effects cannot have immediate=True")
+
+		if len(params) == 1 and params[0].name == "self":
+			return StateEffect(
+				func,
+				name=name,
+				immediate=immediate,
+				lazy=lazy,
+				on_error=on_error,
+				deps=deps,
+				interval=interval,
+			)
+
+		if len(params) > 0:
+			raise TypeError(
+				f"@effect: Function '{func.__name__}' must take no arguments or a single 'self' argument"
+			)
+
+		# This is a standalone effect function. Choose subclass based on async-ness
+		if inspect.iscoroutinefunction(func):
+			return AsyncEffect(
+				func,  # type: ignore[arg-type]
+				name=name or func.__name__,
+				lazy=lazy,
+				on_error=on_error,
+				deps=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:
+		return decorator(fn)
+	return decorator

{pulse_framework-0.1.42 → pulse_framework-0.1.43}/src/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