pulse-framework 0.1.53__py3-none-any.whl → 0.1.55__py3-none-any.whl

pulse/cookies.py

@@ -5,6 +5,7 @@ from urllib.parse import urlparse
 
 from fastapi import Request, Response
 
+from pulse.env import PulseEnv
 from pulse.hooks.runtime import set_cookie
 
 if TYPE_CHECKING:
@@ -16,7 +17,7 @@ class Cookie:
 	name: str
 	_: KW_ONLY
 	domain: str | None = None
-	secure: bool = True
+	secure: bool | None = None
 	samesite: Literal["lax", "strict", "none"] = "lax"
 	max_age_seconds: int = 7 * 24 * 3600
 
@@ -33,6 +34,10 @@ class Cookie:
 		return cookies.get(self.name)
 
 	async def set_through_api(self, value: str):
+		if self.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
 		await set_cookie(
 			name=self.name,
 			value=value,
@@ -44,6 +49,10 @@ class Cookie:
 
 	def set_on_fastapi(self, response: Response, value: str) -> None:
 		"""Set the session cookie on a FastAPI Response-like object."""
+		if self.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
 		response.set_cookie(
 			key=self.name,
 			value=value,
@@ -62,6 +71,10 @@ class SetCookie(Cookie):
 
 	@classmethod
 	def from_cookie(cls, cookie: Cookie, value: str) -> "SetCookie":
+		if cookie.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. Ensure App.setup() ran or set Cookie(secure=True/False)."
+			)
 		return cls(
 			name=cookie.name,
 			value=value,
@@ -81,7 +94,7 @@ def session_cookie(
 		return Cookie(
 			name,
 			domain=None,
-			secure=False,
+			secure=None,
 			samesite="lax",
 			max_age_seconds=max_age_seconds,
 		)
@@ -146,6 +159,29 @@ def compute_cookie_domain(mode: "PulseMode", server_address: str) -> str | None:
 	return None
 
 
+def compute_cookie_secure(env: PulseEnv, server_address: str | None) -> bool:
+	scheme = urlparse(server_address or "").scheme.lower()
+	if scheme in ("https", "wss"):
+		secure = True
+	elif scheme in ("http", "ws"):
+		secure = False
+	else:
+		secure = None
+	if secure is None:
+		if env in ("prod", "ci"):
+			raise RuntimeError(
+				"Could not determine cookie security from server_address. "
+				+ "Use an explicit https:// server_address or set Cookie(secure=True/False)."
+			)
+		return False
+	if env in ("prod", "ci") and not secure:
+		raise RuntimeError(
+			"Refusing to use insecure cookies in prod/ci. "
+			+ "Use an https server_address or set Cookie(secure=True) explicitly."
+		)
+	return secure
+
+
 def cors_options(mode: "PulseMode", server_address: str) -> CORSOptions:
 	host = _parse_host(server_address) or "localhost"
 	opts: CORSOptions = {

pulse/env.py

@@ -4,7 +4,7 @@ Centralized environment variable definitions and typed accessors for Pulse.
 Preferred usage:
 
     from pulse.env import env
-    env.pulse_mode = "prod"
+    env.pulse_env = "prod"
     if env.running_cli:
         ...
 
@@ -20,7 +20,7 @@ from typing import Literal
 PulseEnv = Literal["dev", "ci", "prod"]
 
 # Keys
-ENV_PULSE_MODE = "PULSE_MODE"
+ENV_PULSE_ENV = "PULSE_ENV"
 ENV_PULSE_APP_FILE = "PULSE_APP_FILE"
 ENV_PULSE_APP_DIR = "PULSE_APP_DIR"
 ENV_PULSE_HOST = "PULSE_HOST"
@@ -42,14 +42,14 @@ class EnvVars:
 
 	@property
 	def pulse_env(self) -> PulseEnv:
-		value = (self._get(ENV_PULSE_MODE) or "dev").lower()
+		value = (self._get(ENV_PULSE_ENV) or "dev").lower()
 		if value not in ("dev", "ci", "prod"):
 			value = "dev"
 		return value
 
 	@pulse_env.setter
 	def pulse_env(self, value: PulseEnv) -> None:
-		self._set(ENV_PULSE_MODE, value)
+		self._set(ENV_PULSE_ENV, value)
 
 	# App file/dir
 	@property

pulse/hooks/init.py

@@ -11,6 +11,7 @@ from typing import Any, Literal, cast, override
 
 from pulse.helpers import getsourcecode
 from pulse.hooks.core import HookState, hooks
+from pulse.transpiler.errors import TranspileError
 
 # Storage keyed by (code object, lineno) of the `with ps.init()` call site.
 _init_hook = hooks.create("init_storage", lambda: InitState())
@@ -312,6 +313,10 @@ def rewrite_init_blocks(func: Callable[..., Any]) -> Callable[..., Any]:
 	"""Rewrite `with ps.init()` blocks in the provided function, if present."""
 
 	source = textwrap.dedent(getsourcecode(func))  # raises immediately if missing
+	try:
+		source_start_line = inspect.getsourcelines(func)[1]
+	except (OSError, TypeError):
+		source_start_line = None
 
 	if "init" not in source:  # quick prefilter, allow alias detection later
 		return func
@@ -320,6 +325,7 @@ def rewrite_init_blocks(func: Callable[..., Any]) -> Callable[..., Any]:
 
 	init_names, init_modules = _resolve_init_bindings(func)
 
+	target_def: ast.FunctionDef | ast.AsyncFunctionDef | None = None
 	# Remove decorators so the re-exec'd function isn't double-wrapped.
 	for node in ast.walk(tree):
 		if (
@@ -327,14 +333,59 @@ def rewrite_init_blocks(func: Callable[..., Any]) -> Callable[..., Any]:
 			and node.name == func.__name__
 		):
 			node.decorator_list = []
+			target_def = node
+
+	if target_def is None:
+		return func
 
 	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)"
-		)
+	init_items = _find_init_items(target_def.body, init_names, init_modules)
+	if len(init_items) > 1:
+		try:
+			filename = inspect.getsourcefile(func) or inspect.getfile(func)
+		except (TypeError, OSError):
+			filename = None
+		raise TranspileError(
+			"ps.init may only be used once per component render",
+			node=init_items[1].context_expr,
+			source=source,
+			filename=filename,
+			func_name=func.__name__,
+			source_start_line=source_start_line,
+		) from None
+
+	if init_items and init_items[0].optional_vars is not None:
+		try:
+			filename = inspect.getsourcefile(func) or inspect.getfile(func)
+		except (TypeError, OSError):
+			filename = None
+		raise TranspileError(
+			"ps.init does not support 'as' bindings",
+			node=init_items[0].optional_vars,
+			source=source,
+			filename=filename,
+			func_name=func.__name__,
+			source_start_line=source_start_line,
+		) from None
+
+	disallowed = _find_disallowed_control_flow(
+		target_def.body, init_names, init_modules
+	)
+	if disallowed is not None:
+		try:
+			filename = inspect.getsourcefile(func) or inspect.getfile(func)
+		except (TypeError, OSError):
+			filename = None
+		raise TranspileError(
+			"ps.init blocks cannot contain control flow (if/for/while/try/with/match)",
+			node=disallowed,
+			source=source,
+			filename=filename,
+			func_name=func.__name__,
+			source_start_line=source_start_line,
+		) from None
 
 	rewriter: ast.NodeTransformer
 	if _CAN_USE_CPYTHON:
@@ -373,19 +424,128 @@ def _contains_ps_init(
 	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)
+def _find_disallowed_control_flow(
+	body: Sequence[ast.stmt], init_names: set[str], init_modules: set[str]
+) -> ast.stmt | None:
+	disallowed: tuple[type[ast.AST], ...] = (
+		ast.If,
+		ast.For,
+		ast.AsyncFor,
+		ast.While,
+		ast.Try,
+		ast.With,
+		ast.AsyncWith,
+		ast.Match,
+	)
 	checker = _InitCallChecker(init_names, init_modules)
-	for node in ast.walk(tree):
-		if isinstance(node, ast.With):
+
+	class _Finder(ast.NodeVisitor):
+		found: ast.stmt | None
+
+		def __init__(self) -> None:
+			self.found = None
+
+		@override
+		def visit(self, node: ast.AST) -> Any:  # type: ignore[override]
+			if self.found is not None:
+				return None
+			if isinstance(node, disallowed):
+				self.found = cast(ast.stmt, node)
+				return None
+			return super().visit(node)
+
+		@override
+		def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_ClassDef(self, node: ast.ClassDef) -> Any:
+			return None
+
+	finder = _Finder()
+
+	class _WithFinder(ast.NodeVisitor):
+		@override
+		def visit_With(self, node: ast.With) -> Any:  # type: ignore[override]
 			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
+				for stmt in node.body:
+					finder.visit(stmt)
+					if finder.found is not None:
+						return None
+			self.generic_visit(node)
+
+		@override
+		def visit_AsyncWith(self, node: ast.AsyncWith) -> Any:  # type: ignore[override]
+			first = node.items[0] if node.items else None
+			if first and checker.is_init_call(first.context_expr):
+				for stmt in node.body:
+					finder.visit(stmt)
+					if finder.found is not None:
+						return None
+			self.generic_visit(node)
+
+		@override
+		def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_ClassDef(self, node: ast.ClassDef) -> Any:
+			return None
+
+	with_finder = _WithFinder()
+	for stmt in body:
+		with_finder.visit(stmt)
+		if finder.found is not None:
+			return finder.found
+	return None
+
+
+def _find_init_items(
+	body: Sequence[ast.stmt], init_names: set[str], init_modules: set[str]
+) -> list[ast.withitem]:
+	checker = _InitCallChecker(init_names, init_modules)
+	items: list[ast.withitem] = []
+
+	class _Finder(ast.NodeVisitor):
+		@override
+		def visit_With(self, node: ast.With) -> Any:  # type: ignore[override]
+			first = node.items[0] if node.items else None
+			if first and checker.is_init_call(first.context_expr):
+				items.append(first)
+			self.generic_visit(node)
+
+		@override
+		def visit_AsyncWith(self, node: ast.AsyncWith) -> Any:  # type: ignore[override]
+			first = node.items[0] if node.items else None
+			if first and checker.is_init_call(first.context_expr):
+				items.append(first)
+			self.generic_visit(node)
+
+		@override
+		def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
+			return None
+
+		@override
+		def visit_ClassDef(self, node: ast.ClassDef) -> Any:
+			return None
+
+	finder = _Finder()
+	for stmt in body:
+		finder.visit(stmt)
+	return items
 
 
 class _InitCallChecker:

pulse/hooks/state.py

@@ -0,0 +1,105 @@
+from collections.abc import Callable
+from typing import TypeVar, override
+
+from pulse.hooks.core import HookMetadata, HookState, hooks
+from pulse.state import State
+
+S = TypeVar("S", bound=State)
+
+
+class StateHookState(HookState):
+	__slots__ = ("instances", "called_keys")  # pyright: ignore[reportUnannotatedClassAttribute]
+	instances: dict[str, State]
+	called_keys: set[str]
+
+	def __init__(self) -> None:
+		super().__init__()
+		self.instances = {}
+		self.called_keys = set()
+
+	@override
+	def on_render_start(self, render_cycle: int) -> None:
+		super().on_render_start(render_cycle)
+		self.called_keys.clear()
+
+	def get_or_create_state(self, key: str, arg: State | Callable[[], State]) -> State:
+		if key in self.called_keys:
+			raise RuntimeError(
+				f"`pulse.state` can only be called once per component render with key='{key}'"
+			)
+		self.called_keys.add(key)
+
+		existing = self.instances.get(key)
+		if existing is not None:
+			# Dispose any State instances passed directly as args that aren't being used
+			if isinstance(arg, State) and arg is not existing:
+				try:
+					if not arg.__disposed__:
+						arg.dispose()
+				except RuntimeError:
+					# Already disposed, ignore
+					pass
+			return existing
+
+		# Create new state
+		instance = _instantiate_state(arg)
+		self.instances[key] = instance
+		return instance
+
+	@override
+	def dispose(self) -> None:
+		for instance in self.instances.values():
+			try:
+				if not instance.__disposed__:
+					instance.dispose()
+			except RuntimeError:
+				# Already disposed, ignore
+				pass
+		self.instances.clear()
+
+
+def _instantiate_state(arg: State | Callable[[], State]) -> State:
+	instance = arg() if callable(arg) else arg
+	if not isinstance(instance, State):
+		raise TypeError(
+			"`pulse.state` expects a State instance or a callable returning a State instance"
+		)
+	return instance
+
+
+def _state_factory():
+	return StateHookState()
+
+
+_state_hook = hooks.create(
+	"pulse:core.state",
+	_state_factory,
+	metadata=HookMetadata(
+		owner="pulse.core",
+		description="Internal storage for pulse.state hook",
+	),
+)
+
+
+def state(key: str, arg: S | Callable[[], S]) -> S:
+	"""Get or create a state instance associated with the given key.
+
+	Args:
+		key: A unique string key identifying this state within the component.
+		arg: A State instance or a callable that returns a State instance.
+
+	Returns:
+		The state instance (same instance on subsequent renders with the same key).
+
+	Raises:
+		ValueError: If key is empty.
+		RuntimeError: If called more than once per render with the same key.
+		TypeError: If arg is not a State or callable returning a State.
+	"""
+	if not key:
+		raise ValueError("state() requires a non-empty string key")
+	hook_state = _state_hook()
+	return hook_state.get_or_create_state(key, arg)  # pyright: ignore[reportReturnType]
+
+
+__all__ = ["state", "StateHookState"]

pulse/js/__init__.py

@@ -30,21 +30,22 @@ import importlib as _importlib
 from typing import Any as _Any
 from typing import NoReturn as _NoReturn
 
-from pulse.transpiler.builtins import obj as obj
+from pulse.js.obj import obj as obj
+from pulse.transpiler.nodes import EXPR_REGISTRY as _EXPR_REGISTRY
 from pulse.transpiler.nodes import UNDEFINED as _UNDEFINED
-from pulse.transpiler.nodes import Identifier as _Identifier
 
-# Namespace modules that resolve to Identifier
-_MODULE_EXPORTS_IDENTIFIER: dict[str, str] = {
+# Namespace modules - return JsModule from registry (handles both builtins and external)
+_MODULE_EXPORTS_NAMESPACE: dict[str, str] = {
 	"JSON": "pulse.js.json",
 	"Math": "pulse.js.math",
+	"React": "pulse.js.react",
 	"console": "pulse.js.console",
 	"window": "pulse.js.window",
 	"document": "pulse.js.document",
 	"navigator": "pulse.js.navigator",
 }
 
-# Regular modules that resolve via getattr
+# Class modules - return via getattr to get Class wrapper (emits `new ...`)
 _MODULE_EXPORTS_ATTRIBUTE: dict[str, str] = {
 	"Array": "pulse.js.array",
 	"Date": "pulse.js.date",
@@ -52,6 +53,7 @@ _MODULE_EXPORTS_ATTRIBUTE: dict[str, str] = {
 	"Map": "pulse.js.map",
 	"Object": "pulse.js.object",
 	"Promise": "pulse.js.promise",
+	"React": "pulse.js.react",
 	"RegExp": "pulse.js.regexp",
 	"Set": "pulse.js.set",
 	"String": "pulse.js.string",
@@ -92,10 +94,11 @@ def __getattr__(name: str) -> _Any:
 	if name in _export_cache:
 		return _export_cache[name]
 
-	# Check which dict contains the name
-	if name in _MODULE_EXPORTS_IDENTIFIER:
-		module = _importlib.import_module(_MODULE_EXPORTS_IDENTIFIER[name])
-		export = _Identifier(name)
+	# Namespace modules: return JsModule (handles attribute access via transpile_getattr)
+	if name in _MODULE_EXPORTS_NAMESPACE:
+		module = _importlib.import_module(_MODULE_EXPORTS_NAMESPACE[name])
+		export = _EXPR_REGISTRY[id(module)]
+	# Class modules: return Class wrapper via getattr (emits `new ...()`)
 	elif name in _MODULE_EXPORTS_ATTRIBUTE:
 		module = _importlib.import_module(_MODULE_EXPORTS_ATTRIBUTE[name])
 		export = getattr(module, name)

pulse/js/obj.py

@@ -0,0 +1,79 @@
+"""
+JavaScript object literal creation.
+
+Usage:
+    from pulse.js import obj
+
+    # Create plain JS objects (not Maps):
+    obj(a=1, b=2)          # -> { a: 1, b: 2 }
+
+    # With spread syntax:
+    obj(**base, c=3)       # -> { ...base, c: 3 }
+    obj(a=1, **base)       # -> { a: 1, ...base }
+
+    # Empty object:
+    obj()                  # -> {}
+
+Unlike dict() which transpiles to new Map(), obj() creates plain JavaScript
+object literals. Use this for React props, style objects, and anywhere you
+need a plain JS object.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.nodes import Expr, Object, Spread, spread_dict
+from pulse.transpiler.vdom import VDOMNode
+
+# TYPE_CHECKING avoids import cycle: Transpiler -> nodes -> Expr -> obj -> Transpiler
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+
+@dataclass(slots=True)
+class ObjTransformer(Expr):
+	"""Transformer for obj() with **spread support.
+
+	obj(key=value, ...) -> { key: value, ... }
+	obj(**base, key=value) -> { ...base, key: value }
+
+	Creates a plain JavaScript object literal.
+	Use this instead of dict() when you need a plain object (e.g., for React props).
+	"""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		raise TypeError("obj cannot be emitted directly - must be called")
+
+	@override
+	def render(self) -> VDOMNode:
+		raise TypeError("obj cannot be rendered - must be called")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		if args:
+			raise TranspileError("obj() only accepts keyword arguments")
+
+		props: list[tuple[str, Expr] | Spread] = []
+		for kw in keywords:
+			if kw.arg is None:
+				# **spread syntax
+				props.append(spread_dict(ctx.emit_expr(kw.value)))
+			else:
+				# key=value
+				props.append((kw.arg, ctx.emit_expr(kw.value)))
+
+		return Object(props)
+
+
+# Create singleton instance for use as a callable
+obj = ObjTransformer()

pulse/js/pulse.py

@@ -0,0 +1,112 @@
+"""
+Pulse UI client bindings for channel communication.
+
+Usage:
+    from pulse.js.pulse import usePulseChannel, ChannelBridge, PulseChannelResetError
+
+    @ps.javascript(jsx=True)
+    def MyChannelComponent(*, channel_id: str):
+        bridge = usePulseChannel(channel_id)
+
+        # Subscribe to events
+        useEffect(
+            lambda: bridge.on("server:notify", lambda payload: console.log(payload)),
+            [bridge],
+        )
+
+        # Emit events to server
+        def send_ping():
+            bridge.emit("client:ping", {"message": "hello"})
+
+        # Make requests to server
+        async def send_request():
+            response = await bridge.request("client:request", {"data": 123})
+            console.log(response)
+
+        return ps.div()[
+            ps.button(onClick=send_ping)["Send Ping"],
+            ps.button(onClick=send_request)["Send Request"],
+        ]
+"""
+
+from collections.abc import Awaitable as _Awaitable
+from collections.abc import Callable as _Callable
+from typing import Any as _Any
+from typing import TypeVar as _TypeVar
+
+from pulse.transpiler.js_module import JsModule
+
+T = _TypeVar("T")
+
+
+class PulseChannelResetError(Exception):
+	"""Error raised when a channel is closed or reset."""
+
+	pass
+
+
+class ChannelBridge:
+	"""A bridge for bidirectional communication between client and server.
+
+	Provides methods for emitting events, making requests, and subscribing
+	to server events on a specific channel.
+	"""
+
+	@property
+	def id(self) -> str:
+		"""The unique channel identifier."""
+		...
+
+	def emit(self, event: str, payload: _Any = None) -> None:
+		"""Emit an event to the server.
+
+		Args:
+		    event: The event name to emit.
+		    payload: Optional data to send with the event.
+		"""
+		...
+
+	def request(self, event: str, payload: _Any = None) -> _Awaitable[_Any]:
+		"""Make a request to the server and await a response.
+
+		Args:
+		    event: The event name to send.
+		    payload: Optional data to send with the request.
+
+		Returns:
+		    A Promise that resolves with the server's response.
+		"""
+		...
+
+	def on(self, event: str, handler: _Callable[[_Any], _Any]) -> _Callable[[], None]:
+		"""Subscribe to events from the server.
+
+		Args:
+		    event: The event name to listen for.
+		    handler: A callback function that receives the event payload.
+		        May be sync or async. For request events, the return value
+		        is sent back to the server.
+
+		Returns:
+		    A cleanup function that unsubscribes the handler.
+		"""
+		...
+
+
+def usePulseChannel(channel_id: str) -> ChannelBridge:
+	"""React hook to connect to a Pulse channel.
+
+	Must be called from within a React component. The channel connection
+	is automatically managed based on component lifecycle.
+
+	Args:
+	    channel_id: The unique identifier for the channel to connect to.
+
+	Returns:
+	    A ChannelBridge instance for interacting with the channel.
+	"""
+	...
+
+
+# Register as a JS module with named imports from pulse-ui-client
+JsModule.register(name="pulse", src="pulse-ui-client", values="named_import")