pulse-framework 0.1.72__tar.gz → 0.1.73__tar.gz

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.72
+Version: 0.1.73
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: fastapi>=0.128.0
 Requires-Dist: uvicorn>=0.24.0
@@ -15,7 +15,7 @@ Requires-Dist: urllib3>=2.6.3
 Requires-Dist: watchfiles>=1.1.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: aiohttp>=3.12.0
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
 # Pulse Python

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "pulse-framework"
-version = "0.1.72"
+version = "0.1.73"
 description = "Pulse - Full-stack framework for building real-time React applications in Python"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 dependencies = [
     "fastapi>=0.128.0",
     "uvicorn>=0.24.0",

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/__init__.py

@@ -60,6 +60,14 @@ from pulse.context import PulseContext as PulseContext
 from pulse.cookies import Cookie as Cookie
 from pulse.cookies import SetCookie as SetCookie
 
+# Debounce
+from pulse.debounce import (
+	Debounced as Debounced,
+)
+from pulse.debounce import (
+	debounced as debounced,
+)
+
 # Decorators
 from pulse.decorators import computed as computed
 from pulse.decorators import effect as effect
@@ -1200,7 +1208,7 @@ from pulse.hooks.core import (
 )
 
 # Hooks - Effects (import to register inline_effect_hook before registry locks)
-from pulse.hooks.effects import InlineEffectHookState as InlineEffectHookState
+from pulse.hooks.effects import EffectState as EffectState
 
 # Hooks - Init
 from pulse.hooks.init import (
@@ -1235,6 +1243,9 @@ from pulse.hooks.runtime import (
 from pulse.hooks.runtime import (
 	not_found as not_found,
 )
+from pulse.hooks.runtime import (
+	pulse_route as pulse_route,
+)
 from pulse.hooks.runtime import (
 	redirect as redirect,
 )
@@ -1259,7 +1270,7 @@ from pulse.hooks.runtime import (
 
 # Hooks - Setup
 from pulse.hooks.setup import (
-	SetupHookState as SetupHookState,
+	SetupState as SetupState,
 )
 from pulse.hooks.setup import (
 	setup as setup,
@@ -1271,7 +1282,7 @@ from pulse.hooks.stable import (
 	StableEntry as StableEntry,
 )
 from pulse.hooks.stable import (
-	StableRegistry as StableRegistry,
+	StableState as StableState,
 )
 
 # Hooks - Stable
@@ -1433,7 +1444,8 @@ from pulse.serializer import deserialize as deserialize
 from pulse.serializer import serialize as serialize
 
 # State and routing
-from pulse.state import State as State
+from pulse.state.query_param import QueryParam as QueryParam
+from pulse.state.state import State as State
 
 # Transpiler v2
 from pulse.transpiler.function import JsFunction as JsFunction

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/cli/processes.py

@@ -272,6 +272,8 @@ def _write_tagged_line(name: str, message: str, tag_mode: TagMode) -> None:
 		"Network: use --host to expose" in clean_message
 		or "press h + enter to show help" in clean_message
 		or "➜  Local:" in clean_message
+		or "/__manifest" in clean_message
+		or "?import" in clean_message
 	):
 		return
 

pulse_framework-0.1.73/src/pulse/debounce.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Generic, ParamSpec, TypeVar
+
+from pulse.context import PULSE_CONTEXT
+from pulse.scheduling import TimerHandleLike, later
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+@dataclass(frozen=True, slots=True)
+class Debounced(Generic[P, R]):
+	fn: Callable[P, R]
+	delay_ms: float
+	_handle: TimerHandleLike | asyncio.Handle | None = field(
+		default=None, init=False, repr=False, compare=False
+	)
+
+	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Any:
+		if self._handle is not None:
+			self._handle.cancel()
+
+		delay = self.delay_ms / 1000.0
+
+		def _run() -> None:
+			object.__setattr__(self, "_handle", None)
+			result = self.fn(*args, **kwargs)
+			if asyncio.iscoroutine(result):
+				loop = asyncio.get_running_loop()
+				task = loop.create_task(result)
+
+				def _log_task_exception(t: asyncio.Task[Any]) -> None:
+					try:
+						t.result()
+					except asyncio.CancelledError:
+						pass
+					except Exception as exc:
+						loop.call_exception_handler(
+							{
+								"message": "Unhandled exception in debounced() task",
+								"exception": exc,
+								"context": {"callback": self.fn},
+							}
+						)
+
+				task.add_done_callback(_log_task_exception)
+
+		if PULSE_CONTEXT.get() is not None:
+			handle = later(delay, _run)
+		else:
+			try:
+				loop = asyncio.get_running_loop()
+			except RuntimeError:
+				try:
+					loop = asyncio.get_event_loop()
+				except RuntimeError as exc:
+					raise RuntimeError("debounced() requires an event loop") from exc
+			handle = loop.call_later(delay, _run)
+
+		object.__setattr__(self, "_handle", handle)
+
+
+def debounced(fn: Callable[P, R], delay_ms: int | float) -> Debounced[P, R]:
+	"""Return a debounced callback marker (delay in milliseconds)."""
+	if not callable(fn):
+		raise TypeError("debounced() requires a callable")
+	if isinstance(delay_ms, bool) or not isinstance(delay_ms, (int, float)):
+		raise TypeError("debounced() delay must be a number (ms)")
+	if not math.isfinite(delay_ms) or delay_ms < 0:
+		raise ValueError("debounced() delay must be finite and >= 0")
+	return Debounced(fn=fn, delay_ms=float(delay_ms))
+
+
+__all__ = ["Debounced", "debounced"]

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/decorators.py

@@ -5,7 +5,7 @@ from collections.abc import Awaitable, Callable
 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.effects import effect_state
 from pulse.hooks.state import collect_component_identity
 from pulse.reactive import (
 	AsyncEffect,
@@ -16,7 +16,8 @@ from pulse.reactive import (
 	EffectFn,
 	Signal,
 )
-from pulse.state import ComputedProperty, State, StateEffect
+from pulse.state.property import ComputedProperty, StateEffect
+from pulse.state.state import State
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound=State)
@@ -336,7 +337,7 @@ def effect(
 		else:
 			identity = key
 
-		state = inline_effect_hook()
+		state = effect_state()
 		return state.get_or_create(cast(Any, identity), key, create_effect)
 
 	if fn is not None:

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/hooks/effects.py

@@ -5,7 +5,7 @@ from pulse.hooks.core import HookMetadata, HookState, hooks
 from pulse.reactive import REACTIVE_CONTEXT, AsyncEffect, Effect
 
 
-class InlineEffectHookState(HookState):
+class EffectState(HookState):
 	"""Stores inline effects keyed by function identity or explicit key."""
 
 	__slots__ = ("effects", "_seen_this_render")  # pyright: ignore[reportUnannotatedClassAttribute]
@@ -86,9 +86,9 @@ class InlineEffectHookState(HookState):
 		self._seen_this_render.clear()
 
 
-inline_effect_hook = hooks.create(
+effect_state = hooks.create(
 	"pulse:core.inline_effects",
-	lambda: InlineEffectHookState(),
+	factory=EffectState,
 	metadata=HookMetadata(
 		owner="pulse.core",
 		description="Storage for inline @ps.effect decorators in components",
@@ -97,6 +97,6 @@ inline_effect_hook = hooks.create(
 
 
 __all__ = [
-	"InlineEffectHookState",
-	"inline_effect_hook",
+	"EffectState",
+	"effect_state",
 ]

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/hooks/runtime.py

@@ -13,8 +13,8 @@ from typing import (
 from pulse.context import PulseContext
 from pulse.hooks.core import HOOK_CONTEXT
 from pulse.reactive_extensions import ReactiveDict
-from pulse.routing import RouteContext
-from pulse.state import State
+from pulse.routing import Layout, Route, RouteInfo
+from pulse.state.state import State
 
 
 class RedirectInterrupt(Exception):
@@ -47,11 +47,11 @@ class NotFoundInterrupt(Exception):
 	pass
 
 
-def route() -> RouteContext:
-	"""Get the current route context.
+def route() -> RouteInfo:
+	"""Get the current route info.
 
 	Returns:
-		RouteContext: Object with access to route parameters, path, and query.
+		RouteInfo: Mapping with access to route parameters, path, and query.
 
 	Raises:
 		RuntimeError: If called outside of a component render context.
@@ -61,8 +61,8 @@ def route() -> RouteContext:
 	```python
 	def user_page():
 	    r = ps.route()
-	    user_id = r.params.get("user_id")  # From /users/:user_id
-	    page = r.query.get("page", "1")    # From ?page=2
+	    user_id = r["pathParams"].get("user_id")  # From /users/:user_id
+	    page = r["queryParams"].get("page", "1")  # From ?page=2
 	    return m.Text(f"User {user_id}, Page {page}")
 	```
 	"""
@@ -71,7 +71,24 @@ def route() -> RouteContext:
 		raise RuntimeError(
 			"`pulse.route` can only be called within a component during rendering."
 		)
-	return ctx.route
+	return ctx.route.info
+
+
+def pulse_route() -> Route | Layout:
+	"""Get the current route definition.
+
+	Returns:
+		Route | Layout: The active route or layout definition.
+
+	Raises:
+		RuntimeError: If called outside of a component render context.
+	"""
+	ctx = PulseContext.get()
+	if not ctx or not ctx.route:
+		raise RuntimeError(
+			"`pulse.pulse_route` can only be called within a component during rendering."
+		)
+	return ctx.route.pulse_route
 
 
 def session() -> ReactiveDict[str, Any]:

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/hooks/setup.py

@@ -10,7 +10,7 @@ P = ParamSpec("P")
 T = TypeVar("T")
 
 
-class SetupHookState(HookState):
+class SetupState(HookState):
 	"""Internal hook state for the setup hook.
 
 	Manages the initialization, argument tracking, and lifecycle of
@@ -140,13 +140,9 @@ class SetupHookState(HookState):
 		return key
 
 
-def _setup_factory():
-	return SetupHookState()
-
-
-_setup_hook = hooks.create(
+setup_state = hooks.create(
 	"pulse:core.setup",
-	_setup_factory,
+	factory=SetupState,
 	metadata=HookMetadata(
 		owner="pulse.core",
 		description="Internal storage for pulse.setup hook",
@@ -195,7 +191,7 @@ def setup(init_func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
 		- Use ``ps.setup()`` directly when AST rewriting is problematic
 		- Arguments must be consistent across renders (same count and names)
 	"""
-	state = _setup_hook()
+	state = setup_state()
 	state.ensure_not_called()
 
 	key = state.consume_pending_key()
@@ -245,10 +241,10 @@ def setup_key(key: str) -> None:
 	"""
 	if not isinstance(key, str):
 		raise TypeError("setup_key() requires a string key")
-	state = _setup_hook()
+	state = setup_state()
 	if state.called_this_render:
 		raise RuntimeError("setup_key() must be called before setup() in a render")
 	state.set_pending_key(key)
 
 
-__all__ = ["setup", "setup_key", "SetupHookState"]
+__all__ = ["setup", "setup_key", "SetupState"]

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/hooks/stable.py

@@ -35,7 +35,7 @@ class StableEntry:
 		self.wrapper = wrapper
 
 
-class StableRegistry(HookState):
+class StableState(HookState):
 	"""Internal hook state that stores stable entries by key.
 
 	Maintains a dictionary of StableEntry objects, allowing stable
@@ -50,13 +50,9 @@ class StableRegistry(HookState):
 		self.entries: dict[str, StableEntry] = {}
 
 
-def _stable_factory(*_: object) -> StableRegistry:
-	return StableRegistry()
-
-
-_stable_hook = hooks.create(
+stable_state = hooks.create(
 	"pulse:core.stable",
-	_stable_factory,
+	factory=StableState,
 	metadata=HookMetadata(
 		owner="pulse.core",
 		description="Internal registry for pulse.stable values",
@@ -119,7 +115,7 @@ def stable(key: str, value: Any = MISSING) -> Any:
 	if not key:
 		raise ValueError("stable() requires a non-empty string key")
 
-	registry = _stable_hook()
+	registry = stable_state()
 	entry = registry.entries.get(key)
 
 	if value is not MISSING:
@@ -135,4 +131,4 @@ def stable(key: str, value: Any = MISSING) -> Any:
 	return entry.wrapper
 
 
-__all__ = ["stable", "StableRegistry", "StableEntry"]
+__all__ = ["stable", "StableState", "StableEntry"]

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/hooks/state.py

@@ -5,7 +5,7 @@ from typing import Any, TypeVar, override
 
 from pulse.component import is_component_code
 from pulse.hooks.core import HookMetadata, HookState, hooks
-from pulse.state import State
+from pulse.state.state import State
 
 S = TypeVar("S", bound=State)
 
@@ -99,10 +99,6 @@ def _instantiate_state(arg: State | Callable[[], State]) -> State:
 	return instance
 
 
-def _state_factory():
-	return StateHookState()
-
-
 def _frame_offset(frame: FrameType) -> int:
 	offset = frame.f_lasti
 	if offset < 0:
@@ -123,9 +119,9 @@ def collect_component_identity(
 	return tuple(identity[:1])
 
 
-_state_hook = hooks.create(
+state_hook = hooks.create(
 	"pulse:core.state",
-	_state_factory,
+	factory=StateHookState,
 	metadata=HookMetadata(
 		owner="pulse.core",
 		description="Internal storage for pulse.state hook",
@@ -185,7 +181,7 @@ def state(
 	else:
 		identity = resolved_key
 
-	hook_state = _state_hook()
+	hook_state = state_hook()
 	return hook_state.get_or_create_state(identity, resolved_key, resolved_arg)  # pyright: ignore[reportReturnType]
 
 

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/queries/common.py

@@ -13,7 +13,7 @@ from typing import (
 	override,
 )
 
-from pulse.state import State
+from pulse.state.state import State
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound="State")

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/queries/infinite_query.py

@@ -39,7 +39,8 @@ from pulse.queries.query import RETRY_DELAY_DEFAULT, QueryConfig
 from pulse.reactive import Computed, Effect, Signal, Untrack
 from pulse.reactive_extensions import ReactiveList, unwrap
 from pulse.scheduling import TimerHandleLike, create_task, later
-from pulse.state import InitializableProperty, State
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 T = TypeVar("T")
 TParam = TypeVar("TParam")

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/queries/mutation.py

@@ -13,7 +13,8 @@ from typing import (
 from pulse.helpers import call_flexible, maybe_await
 from pulse.queries.common import OnErrorFn, OnSuccessFn, bind_state
 from pulse.reactive import Signal
-from pulse.state import InitializableProperty, State
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 T = TypeVar("T")
 TState = TypeVar("TState", bound=State)

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/queries/query.py

@@ -37,7 +37,8 @@ from pulse.queries.common import (
 from pulse.queries.effect import AsyncQueryEffect
 from pulse.reactive import Computed, Effect, Signal, Untrack
 from pulse.scheduling import TimerHandleLike, create_task, is_pytest, later
-from pulse.state import InitializableProperty, State
+from pulse.state.property import InitializableProperty
+from pulse.state.state import State
 
 if TYPE_CHECKING:
 	from pulse.queries.protocol import QueryResult

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/render_session.py

@@ -34,7 +34,7 @@ from pulse.scheduling import (
 	TimerRegistry,
 	create_future,
 )
-from pulse.state import State
+from pulse.state.state import State
 from pulse.transpiler.id import next_id
 from pulse.transpiler.nodes import Expr
 
@@ -111,7 +111,7 @@ class RouteMount:
 	) -> None:
 		self.render = render
 		self.path = ensure_absolute_path(path)
-		self.route = RouteContext(route_info, route)
+		self.route = RouteContext(route_info, route, render)
 		self.effect = None
 		self._pulse_ctx = None
 		self.tree = RenderTree(route.render())

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/renderer.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from types import NoneType
 from typing import Any, NamedTuple, TypeAlias, cast
 
+from pulse.debounce import Debounced
 from pulse.helpers import values_equal
 from pulse.hooks.core import HookContext
 from pulse.transpiler import Import
@@ -33,7 +34,7 @@ from pulse.transpiler.vdom import (
 	VDOMPropValue,
 )
 
-PropValue: TypeAlias = Node | Callable[..., Any]
+PropValue: TypeAlias = Node | Callable[..., Any] | Debounced[Any, Any]
 
 FRAGMENT_TAG = ""
 MOUNT_PREFIX = "$$"
@@ -404,6 +405,21 @@ class Renderer:
 					updated[key] = value.render()
 				continue
 
+			if isinstance(value, Debounced):
+				eval_keys.add(key)
+				if isinstance(old_value, (Element, PulseNode)):
+					unmount_element(old_value)
+				if normalized is None:
+					normalized = current.copy()
+				normalized[key] = value
+				register_callback(self.callbacks, prop_path, value.fn)
+				prev_delay = (
+					old_value.delay_ms if isinstance(old_value, Debounced) else None
+				)
+				if prev_delay != value.delay_ms:
+					updated[key] = format_callback_placeholder(value.delay_ms)
+				continue
+
 			if callable(value):
 				eval_keys.add(key)
 				if isinstance(old_value, (Element, PulseNode)):
@@ -412,7 +428,7 @@ class Renderer:
 					normalized = current.copy()
 				normalized[key] = value
 				register_callback(self.callbacks, prop_path, value)
-				if not callable(old_value):
+				if not callable(old_value) or isinstance(old_value, Debounced):
 					updated[key] = CALLBACK_PLACEHOLDER
 				continue
 
@@ -483,6 +499,8 @@ def prop_requires_eval(value: PropValue) -> bool:
 		return True
 	if isinstance(value, Expr):
 		return True
+	if isinstance(value, Debounced):
+		return True
 	return callable(value)
 
 
@@ -530,6 +548,16 @@ def normalize_children(children: Children | None) -> list[Node]:
 	return out
 
 
+def format_callback_placeholder(delay_ms: float | None) -> str:
+	if delay_ms is None:
+		return CALLBACK_PLACEHOLDER
+	if delay_ms.is_integer():
+		suffix = str(int(delay_ms))
+	else:
+		suffix = format(delay_ms, "g")
+	return f"{CALLBACK_PLACEHOLDER}:{suffix}"
+
+
 def register_callback(
 	callbacks: Callbacks,
 	path: str,

{pulse_framework-0.1.72 → pulse_framework-0.1.73}/src/pulse/routing.py

@@ -1,12 +1,16 @@
 import re
 from collections.abc import Sequence
 from dataclasses import dataclass, field
-from typing import TypedDict, cast, override
+from typing import TYPE_CHECKING, TypedDict, cast, override
 
 from pulse.component import Component
 from pulse.env import env
 from pulse.reactive_extensions import ReactiveDict
 
+if TYPE_CHECKING:
+	from pulse.render_session import RenderSession
+	from pulse.state.query_param import QueryParamSync
+
 # angle brackets cannot appear in a regular URL path, this ensures no name conflicts
 LAYOUT_INDICATOR = "<layout>"
 
@@ -516,7 +520,8 @@ class RouteContext:
 	"""Runtime context for the current route.
 
 	Provides reactive access to the current route's URL components and
-	parameters. Accessible via `ps.route()` in components.
+	parameters. Available via `ps.route()` (route info) and `ps.pulse_route()`
+	(route definition) in components.
 
 	Attributes:
 		info: Current route info (reactive, auto-updates on navigation).
@@ -534,18 +539,27 @@ class RouteContext:
 		```python
 		@ps.component
 		def UserProfile():
-			ctx = ps.route()
-			user_id = ctx.pathParams.get("id")
+			info = ps.route()
+			user_id = info["pathParams"].get("id")
 			return ps.div(f"User: {user_id}")
 		```
 	"""
 
 	info: RouteInfo
 	pulse_route: Route | Layout
+	query_param_sync: "QueryParamSync"
 
-	def __init__(self, info: RouteInfo, pulse_route: Route | Layout):
+	def __init__(
+		self,
+		info: RouteInfo,
+		pulse_route: Route | Layout,
+		render: "RenderSession",
+	):
 		self.info = cast(RouteInfo, cast(object, ReactiveDict(info)))
 		self.pulse_route = pulse_route
+		from pulse.state.query_param import QueryParamSync
+
+		self.query_param_sync = QueryParamSync(render, self)
 
 	def update(self, info: RouteInfo) -> None:
 		"""Update the route info with new values.