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

pulse/decorators.py

@@ -1,10 +1,17 @@
 # Separate file from reactive.py due to needing to import from state too
 
 import inspect
-from collections.abc import Callable, Coroutine
-from typing import Any, Protocol, TypeVar, overload
+from collections.abc import Awaitable, Callable
+from typing import Any, Concatenate, ParamSpec, Protocol, TypeVar, overload
 
-from pulse.query import QueryProperty, QueryPropertyWithInitial
+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,
@@ -18,6 +25,7 @@ from pulse.state import ComputedProperty, State, StateEffect
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound=State)
+P = ParamSpec("P")
 
 
 # -> @ps.computed The chalenge is:
@@ -58,7 +66,7 @@ def computed(fn: Callable[..., Any] | None = None, *, name: str | None = None):
 
 
 StateEffectFn = Callable[[TState], EffectCleanup | None]
-AsyncStateEffectFn = Callable[[TState], Coroutine[Any, Any, EffectCleanup | None]]
+AsyncStateEffectFn = Callable[[TState], Awaitable[EffectCleanup | None]]
 
 
 class EffectBuilder(Protocol):
@@ -171,75 +179,159 @@ def effect(
 # -----------------
 # Query decorator
 # -----------------
+
+
+# With initial (narrowed return type) - more specific overloads first
 @overload
 def query(
-	fn: Callable[[TState], Coroutine[Any, Any, T]],
+	fn: Callable[[TState], Awaitable[T]],
 	*,
-	keep_alive: bool = False,
+	key: Callable[[TState], tuple[Any, ...]] | None = None,
+	stale_time: float = 0.0,
+	gc_time: float | None = 300.0,
 	keep_previous_data: bool = False,
-) -> QueryProperty[T, TState]: ...
+	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, *, keep_alive: bool = False, keep_previous_data: bool = False
+	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], Coroutine[Any, Any, T]]], QueryProperty[T, TState]
+	[Callable[[TState], Awaitable[T]]], QueryPropertyWithInitial[T, TState]
 ]: ...
 
 
-# When an initial value is provided, the resulting property narrows data to non-None
 @overload
 def query(
-	fn: Callable[[TState], Coroutine[Any, Any, T]],
+	fn: Callable[[TState], Awaitable[T]],
 	*,
-	keep_alive: bool = False,
+	key: Callable[[TState], tuple[Any, ...]] | None = None,
+	stale_time: float = 0.0,
+	gc_time: float | None = 300.0,
 	keep_previous_data: bool = False,
-	initial: T,
-) -> QueryPropertyWithInitial[T, TState]: ...
+	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,
 	*,
-	keep_alive: bool = False,
+	key: Callable[[TState], tuple[Any, ...]] | None = None,
+	stale_time: float = 0.0,
+	gc_time: float | None = 300.0,
 	keep_previous_data: bool = False,
-	initial: T,
-) -> Callable[
-	[Callable[[TState], Coroutine[Any, Any, T]]], QueryPropertyWithInitial[T, TState]
-]: ...
+	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], Any] | None = None,
+	fn: Callable[[TState], Awaitable[T]] | None = None,
 	*,
-	keep_alive: bool = False,
+	key: Callable[[TState], tuple[Any, ...]] | None = None,
+	stale_time: float = 0.0,
+	gc_time: float | None = 300.0,
 	keep_previous_data: bool = False,
-	initial: Any = None,
-) -> (
-	QueryProperty[T, TState]
-	| QueryPropertyWithInitial[T, TState]
-	| Callable[
-		[Callable[[TState], Coroutine[Any, Any, T]]],
-		QueryProperty[T, TState] | QueryPropertyWithInitial[T, TState],
-	]
+	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], Coroutine[Any, Any, T]], /):
+	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)")
-		if initial is not None:
-			return QueryPropertyWithInitial(
-				func.__name__,
-				func,
-				keep_alive=keep_alive,
-				keep_previous_data=keep_previous_data,
-				initial=initial,
-			)
-		return QueryProperty(
+
+		prop_cls = QueryPropertyWithInitial if initial is not None else QueryProperty
+
+		return prop_cls(
 			func.__name__,
 			func,
-			keep_alive=keep_alive,
+			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,
 		)
 
 	if fn:

pulse/form.py

@@ -1,10 +1,9 @@
 import json
 import uuid
-from collections.abc import Callable, Coroutine
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import (
 	TYPE_CHECKING,
-	Any,
 	Never,
 	TypedDict,
 	Unpack,
@@ -16,7 +15,7 @@ from starlette.datastructures import FormData as StarletteFormData
 from starlette.datastructures import UploadFile
 
 from pulse.context import PulseContext
-from pulse.helpers import call_flexible, maybe_await
+from pulse.helpers import Disposable, call_flexible, maybe_await
 from pulse.hooks.core import HOOK_CONTEXT, HookMetadata, HookState, hooks
 from pulse.hooks.runtime import server_address
 from pulse.hooks.stable import stable
@@ -60,10 +59,10 @@ class FormRegistration:
 	render_id: str
 	route_path: str
 	session_id: str
-	on_submit: Callable[[FormData], Coroutine[Any, Any, None]]
+	on_submit: Callable[[FormData], Awaitable[None]]
 
 
-class FormRegistry:
+class FormRegistry(Disposable):
 	def __init__(self, render: "RenderSession") -> None:
 		self._render: "RenderSession" = render
 		self._handlers: dict[str, FormRegistration] = {}
@@ -73,7 +72,7 @@ class FormRegistry:
 		render_id: str,
 		route_id: str,
 		session_id: str,
-		on_submit: Callable[[FormData], Coroutine[Any, Any, None]],
+		on_submit: Callable[[FormData], Awaitable[None]],
 	) -> FormRegistration:
 		registration = FormRegistration(
 			uuid.uuid4().hex,
@@ -88,9 +87,9 @@ class FormRegistry:
 	def unregister(self, form_id: str) -> None:
 		self._handlers.pop(form_id, None)
 
+	@override
 	def dispose(self) -> None:
-		for form_id in list(self._handlers.keys()):
-			self.unregister(form_id)
+		self._handlers.clear()
 
 	async def handle_submit(
 		self,
@@ -203,7 +202,7 @@ class GeneratedFormProps(TypedDict):
 	onSubmit: Callable[[], None]
 
 
-class ManualForm:
+class ManualForm(Disposable):
 	_submit_signal: Signal[bool]
 	_render: "RenderSession"
 	_registration: FormRegistration | None
@@ -267,6 +266,7 @@ class ManualForm:
 		props.update(self.props())  # pyright: ignore[reportCallIssue, reportArgumentType]
 		return client_form_component(*children, key=key, **props)
 
+	@override
 	def dispose(self) -> None:
 		if self._registration is None:
 			return

pulse/helpers.py

@@ -2,13 +2,26 @@ import asyncio
 import inspect
 import os
 import socket
-from collections.abc import Awaitable, Callable, Coroutine
-from typing import Any, ParamSpec, Protocol, TypedDict, TypeVar, overload, override
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import (
+	Any,
+	ParamSpec,
+	Protocol,
+	Self,
+	TypedDict,
+	TypeVar,
+	overload,
+	override,
+)
 from urllib.parse import urlsplit
 
 from anyio import from_thread
 from fastapi import Request
 
+from pulse.env import env
+
 
 def values_equal(a: Any, b: Any) -> bool:
 	"""Robust equality that avoids ambiguous truth for DataFrames/ndarrays.
@@ -86,9 +99,34 @@ def data(**attrs: Any):
 
 
 # --- Async scheduling helpers (work from loop or sync threads) ---
+class Disposable(ABC):
+	__disposed__: bool = False
+
+	@abstractmethod
+	def dispose(self) -> None: ...
+
+	def __init_subclass__(cls, **kwargs: Any):
+		super().__init_subclass__(**kwargs)
+
+		if "dispose" in cls.__dict__:
+			original_dispose = cls.dispose
+
+			@wraps(original_dispose)
+			def wrapped_dispose(self: Self, *args: Any, **kwargs: Any):
+				if self.__disposed__:
+					if env.pulse_env == "dev":
+						cls_name = type(self).__name__
+						raise RuntimeError(
+							f"{self} (type={cls_name}) was disposed twice. This is likely a bug."
+						)
+					return
+				self.__disposed__ = True
+				return original_dispose(self, *args, **kwargs)
 
+			cls.dispose = wrapped_dispose
 
-def _running_under_pytest() -> bool:
+
+def is_pytest() -> bool:
 	"""Detect if running inside pytest using environment variables."""
 	return bool(os.environ.get("PYTEST_CURRENT_TEST")) or (
 		"PYTEST_XDIST_TESTRUNUID" in os.environ
@@ -109,12 +147,12 @@ def schedule_on_loop(callback: Callable[[], None]) -> None:
 		try:
 			from_thread.run(_runner)
 		except RuntimeError:
-			if not _running_under_pytest():
+			if not is_pytest():
 				raise
 
 
 def create_task(
-	coroutine: Coroutine[Any, Any, T],
+	coroutine: Awaitable[T],
 	*,
 	name: str | None = None,
 	on_done: Callable[[asyncio.Task[T]], None] | None = None,
@@ -126,16 +164,22 @@ def create_task(
 	"""
 
 	try:
-		loop = asyncio.get_running_loop()
-		task = loop.create_task(coroutine, name=name)
+		asyncio.get_running_loop()
+		# ensure_future accepts Awaitable and returns a Task when given a coroutine
+		task = asyncio.ensure_future(coroutine)
+		if name is not None:
+			task.set_name(name)
 		if on_done:
 			task.add_done_callback(on_done)
 		return task
 	except RuntimeError:
 
 		async def _runner():
-			loop = asyncio.get_running_loop()
-			task = loop.create_task(coroutine, name=name)
+			asyncio.get_running_loop()
+			# ensure_future accepts Awaitable and returns a Task when given a coroutine
+			task = asyncio.ensure_future(coroutine)
+			if name is not None:
+				task.set_name(name)
 			if on_done:
 				task.add_done_callback(on_done)
 			return task
@@ -143,7 +187,7 @@ def create_task(
 		try:
 			return from_thread.run(_runner)
 		except RuntimeError:
-			if _running_under_pytest():
+			if is_pytest():
 				return None  # pyright: ignore[reportReturnType]
 			raise
 
@@ -418,9 +462,29 @@ async def maybe_await(value: T | Awaitable[T]) -> T:
 def find_available_port(start_port: int = 8000, max_attempts: int = 100) -> int:
 	"""Find an available port starting from start_port."""
 	for port in range(start_port, start_port + max_attempts):
+		# First check if something is actively listening on the port
+		# by trying to connect to it (check both IPv4 and IPv6)
+		port_in_use = False
+		for family, addr in [(socket.AF_INET, "127.0.0.1"), (socket.AF_INET6, "::1")]:
+			try:
+				with socket.socket(family, socket.SOCK_STREAM) as test_socket:
+					test_socket.settimeout(0.1)
+					result = test_socket.connect_ex((addr, port))
+					# If connection succeeds (result == 0), something is listening
+					if result == 0:
+						port_in_use = True
+						break
+			except OSError:
+				# Connection failed, continue checking
+				pass
+
+		if port_in_use:
+			continue
+
+		# Port appears free, try to bind to it
+		# Allow reuse of addresses in TIME_WAIT state (matches uvicorn behavior)
 		try:
 			with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-				# Allow reuse of addresses in TIME_WAIT state (matches uvicorn behavior)
 				s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
 				s.bind(("localhost", port))
 				return port

pulse/hooks/core.py

@@ -3,9 +3,9 @@ import logging
 from collections.abc import Callable, Mapping
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic, TypeVar, override
 
-from pulse.helpers import call_flexible
+from pulse.helpers import Disposable, call_flexible
 
 logger = logging.getLogger(__name__)
 
@@ -37,7 +37,7 @@ class HookMetadata:
 	extra: Mapping[str, Any] | None = None
 
 
-class HookState:
+class HookState(Disposable):
 	"""Base class returned by hook factories."""
 
 	render_cycle: int
@@ -52,6 +52,7 @@ class HookState:
 		"""Called after the component render has completed."""
 		...
 
+	@override
 	def dispose(self) -> None:
 		"""Called when the hook instance is discarded."""
 		...

pulse/hooks/states.py

@@ -17,48 +17,106 @@ S9 = TypeVar("S9", bound=State)
 S10 = TypeVar("S10", bound=State)
 
 
+class StateNamespace:
+	__slots__: tuple[str, ...] = ("states", "key", "called")
+	states: tuple[State, ...]
+	key: str | None
+	called: bool
+
+	def __init__(self, key: str | None) -> None:
+		self.states = ()
+		self.key = key
+		self.called = False
+
+	def ensure_not_called(self) -> None:
+		if self.called:
+			key_msg = (
+				f" with key='{self.key}'" if self.key is not None else " without a key"
+			)
+			raise RuntimeError(
+				f"`pulse.states` can only be called once per component render{key_msg}"
+			)
+
+	def get_or_create_states(
+		self, args: tuple[State | Callable[[], State], ...]
+	) -> tuple[State, ...]:
+		if len(self.states) > 0:
+			# Reuse existing states
+			existing_states = self.states
+			# Validate that the number of arguments matches
+			if len(args) != len(existing_states):
+				key_msg = (
+					f" with key='{self.key}'"
+					if self.key is not None
+					else " without a key"
+				)
+				raise RuntimeError(
+					f"`pulse.states` called with {len(args)} argument(s) but was previously "
+					+ f"called with {len(existing_states)} argument(s){key_msg}. "
+					+ "The number of arguments must remain consistent across renders."
+				)
+			# Dispose any State instances passed directly as args that aren't being used
+			existing_set = set(existing_states)
+			for arg in args:
+				if isinstance(arg, State) and arg not in existing_set:
+					try:
+						if not arg.__disposed__:
+							arg.dispose()
+					except RuntimeError:
+						# Already disposed, ignore
+						pass
+			return existing_states
+
+		# Create new states
+		instances = tuple(_instantiate_state(arg) for arg in args)
+		self.states = instances
+		return instances
+
+	def dispose(self) -> None:
+		for state in self.states:
+			try:
+				if not state.__disposed__:
+					state.dispose()
+			except RuntimeError:
+				# Already disposed, ignore
+				pass
+		self.states = ()
+
+
 class StatesHookState(HookState):
-	__slots__: tuple[str, ...] = ("initialized", "states", "key", "_called")
-	initialized: bool
-	_called: bool
+	__slots__: tuple[str, ...] = ("namespaces",)
+	namespaces: dict[str | None, StateNamespace]
 
 	def __init__(self) -> None:
 		super().__init__()
-		self.initialized = False
-		self.states: tuple[State, ...] = ()
-		self.key: str | None = None
-		self._called = False
+		self.namespaces = {}
 
 	@override
 	def on_render_start(self, render_cycle: int) -> None:
 		super().on_render_start(render_cycle)
-		self._called = False
-
-	def replace(self, states: list[State], key: str | None) -> None:
-		self.dispose_states()
-		self.states = tuple(states)
-		self.key = key
-		self.initialized = True
-
-	def dispose_states(self) -> None:
-		for state in self.states:
-			state.dispose()
-		self.states = ()
-		self.initialized = False
-		self.key = None
+		if self.namespaces:
+			for namespace in self.namespaces.values():
+				namespace.called = False
+
+	def get_namespace(self, key: str | None) -> StateNamespace:
+		if key not in self.namespaces:
+			self.namespaces[key] = StateNamespace(key)
+		return self.namespaces[key]
+
+	def get_or_create_states(
+		self, args: tuple[State | Callable[[], State], ...], key: str | None
+	) -> tuple[State, ...]:
+		namespace = self.get_namespace(key)
+		namespace.ensure_not_called()
+		result = namespace.get_or_create_states(args)
+		namespace.called = True
+		return result
 
 	@override
 	def dispose(self) -> None:
-		self.dispose_states()
-
-	def ensure_not_called(self) -> None:
-		if self._called:
-			raise RuntimeError(
-				"`pulse.states` can only be called once per component render"
-			)
-
-	def mark_called(self) -> None:
-		self._called = True
+		for namespace in self.namespaces.values():
+			namespace.dispose()
+		self.namespaces.clear()
 
 
 def _instantiate_state(arg: State | Callable[[], State]) -> State:
@@ -219,29 +277,8 @@ def states(*args: S | Callable[[], S], key: str | None = ...) -> tuple[S, ...]:
 
 
 def states(*args: State | Callable[[], State], key: str | None = None):
-	state = _states_hook()
-	state.ensure_not_called()
-
-	if not state.initialized:
-		instances = [_instantiate_state(arg) for arg in args]
-		state.replace(instances, key)
-		state.mark_called()
-		result = state.states
-		return result[0] if len(result) == 1 else result
-
-	if key is not None and key != state.key:
-		instances = [_instantiate_state(arg) for arg in args]
-		state.replace(instances, key)
-		state.mark_called()
-		result = state.states
-		return result[0] if len(result) == 1 else result
-
-	for arg in args:
-		if isinstance(arg, State):
-			arg.dispose()
-
-	state.mark_called()
-	result = state.states
+	hook_state = _states_hook()
+	result = hook_state.get_or_create_states(args, key)
 	return result[0] if len(result) == 1 else result
 
 

pulse/messages.py

@@ -175,6 +175,6 @@ class Directives(TypedDict):
 	socketio: SocketIODirectives
 
 
-class PrerenderResult(TypedDict):
+class Prerender(TypedDict):
 	views: dict[str, ServerInitMessage | None]
 	directives: Directives