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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.41
+Version: 0.1.42
 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.41 → pulse_framework-0.1.42}/pyproject.toml

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

{pulse_framework-0.1.41 → pulse_framework-0.1.42}/src/pulse/__init__.py

@@ -161,6 +161,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,
 )

{pulse_framework-0.1.41 → pulse_framework-0.1.42}/src/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_framework-0.1.41 → pulse_framework-0.1.42}/src/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)

pulse_framework-0.1.42/src/pulse/hooks/init.py

@@ -0,0 +1,460 @@
+from __future__ import annotations
+
+import ast
+import ctypes
+import functools
+import inspect
+import textwrap
+import types
+from collections.abc import Callable, Sequence
+from typing import Any, Literal, cast, override
+
+from pulse.hooks.core import HookState, hooks
+
+# Storage keyed by (code object, lineno) of the `with ps.init()` call site.
+_init_hook = hooks.create("init_storage", lambda: InitState())
+
+_CAN_USE_CPYTHON = hasattr(ctypes.pythonapi, "PyFrame_LocalsToFast")
+if _CAN_USE_CPYTHON:
+	PyFrame_LocalsToFast = ctypes.pythonapi.PyFrame_LocalsToFast
+	PyFrame_LocalsToFast.argtypes = [ctypes.py_object, ctypes.c_int]
+	PyFrame_LocalsToFast.restype = None
+
+
+def previous_frame() -> types.FrameType:
+	"""Get the previous frame (caller's frame) with assertions.
+
+	This skips the frame of this helper function and its immediate caller
+	to return the actual previous frame.
+	"""
+	current = inspect.currentframe()
+	assert current is not None, "currentframe() returned None"
+	# Skip this helper function's frame
+	caller = current.f_back
+	assert caller is not None, "f_back is None"
+	# Skip the caller's frame (e.g., __enter__) to get the actual previous frame
+	frame = caller.f_back
+	assert frame is not None, "f_back.f_back is None"
+	return frame
+
+
+class InitContext:
+	"""Context that captures locals on first render and restores thereafter."""
+
+	callsite: tuple[Any, int] | None
+	frame: types.FrameType | None
+	first_render: bool
+	pre_keys: set[str]
+	saved: dict[str, Any]
+
+	def __init__(self):
+		self.callsite = None
+		self.frame = None
+		self.first_render = False
+		self.pre_keys = set()
+		self.saved = {}
+
+	def __enter__(self):
+		self.frame = previous_frame()
+		self.pre_keys = set(self.frame.f_locals.keys())
+		# Use code object to disambiguate identical line numbers in different fns.
+		self.callsite = (self.frame.f_code, self.frame.f_lineno)
+
+		storage = _init_hook().storage
+		entry = storage.get(self.callsite)
+		if entry is None:
+			self.first_render = True
+			self.saved = {}
+		else:
+			self.first_render = False
+			self.saved = entry["vars"]
+		return self
+
+	def restore_variables(self):
+		if self.first_render:
+			return
+		frame = self.frame if self.frame is not None else previous_frame()
+		frame.f_locals.update(self.saved)
+		PyFrame_LocalsToFast(frame, 1)
+
+	def save(self, values: dict[str, Any]):
+		self.saved = values
+		assert self.callsite is not None, "callsite is None"
+		storage = _init_hook().storage
+		storage[self.callsite] = {"vars": values}
+
+	def _capture_new_locals(self) -> dict[str, Any]:
+		frame = self.frame
+		assert frame is not None, "frame is None"
+		captured = {}
+		for name, value in frame.f_locals.items():
+			if name in self.pre_keys:
+				continue
+			if value is self:
+				continue
+			captured[name] = value
+		return captured
+
+	def __exit__(
+		self,
+		exc_type: type[BaseException] | None,
+		exc_value: BaseException | None,
+		exc_tb: Any,
+	) -> Literal[False]:
+		if exc_type is None:
+			captured = self._capture_new_locals()
+			assert self.callsite is not None, "callsite  None"
+			storage = _init_hook().storage
+			storage[self.callsite] = {"vars": captured}
+		self.frame = None
+		return False
+
+
+def init() -> InitContext:
+	return InitContext()
+
+
+# ---------------------------- AST rewriting -------------------------------
+
+
+class InitCPythonRewriter(ast.NodeTransformer):
+	counter: int
+	_init_names: set[str]
+	_init_modules: set[str]
+
+	def __init__(self, init_names: set[str], init_modules: set[str]):
+		super().__init__()
+		self.counter = 0
+		self._init_names = init_names
+		self._init_modules = init_modules
+
+	@override
+	def visit_With(self, node: ast.With):
+		node = cast(ast.With, self.generic_visit(node))
+		if not node.items:
+			return node
+
+		item = node.items[0]
+		if self.is_init_call(item.context_expr):
+			ctx_name = f"_init_ctx_{self.counter}"
+			self.counter += 1
+			new_item = ast.withitem(
+				context_expr=item.context_expr,
+				optional_vars=ast.Name(id=ctx_name, ctx=ast.Store()),
+			)
+
+			restore_call = ast.Expr(
+				value=ast.Call(
+					func=ast.Attribute(
+						value=ast.Name(id=ctx_name, ctx=ast.Load()),
+						attr="restore_variables",
+						ctx=ast.Load(),
+					),
+					args=[],
+					keywords=[],
+				)
+			)
+
+			new_if = ast.If(
+				test=ast.Attribute(
+					value=ast.Name(id=ctx_name, ctx=ast.Load()),
+					attr="first_render",
+					ctx=ast.Load(),
+				),
+				body=node.body,
+				orelse=[restore_call],
+			)
+
+			return ast.With(
+				items=[new_item],
+				body=[new_if],
+				type_comment=getattr(node, "type_comment", None),
+			)
+
+		return node
+
+	def is_init_call(self, expr: ast.AST) -> bool:
+		if not isinstance(expr, ast.Call):
+			return False
+		func = expr.func
+		if isinstance(func, ast.Name) and func.id in self._init_names:
+			return True
+		if (
+			isinstance(func, ast.Attribute)
+			and isinstance(func.value, ast.Name)
+			and func.value.id in self._init_modules
+			and func.attr == "init"
+		):
+			return True
+		return False
+
+
+class InitFallbackRewriter(ast.NodeTransformer):
+	"""Rewrite using explicit rebinding (portable, no LocalsToFast)."""
+
+	counter: int
+	_init_names: set[str]
+	_init_modules: set[str]
+
+	def __init__(self, init_names: set[str], init_modules: set[str]):
+		super().__init__()
+		self.counter = 0
+		self._init_names = init_names
+		self._init_modules = init_modules
+
+	@override
+	def visit_With(self, node: ast.With):
+		node = cast(ast.With, self.generic_visit(node))
+		if not node.items:
+			return node
+
+		item = node.items[0]
+		if not self.is_init_call(item.context_expr):
+			return node
+
+		ctx_name = f"_init_ctx_{self.counter}"
+		self.counter += 1
+		new_item = ast.withitem(
+			context_expr=item.context_expr,
+			optional_vars=ast.Name(id=ctx_name, ctx=ast.Store()),
+		)
+
+		assigned = _collect_assigned_names(node.body)
+
+		save_call = ast.Expr(
+			value=ast.Call(
+				func=ast.Attribute(
+					value=ast.Name(id=ctx_name, ctx=ast.Load()),
+					attr="save",
+					ctx=ast.Load(),
+				),
+				args=[
+					ast.Dict(
+						keys=[ast.Constant(n) for n in assigned],
+						values=[ast.Name(id=n, ctx=ast.Load()) for n in assigned],
+					)
+				],
+				keywords=[],
+			)
+		)
+
+		restore_assigns: Sequence[ast.stmt] = [
+			ast.Assign(
+				targets=[ast.Name(id=name, ctx=ast.Store())],
+				value=ast.Subscript(
+					value=ast.Attribute(
+						value=ast.Name(id=ctx_name, ctx=ast.Load()),
+						attr="saved",
+						ctx=ast.Load(),
+					),
+					slice=ast.Constant(name),
+					ctx=ast.Load(),
+				),
+			)
+			for name in assigned
+		]
+
+		new_if = ast.If(
+			test=ast.Attribute(
+				value=ast.Name(id=ctx_name, ctx=ast.Load()),
+				attr="first_render",
+				ctx=ast.Load(),
+			),
+			body=node.body + [save_call],
+			orelse=list(restore_assigns),
+		)
+
+		return ast.With(
+			items=[new_item],
+			body=[new_if],
+			type_comment=getattr(node, "type_comment", None),
+		)
+
+	def is_init_call(self, expr: ast.AST) -> bool:
+		if not isinstance(expr, ast.Call):
+			return False
+		func = expr.func
+		if isinstance(func, ast.Name) and func.id in self._init_names:
+			return True
+		if (
+			isinstance(func, ast.Attribute)
+			and isinstance(func.value, ast.Name)
+			and func.value.id in self._init_modules
+			and func.attr == "init"
+		):
+			return True
+		return False
+
+
+def _collect_assigned_names(body: list[ast.stmt]) -> list[str]:
+	names: set[str] = set()
+
+	def add_target(target: ast.AST):
+		if isinstance(target, ast.Name):
+			names.add(target.id)
+		elif isinstance(target, (ast.Tuple, ast.List)):
+			for elt in target.elts:
+				add_target(elt)
+
+	for stmt in body:
+		if isinstance(stmt, ast.Assign):
+			for target in stmt.targets:
+				add_target(target)
+		elif isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+			names.add(stmt.target.id)
+		elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+			names.add(stmt.name)
+	return list(names)
+
+
+def rewrite_init_blocks(func: Callable[..., Any]) -> Callable[..., Any]:
+	"""Rewrite `with ps.init()` blocks in the provided function, if present."""
+
+	source = _get_source(func)  # raises immediately if missing
+
+	if "init" not in source:  # quick prefilter, allow alias detection later
+		return func
+
+	tree = ast.parse(source)
+
+	init_names, init_modules = _resolve_init_bindings(func)
+
+	# Remove decorators so the re-exec'd function isn't double-wrapped.
+	for node in ast.walk(tree):
+		if (
+			isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+			and node.name == func.__name__
+		):
+			node.decorator_list = []
+
+	if not _contains_ps_init(tree, init_names, init_modules):
+		return func
+
+	if _has_disallowed_control_flow(tree, init_names, init_modules):
+		raise RuntimeError(
+			"ps.init blocks cannot contain control flow (if/for/while/try/with/match)"
+		)
+
+	rewriter: ast.NodeTransformer
+	if _CAN_USE_CPYTHON:
+		rewriter = InitCPythonRewriter(init_names, init_modules)
+	else:
+		rewriter = InitFallbackRewriter(init_names, init_modules)
+
+	tree = rewriter.visit(tree)
+	ast.fix_missing_locations(tree)
+
+	filename = inspect.getsourcefile(func) or "<rewrite>"
+	compiled = compile(tree, filename=filename, mode="exec")
+
+	global_ns = dict(func.__globals__)
+	closure_vars = inspect.getclosurevars(func)
+	global_ns.update(closure_vars.nonlocals)
+	# Ensure `ps` resolves during exec.
+	if "ps" not in global_ns:
+		try:
+			import pulse as ps
+
+			global_ns["ps"] = ps
+		except Exception:
+			pass
+	local_ns: dict[str, Any] = {}
+	exec(compiled, global_ns, local_ns)
+	rewritten = local_ns.get(func.__name__) or global_ns[func.__name__]
+	functools.update_wrapper(rewritten, func)
+	return rewritten
+
+
+def _contains_ps_init(
+	tree: ast.AST, init_names: set[str], init_modules: set[str]
+) -> bool:
+	checker = _InitCallChecker(init_names, init_modules)
+	return checker.contains_init(tree)
+
+
+def _has_disallowed_control_flow(
+	tree: ast.AST, init_names: set[str], init_modules: set[str]
+) -> bool:
+	disallowed = (ast.If, ast.For, ast.While, ast.Try, ast.With, ast.Match)
+	checker = _InitCallChecker(init_names, init_modules)
+	for node in ast.walk(tree):
+		if isinstance(node, ast.With):
+			first = node.items[0] if node.items else None
+			if first and checker.is_init_call(first.context_expr):
+				continue
+		if isinstance(node, disallowed):
+			return True
+	return False
+
+
+class _InitCallChecker:
+	init_names: set[str]
+	init_modules: set[str]
+
+	def __init__(self, init_names: set[str], init_modules: set[str]):
+		self.init_names = init_names
+		self.init_modules = init_modules
+
+	def is_init_call(self, expr: ast.AST) -> bool:
+		if not isinstance(expr, ast.Call):
+			return False
+		func = expr.func
+		if isinstance(func, ast.Name) and func.id in self.init_names:
+			return True
+		if (
+			isinstance(func, ast.Attribute)
+			and isinstance(func.value, ast.Name)
+			and func.value.id in self.init_modules
+			and func.attr == "init"
+		):
+			return True
+		return False
+
+	def contains_init(self, tree: ast.AST) -> bool:
+		for node in ast.walk(tree):
+			if self.is_init_call(node):
+				return True
+		return False
+
+
+def _get_source(func: Callable[..., Any]) -> str:
+	try:
+		return textwrap.dedent(inspect.getsource(func))
+	except OSError as exc:
+		src = getattr(func, "__source__", None)
+		if src is None:
+			raise RuntimeError(
+				f"ps.init rewrite failed: unable to read source ({exc})"
+			) from exc
+		return textwrap.dedent(src)
+
+
+def _resolve_init_bindings(func: Callable[..., Any]) -> tuple[set[str], set[str]]:
+	"""Find names/modules that resolve to pulse.init in the function scope."""
+
+	init_names: set[str] = set()
+	init_modules: set[str] = set()
+
+	closure = inspect.getclosurevars(func)
+	scopes = [func.__globals__, closure.nonlocals, closure.globals]
+
+	for scope in scopes:
+		for name, val in scope.items():
+			if val is init:
+				init_names.add(name)
+			try:
+				if getattr(val, "init", None) is init:
+					init_modules.add(name)
+			except Exception:
+				continue
+
+	return init_names, init_modules
+
+
+class InitState(HookState):
+	def __init__(self) -> None:
+		self.storage: dict[tuple[Any, int], dict[str, Any]] = {}
+
+	@override
+	def dispose(self) -> None:
+		self.storage.clear()

{pulse_framework-0.1.41 → pulse_framework-0.1.42}/src/pulse/react_component.py

@@ -535,10 +535,11 @@ class ComponentRegistry:
 		exc_type: type[BaseException] | None,
 		exc_val: BaseException | None,
 		exc_tb: Any,
-	):
+	) -> Literal[False]:
 		if self._token:
 			COMPONENT_REGISTRY.reset(self._token)
 			self._token = None
+		return False
 
 
 COMPONENT_REGISTRY: ContextVar[ComponentRegistry] = ContextVar(

{pulse_framework-0.1.41 → pulse_framework-0.1.42}/src/pulse/reactive.py

@@ -6,6 +6,7 @@ from contextvars import ContextVar, Token
 from typing import (
 	Any,
 	Generic,
+	Literal,
 	ParamSpec,
 	TypeVar,
 	override,
@@ -675,11 +676,12 @@ class Batch:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_traceback: Any,
-	):
+	) -> Literal[False]:
 		self.flush()
 		# Restore previous reactive context
 		if self._token:
 			REACTIVE_CONTEXT.reset(self._token)
+		return False
 
 
 class GlobalBatch(Batch):
@@ -755,10 +757,11 @@ class Scope:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_traceback: Any,
-	):
+	) -> Literal[False]:
 		# Restore previous reactive context
 		if self._token:
 			REACTIVE_CONTEXT.reset(self._token)
+		return False
 
 
 class Untrack(Scope): ...
@@ -801,8 +804,9 @@ class ReactiveContext:
 		exc_type: type[BaseException] | None,
 		exc_value: BaseException | None,
 		exc_tb: Any,
-	):
+	) -> Literal[False]:
 		REACTIVE_CONTEXT.reset(self._tokens.pop())
+		return False
 
 
 def epoch():

{pulse_framework-0.1.41 → pulse_framework-0.1.42}/src/pulse/vdom.py

@@ -23,6 +23,7 @@ from typing import (
 )
 
 from pulse.hooks.core import HookContext
+from pulse.hooks.init import rewrite_init_blocks
 
 # ============================================================================
 # Core VDOM
@@ -291,7 +292,8 @@ def component(
 	fn: "Callable[P, Element] | None" = None, *, name: str | None = None
 ) -> "Component[P] | Callable[[Callable[P, Element]], Component[P]]":
 	def decorator(fn: Callable[P, Element]):
-		return Component(fn, name)
+		rewritten = rewrite_init_blocks(fn)
+		return Component(rewritten, name)
 
 	if fn is not None:
 		return decorator(fn)