pulse-framework 0.1.72__py3-none-any.whl → 0.1.74__py3-none-any.whl

pulse/{state.py → state/state.py}

@@ -5,223 +5,23 @@ This module provides the base State class and reactive property system
 that enables automatic re-rendering when state changes.
 """
 
-import inspect
-from abc import ABC, ABCMeta, abstractmethod
-from collections.abc import Callable, Iterator
+import sys
+from abc import ABC, ABCMeta
+from collections.abc import Iterator
 from enum import IntEnum
-from typing import Any, Generic, Never, TypeVar, override
+from types import SimpleNamespace
+from typing import Any, get_type_hints, override
 
 from pulse.helpers import Disposable
-from pulse.reactive import (
-	AsyncEffect,
-	Computed,
-	Effect,
-	Scope,
-	Signal,
-)
+from pulse.reactive import Computed, Effect, Scope, Signal
 from pulse.reactive_extensions import ReactiveProperty
-
-T = TypeVar("T")
-
-
-class StateProperty(ReactiveProperty[Any]):
-	"""
-	Descriptor for reactive properties on State classes.
-
-	StateProperty wraps a Signal and provides automatic reactivity for
-	class attributes. When a property is read, it subscribes to the underlying
-	Signal. When written, it updates the Signal and triggers re-renders.
-
-	This class is typically not used directly. Instead, declare typed attributes
-	on a State subclass, and the StateMeta metaclass will automatically convert
-	them into StateProperty instances.
-
-	Example:
-
-	```python
-	class MyState(ps.State):
-	    count: int = 0  # Automatically becomes a StateProperty
-	    name: str = "default"
-
-	state = MyState()
-	state.count = 5  # Updates the underlying Signal
-	print(state.count)  # Reads from the Signal, subscribes to changes
-	```
-	"""
-
-	pass
-
-
-class InitializableProperty(ABC):
-	@abstractmethod
-	def initialize(self, state: "State", name: str) -> Any: ...
-
-
-class ComputedProperty(Generic[T]):
-	"""
-	Descriptor for computed (derived) properties on State classes.
-
-	ComputedProperty wraps a method that derives its value from other reactive
-	properties. The computed value is cached and only recalculated when its
-	dependencies change. Reading a computed property subscribes to it.
-
-	Created automatically when using the @ps.computed decorator on a State method.
-
-	Args:
-		name: The property name (used for debugging and the private storage key).
-		fn: The method that computes the value. Must take only `self` as argument.
-
-	Example:
-
-	```python
-	class MyState(ps.State):
-	    count: int = 0
-
-	    @ps.computed
-	    def doubled(self):
-	        return self.count * 2
-
-	state = MyState()
-	print(state.doubled)  # 0
-	state.count = 5
-	print(state.doubled)  # 10 (automatically recomputed)
-	```
-	"""
-
-	name: str
-	private_name: str
-	fn: "Callable[[State], T]"
-
-	def __init__(self, name: str, fn: "Callable[[State], T]"):
-		self.name = name
-		self.private_name = f"__computed_{name}"
-		# The computed_template holds the original method
-		self.fn = fn
-
-	def get_computed(self, obj: Any) -> Computed[T]:
-		if not isinstance(obj, State):
-			raise ValueError(
-				f"Computed property {self.name} defined on a non-State class"
-			)
-		if not hasattr(obj, self.private_name):
-			# Create the computed on first access for this instance
-			bound_method = self.fn.__get__(obj, obj.__class__)
-			new_computed = Computed(
-				bound_method,
-				name=f"{obj.__class__.__name__}.{self.name}",
-			)
-			setattr(obj, self.private_name, new_computed)
-		return getattr(obj, self.private_name)
-
-	def __get__(self, obj: Any, objtype: Any = None) -> T:
-		if obj is None:
-			return self  # pyright: ignore[reportReturnType]
-
-		return self.get_computed(obj).read()
-
-	def __set__(self, obj: Any, value: Any) -> Never:
-		raise AttributeError(f"Cannot set computed property '{self.name}'")
-
-
-class StateEffect(Generic[T], InitializableProperty):
-	"""
-	Descriptor for side effects on State classes.
-
-	StateEffect wraps a method that performs side effects when its dependencies
-	change. The effect is initialized when the State instance is created and
-	disposed when the State is disposed.
-
-	Created automatically when using the @ps.effect decorator on a State method.
-	Supports both sync and async methods.
-
-		Args:
-			fn: The effect function. Must take only `self` as argument.
-			        Can return a cleanup function that runs before the next execution
-			        or when the effect is disposed.
-		name: Debug name for the effect. Defaults to "ClassName.method_name".
-		immediate: If True, run synchronously when scheduled (sync effects only).
-		lazy: If True, don't run on creation; wait for first dependency change.
-		on_error: Callback for handling errors during effect execution.
-		deps: Explicit dependencies. If provided, auto-tracking is disabled.
-		interval: Re-run interval in seconds for polling effects.
-
-	Example:
-
-	```python
-	class MyState(ps.State):
-	    count: int = 0
-
-	    @ps.effect
-	    def log_count(self):
-	        print(f"Count changed to: {self.count}")
-
-	    @ps.effect
-	    async def fetch_data(self):
-	        data = await api.fetch(self.query)
-	        self.data = data
-
-	    @ps.effect
-	    def subscribe(self):
-	        unsub = event_bus.subscribe(self.handle_event)
-	        return unsub  # Cleanup function
-	```
-	"""
-
-	fn: "Callable[[State], T]"
-	name: str | None
-	immediate: bool
-	on_error: "Callable[[Exception], None] | None"
-	lazy: bool
-	deps: "list[Signal[Any] | Computed[Any]] | None"
-	update_deps: bool | None
-	interval: float | None
-
-	def __init__(
-		self,
-		fn: "Callable[[State], T]",
-		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,
-		update_deps: bool | None = None,
-		interval: float | None = None,
-	):
-		self.fn = fn
-		self.name = name
-		self.immediate = immediate
-		self.on_error = on_error
-		self.lazy = lazy
-		self.deps = deps
-		self.update_deps = update_deps
-		self.interval = interval
-
-	@override
-	def initialize(self, state: "State", name: str):
-		bound_method = self.fn.__get__(state, state.__class__)
-		# Select sync/async effect type based on bound method
-		if inspect.iscoroutinefunction(bound_method):
-			effect: Effect = AsyncEffect(
-				bound_method,  # type: ignore[arg-type]
-				name=self.name or f"{state.__class__.__name__}.{name}",
-				lazy=self.lazy,
-				on_error=self.on_error,
-				deps=self.deps,
-				update_deps=self.update_deps,
-				interval=self.interval,
-			)
-		else:
-			effect = Effect(
-				bound_method,  # type: ignore[arg-type]
-				name=self.name or f"{state.__class__.__name__}.{name}",
-				immediate=self.immediate,
-				lazy=self.lazy,
-				on_error=self.on_error,
-				deps=self.deps,
-				update_deps=self.update_deps,
-				interval=self.interval,
-			)
-		setattr(state, name, effect)
+from pulse.state.property import (
+	ComputedProperty,
+	InitializableProperty,
+	StateEffect,
+	StateProperty,
+)
+from pulse.state.query_param import QueryParam, QueryParamProperty, extract_query_param
 
 
 class StateMeta(ABCMeta):
@@ -258,18 +58,62 @@ class StateMeta(ABCMeta):
 		namespace: dict[str, Any],
 		**kwargs: Any,
 	):
-		annotations = namespace.get("__annotations__", {})
+		declared_annotations = dict(namespace.get("__annotations__", {}))
+		cls = super().__new__(mcs, name, bases, namespace)
+		resolved_annotations: dict[str, Any] = {}
+		if declared_annotations:
+			module = sys.modules.get(cls.__module__)
+			globalns = module.__dict__ if module else {}
+			if "QueryParam" not in globalns:
+				globalns["QueryParam"] = QueryParam
+			localns = dict(cls.__dict__)
+			try:
+				hints = get_type_hints(
+					cls,
+					globalns=globalns,
+					localns=localns,
+				)
+			except Exception:
+				hints = None
+			if hints is not None:
+				for key, value in declared_annotations.items():
+					resolved_annotations[key] = hints.get(key, value)
+			else:
+				for key, value in declared_annotations.items():
+					try:
+						holder = SimpleNamespace(__annotations__={key: value})
+						resolved = get_type_hints(
+							holder,
+							globalns=globalns,
+							localns=localns,
+						).get(key, value)
+					except Exception:
+						resolved = value
+					resolved_annotations[key] = resolved
 
 		# 1) Turn annotated fields into StateProperty descriptors
-		for attr_name in annotations:
+		for attr_name, annotation in resolved_annotations.items():
 			# Do not wrap private/dunder attributes as reactive
 			if attr_name.startswith("_"):
 				continue
-			default_value = namespace.get(attr_name)
-			namespace[attr_name] = StateProperty(attr_name, default_value)
+			default_value = cls.__dict__.get(attr_name)
+			value_type, is_query_param = extract_query_param(annotation)
+			if is_query_param:
+				cls.__annotations__[attr_name] = value_type
+				prop = QueryParamProperty(
+					attr_name,
+					default_value,
+					value_type,
+				)
+				setattr(cls, attr_name, prop)
+				prop.__set_name__(cls, attr_name)
+			else:
+				prop = StateProperty(attr_name, default_value)
+				setattr(cls, attr_name, prop)
+				prop.__set_name__(cls, attr_name)
 
 		# 2) Turn non-annotated plain values into StateProperty descriptors
-		for attr_name, value in list(namespace.items()):
+		for attr_name, value in list(cls.__dict__.items()):
 			# Do not wrap private/dunder attributes as reactive
 			if attr_name.startswith("_"):
 				continue
@@ -285,9 +129,11 @@ class StateMeta(ABCMeta):
 			):
 				continue
 			# Convert plain class var into a StateProperty
-			namespace[attr_name] = StateProperty(attr_name, value)
+			prop = StateProperty(attr_name, value)
+			setattr(cls, attr_name, prop)
+			prop.__set_name__(cls, attr_name)
 
-		return super().__new__(mcs, name, bases, namespace)
+		return cls
 
 	@override
 	def __call__(cls, *args: Any, **kwargs: Any):

pulse/transpiler/__init__.py

@@ -106,6 +106,11 @@ from pulse.transpiler.nodes import While as While
 # Emit
 from pulse.transpiler.nodes import emit as emit
 
+# Parse helpers
+from pulse.transpiler.parse import ParsedSource as ParsedSource
+from pulse.transpiler.parse import get_ast as get_ast
+from pulse.transpiler.parse import get_source as get_source
+
 # Transpiler
 from pulse.transpiler.transpiler import Transpiler as Transpiler
 from pulse.transpiler.transpiler import transpile as transpile

pulse/transpiler/function.py

@@ -7,8 +7,8 @@ and JsFunction which wraps transpiled functions with their dependencies.
 from __future__ import annotations
 
 import ast
+import dis
 import inspect
-import textwrap
 import types as pytypes
 from collections.abc import Callable
 from dataclasses import dataclass, field
@@ -25,7 +25,6 @@ from typing import (
 	override,
 )
 
-from pulse.helpers import getsourcecode
 from pulse.transpiler.errors import TranspileError
 from pulse.transpiler.id import next_id, reset_id_counter
 from pulse.transpiler.imports import Import
@@ -38,6 +37,7 @@ from pulse.transpiler.nodes import (
 	Return,
 	to_js_identifier,
 )
+from pulse.transpiler.parse import clear_parse_cache, get_ast, get_source
 from pulse.transpiler.transpiler import Transpiler
 from pulse.transpiler.vdom import VDOMExpr
 
@@ -63,6 +63,7 @@ def clear_function_cache() -> None:
 
 	FUNCTION_CACHE.clear()
 	CONSTANT_REGISTRY.clear()
+	clear_parse_cache()
 	clear_import_registry()
 	clear_asset_registry()
 	reset_id_counter()
@@ -137,33 +138,17 @@ def _transpile_function_body(
 	deps: dict[str, Expr],
 	*,
 	jsx: bool = False,
-) -> tuple[Function | Arrow, str]:
+) -> Function | Arrow:
 	"""Shared transpilation logic for JsFunction and JsxFunction.
 
-	Returns the transpiled Function/Arrow node and the source code.
+	Returns the transpiled Function/Arrow node.
 	"""
 	# Get and parse source
-	src = getsourcecode(fn)
-	src = textwrap.dedent(src)
-	try:
-		source_start_line = inspect.getsourcelines(fn)[1]
-	except (OSError, TypeError):
-		source_start_line = None
-	module = ast.parse(src)
-
-	# Find the function definition
-	fndefs = [
-		n for n in module.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
-	]
-	if not fndefs:
-		raise TranspileError("No function definition found in source")
-	fndef = fndefs[-1]
-
-	# Get filename for error messages and source file resolution
-	try:
-		filename = inspect.getfile(fn)
-	except (TypeError, OSError):
-		filename = None
+	parsed = get_source(fn)
+	src = parsed.source
+	fndef = get_ast(fn)
+	filename = parsed.filename
+	source_start_line = parsed.source_start_line
 
 	# Transpile with source context for errors
 	try:
@@ -181,7 +166,7 @@ def _transpile_function_body(
 			) from None
 		raise
 
-	return result, src
+	return result
 
 
 @dataclass(slots=True, init=False)
@@ -238,7 +223,7 @@ class JsFunction(Expr, Generic[*Args, R]):
 		if self._transpiled is not None:
 			return self._transpiled
 
-		result, _ = _transpile_function_body(self.fn, self.deps)
+		result = _transpile_function_body(self.fn, self.deps)
 
 		# Convert Arrow to Function if needed, and set the name
 		if isinstance(result, Function):
@@ -326,7 +311,7 @@ class JsxFunction(Expr, Generic[P, R]):
 		if self._transpiled is not None:
 			return self._transpiled
 
-		result, _ = _transpile_function_body(self.fn, self.deps, jsx=True)
+		result = _transpile_function_body(self.fn, self.deps, jsx=True)
 
 		# JSX transpilation always returns Function (never Arrow)
 		assert isinstance(result, Function), (
@@ -376,7 +361,6 @@ def analyze_code_object(
 	    - effective_globals: dict mapping names to their values (includes closure vars)
 	    - all_names: set of all names referenced in the code (including nested functions)
 	"""
-	import dis
 
 	code = fn.__code__
 
@@ -443,14 +427,54 @@ def analyze_deps(fn: Callable[..., Any]) -> dict[str, Expr]:
 	"""
 	# Analyze code object and resolve globals + closure vars
 	effective_globals, all_names = analyze_code_object(fn)
+	code_names = set(all_names)
+	default_names: set[str] = set()
+	default_name_values: dict[str, Any] = {}
+
+	# Include names referenced only in default expressions (not in bytecode)
+	try:
+		args = get_ast(fn).args
+		pos_defaults = list(args.defaults)
+		py_defaults = fn.__defaults__ or ()
+		num_args = len(args.args)
+		num_defaults = len(pos_defaults)
+		for i, _arg in enumerate(args.args):
+			default_idx = i - (num_args - num_defaults)
+			if default_idx < 0 or default_idx >= len(pos_defaults):
+				continue
+			default_node = pos_defaults[default_idx]
+			if isinstance(default_node, ast.Name) and default_idx < len(py_defaults):
+				default_name_values[default_node.id] = py_defaults[default_idx]
+			for node in ast.walk(default_node):
+				if isinstance(node, ast.Name):
+					default_names.add(node.id)
+
+		py_kwdefaults = fn.__kwdefaults__ or {}
+		for i, kwarg in enumerate(args.kwonlyargs):
+			default_node = args.kw_defaults[i]
+			if default_node is None:
+				continue
+			if isinstance(default_node, ast.Name) and kwarg.arg in py_kwdefaults:
+				default_name_values[default_node.id] = py_kwdefaults[kwarg.arg]
+			for node in ast.walk(default_node):
+				if isinstance(node, ast.Name):
+					default_names.add(node.id)
+	except (OSError, TypeError, SyntaxError, TranspileError):
+		pass
+
+	all_names.update(default_names)
+	default_only_names = default_names - code_names
 
 	# Build dependencies dictionary - all values are Expr
 	deps: dict[str, Expr] = {}
 
+	missing = object()
 	for name in all_names:
-		value = effective_globals.get(name)
-
-		if value is None:
+		if name in default_only_names and name in default_name_values:
+			value = default_name_values[name]
+		else:
+			value = effective_globals.get(name, missing)
+		if value is missing:
 			# Not in globals - could be a builtin or unresolved
 			# For now, skip - builtins will be handled by the transpiler
 			# TODO: Add builtin support

pulse/transpiler/nodes.py

@@ -1150,6 +1150,15 @@ class Unary(Expr):
 			out.append(" ")
 		else:
 			out.append(self.op)
+		if (
+			self.op in {"+", "-"}
+			and isinstance(self.operand, Unary)
+			and self.operand.op == self.op
+		):
+			out.append("(")
+			self.operand.emit(out)
+			out.append(")")
+			return
 		_emit_paren(self.operand, self.op, "unary", out)
 
 	@override
@@ -1508,7 +1517,7 @@ class If(Stmt):
 
 @dataclass(slots=True)
 class ForOf(Stmt):
-	"""JS for-of loop: for (const x of iter) { ... }
+	"""JS for-of loop: for (x of iter) { ... }
 
 	target can be a single name or array pattern for destructuring: [a, b]
 	"""
@@ -1519,7 +1528,7 @@ class ForOf(Stmt):
 
 	@override
 	def emit(self, out: list[str]) -> None:
-		out.append("for (const ")
+		out.append("for (")
 		out.append(self.target)
 		out.append(" of ")
 		self.iter.emit(out)
@@ -1574,17 +1583,32 @@ class Assign(Stmt):
 	op: None for =, or "+", "-", etc. for augmented assignment
 	"""
 
-	target: str
+	target: str | Identifier | Member | Subscript
 	value: Expr
 	declare: Lit["let", "const"] | None = None
 	op: str | None = None  # For augmented: +=, -=, etc.
 
+	@staticmethod
+	def _validate_target(target: object) -> None:
+		if not isinstance(target, (str, Identifier, Member, Subscript)):
+			raise TypeError(
+				"Assign target must be str, Identifier, Member, or Subscript; "
+				+ f"got {type(target).__name__}: {target!r}"
+			)
+
+	def __post_init__(self) -> None:
+		self._validate_target(self.target)
+
 	@override
 	def emit(self, out: list[str]) -> None:
+		self._validate_target(self.target)
 		if self.declare:
 			out.append(self.declare)
 			out.append(" ")
-		out.append(self.target)
+		if isinstance(self.target, str):
+			out.append(self.target)
+		else:
+			_emit_primary(self.target, out)
 		if self.op:
 			out.append(" ")
 			out.append(self.op)
@@ -1595,6 +1619,21 @@ class Assign(Stmt):
 		out.append(";")
 
 
+@dataclass(slots=True)
+class LetDecl(Stmt):
+	"""JS let declaration: let a, b;"""
+
+	names: Sequence[str]
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		if not self.names:
+			return
+		out.append("let ")
+		out.append(", ".join(self.names))
+		out.append(";")
+
+
 @dataclass(slots=True)
 class ExprStmt(Stmt):
 	"""JS expression statement: expr;"""

pulse/transpiler/parse.py

@@ -0,0 +1,70 @@
+"""Cached parsing helpers for transpiler source inspection."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pulse.helpers import getsourcecode
+from pulse.transpiler.errors import TranspileError
+
+
+@dataclass(slots=True)
+class ParsedSource:
+	source: str
+	filename: str | None
+	source_start_line: int | None
+
+
+_SOURCE_CACHE: dict[Callable[..., Any], ParsedSource] = {}
+_AST_CACHE: dict[Callable[..., Any], ast.FunctionDef | ast.AsyncFunctionDef] = {}
+
+
+def clear_parse_cache() -> None:
+	_SOURCE_CACHE.clear()
+	_AST_CACHE.clear()
+
+
+def get_source(fn: Callable[..., Any]) -> ParsedSource:
+	cached = _SOURCE_CACHE.get(fn)
+	if cached is not None:
+		return cached
+
+	src = getsourcecode(fn)
+	src = textwrap.dedent(src)
+	try:
+		source_start_line = inspect.getsourcelines(fn)[1]
+	except (OSError, TypeError):
+		source_start_line = None
+	try:
+		filename = inspect.getfile(fn)
+	except (TypeError, OSError):
+		filename = None
+
+	parsed = ParsedSource(
+		source=src,
+		filename=filename,
+		source_start_line=source_start_line,
+	)
+	_SOURCE_CACHE[fn] = parsed
+	return parsed
+
+
+def get_ast(fn: Callable[..., Any]) -> ast.FunctionDef | ast.AsyncFunctionDef:
+	cached = _AST_CACHE.get(fn)
+	if cached is not None:
+		return cached
+
+	module = ast.parse(get_source(fn).source)
+	fndefs = [
+		n for n in module.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+	]
+	if not fndefs:
+		raise TranspileError("No function definition found in source")
+	fndef = fndefs[-1]
+	_AST_CACHE[fn] = fndef
+	return fndef