pulse-framework 0.1.52__py3-none-any.whl → 0.1.54__py3-none-any.whl

pulse/transpiler/nodes.py

@@ -88,19 +88,23 @@ class Expr(ABC):
 	def transpile_call(
 		self,
 		args: list[ast.expr],
-		kwargs: dict[str, ast.expr],
+		keywords: list[ast.keyword],
 		ctx: Transpiler,
 	) -> Expr:
 		"""Called when this expression is used as a function: expr(args).
 
 		Override to customize call behavior.
-		Default raises - most expressions are not callable.
+		Default emits a Call expression with args transpiled.
 
-		Args and kwargs are raw Python `ast.expr` nodes (not yet transpiled).
+		Args and keywords are raw Python AST nodes (not yet transpiled).
 		Use ctx.emit_expr() to convert them to Expr as needed.
+		Keywords with kw.arg=None are **spread syntax.
 		"""
-		if kwargs:
-			raise TranspileError("Keyword arguments not yet supported in v2 transpiler")
+		if keywords:
+			has_spread = any(kw.arg is None for kw in keywords)
+			if has_spread:
+				raise TranspileError("Spread (**expr) not supported in this call")
+			raise TranspileError("Keyword arguments not supported in call")
 		return Call(self, [ctx.emit_expr(a) for a in args])
 
 	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
@@ -341,10 +345,10 @@ class ExprWrapper(Expr):
 	def transpile_call(
 		self,
 		args: list[ast.expr],
-		kwargs: dict[str, ast.expr],
+		keywords: list[ast.keyword],
 		ctx: Transpiler,
 	) -> Expr:
-		return self.expr.transpile_call(args, kwargs, ctx)
+		return self.expr.transpile_call(args, keywords, ctx)
 
 	@override
 	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
@@ -395,28 +399,33 @@ class Jsx(ExprWrapper):
 	def transpile_call(
 		self,
 		args: list[ast.expr],
-		kwargs: dict[str, ast.expr],
+		keywords: list[ast.keyword],
 		ctx: "Transpiler",
 	) -> Expr:
 		"""Transpile a call to this JSX wrapper into an Element.
 
 		Positional args become children, keyword args become props.
-		The `key` kwarg is extracted specially.
+		The `key` kwarg is extracted specially. Spread (**expr) is supported.
 		"""
 		children: list[Node] = [ctx.emit_expr(a) for a in args]
 
-		props: dict[str, Prop] = {}
+		props: list[tuple[str, Prop] | Spread] = []
 		key: str | Expr | None = None
-		for k, v in kwargs.items():
-			v = ctx.emit_expr(v)
-			if k == "key":
-				# Accept any expression as key for transpilation
-				if isinstance(v, Literal) and isinstance(v.value, str):
-					key = v.value  # Optimize string literals
-				else:
-					key = v  # Keep as expression
+		for kw in keywords:
+			if kw.arg is None:
+				# **spread syntax
+				props.append(spread_dict(ctx.emit_expr(kw.value)))
 			else:
-				props[k] = v
+				k = kw.arg
+				v = ctx.emit_expr(kw.value)
+				if k == "key":
+					# Accept any expression as key for transpilation
+					if isinstance(v, Literal) and isinstance(v.value, str):
+						key = v.value  # Optimize string literals
+					else:
+						key = v  # Keep as expression
+				else:
+					props.append((k, v))
 
 		return Element(
 			tag=self.expr,
@@ -435,7 +444,7 @@ class Jsx(ExprWrapper):
 		"""
 
 		# Normal call: build Element
-		props: dict[str, object] = {}
+		props: dict[str, Any] = {}
 		key: str | None = None
 		children: list[Node] = list(args)
 
@@ -490,7 +499,9 @@ class Value(Expr):
 
 	@override
 	def render(self) -> VDOMNode:
-		raise TypeError("Value cannot be rendered as VDOMExpr; use coerce_json instead")
+		raise TypeError(
+			"Value cannot be rendered as VDOMExpr; unwrap with .value instead"
+		)
 
 
 class Element(Expr):
@@ -501,19 +512,23 @@ class Element(Expr):
 	- "div", "span", etc.: HTML element
 	- "$$ComponentId": Client component (registered in JS registry)
 	- Expr (Import, Member, etc.): Direct component reference for transpilation
+
+	Props can be either:
+	- tuple[str, Prop]: key-value pair
+	- Spread: spread expression (...expr)
 	"""
 
 	__slots__: tuple[str, ...] = ("tag", "props", "children", "key")
 
 	tag: str | Expr
-	props: dict[str, Any] | None
+	props: Sequence[tuple[str, Prop] | Spread] | dict[str, Any] | None
 	children: Sequence[Node] | None
 	key: str | Expr | None
 
 	def __init__(
 		self,
 		tag: str | Expr,
-		props: dict[str, Any] | None = None,
+		props: Sequence[tuple[str, Prop] | Spread] | dict[str, Any] | None = None,
 		children: Sequence[Node] | None = None,
 		key: str | Expr | None = None,
 	) -> None:
@@ -534,8 +549,6 @@ class Element(Expr):
 				warn_stacklevel=5,
 			)
 		self.key = key
-		if self.key is None and self.props:
-			self.key = self.props.pop("key", None)
 
 	def _emit_key(self, out: list[str]) -> None:
 		"""Emit key prop (string or expression)."""
@@ -583,10 +596,24 @@ class Element(Expr):
 		if self.key is not None:
 			self._emit_key(props_out)
 		if self.props:
-			for name, value in self.props.items():
+			# Handle both dict (from render path) and sequence (from transpilation)
+			# Dict case: items() yields tuple[str, Any], never Spread
+			# Sequence case: already list[tuple[str, Prop] | Spread]
+			props_iter: Iterable[tuple[str, Any]] | Sequence[tuple[str, Prop] | Spread]
+			if isinstance(self.props, dict):
+				props_iter = self.props.items()
+			else:
+				props_iter = self.props
+			for prop in props_iter:
 				if props_out:
 					props_out.append(" ")
-				_emit_jsx_prop(name, value, props_out)
+				if isinstance(prop, Spread):
+					props_out.append("{...")
+					prop.expr.emit(props_out)
+					props_out.append("}")
+				else:
+					name, value = prop
+					_emit_jsx_prop(name, value, props_out)
 
 		# Build children into a separate buffer to check if empty
 		children_out: list[str] = []
@@ -682,6 +709,27 @@ class Element(Expr):
 			key=self.key,
 		)
 
+	def props_dict(self) -> dict[str, Any]:
+		"""Convert props to dict for rendering.
+
+		Raises TypeError if props contain Spread (only valid in transpilation).
+		"""
+		if not self.props:
+			return {}
+		# Already a dict (from renderer reconciliation)
+		if isinstance(self.props, dict):
+			return self.props
+		# Sequence of (key, value) pairs or Spread
+		result: dict[str, Any] = {}
+		for prop in self.props:
+			if isinstance(prop, Spread):
+				raise TypeError(
+					"Element with spread props cannot be rendered; spread is only valid during transpilation"
+				)
+			k, v = prop
+			result[k] = v
+		return result
+
 	@override
 	def render(self) -> VDOMNode:
 		"""Element rendering is handled by Renderer.render_node(), not render().
@@ -938,25 +986,40 @@ class Array(Expr):
 
 @dataclass(slots=True)
 class Object(Expr):
-	"""JS object: { key: value }"""
+	"""JS object: { key: value, ...spread }
+
+	Props can be either:
+	- tuple[str, Expr]: key-value pair
+	- Spread: spread expression (...expr)
+	"""
 
-	props: Sequence[tuple[str, Expr]]
+	props: Sequence[tuple[str, Expr] | Spread]
 
 	@override
 	def emit(self, out: list[str]) -> None:
 		out.append("{")
-		for i, (k, v) in enumerate(self.props):
+		for i, prop in enumerate(self.props):
 			if i > 0:
 				out.append(", ")
-			out.append('"')
-			out.append(_escape_string(k))
-			out.append('": ')
-			v.emit(out)
+			if isinstance(prop, Spread):
+				prop.emit(out)
+			else:
+				k, v = prop
+				out.append('"')
+				out.append(_escape_string(k))
+				out.append('": ')
+				v.emit(out)
 		out.append("}")
 
 	@override
 	def render(self) -> VDOMNode:
-		return {"t": "object", "props": {k: v.render() for k, v in self.props}}
+		rendered_props: dict[str, VDOMNode] = {}
+		for prop in self.props:
+			if isinstance(prop, Spread):
+				raise TypeError("Object spread cannot be rendered to VDOM")
+			k, v = prop
+			rendered_props[k] = v.render()
+		return {"t": "object", "props": rendered_props}
 
 
 @dataclass(slots=True)
@@ -1214,6 +1277,21 @@ class Spread(Expr):
 		raise TypeError("Spread cannot be rendered as VDOMExpr directly")
 
 
+def spread_dict(expr: Expr) -> Spread:
+	"""Wrap a spread expression with Map-to-object conversion.
+
+	Python dicts transpile to Map, which has no enumerable own properties.
+	This wraps the spread with an IIFE that converts Map to object:
+		(...expr) -> ...($s => $s instanceof Map ? Object.fromEntries($s) : $s)(expr)
+
+	The IIFE ensures expr is evaluated only once.
+	"""
+	s = Identifier("$s")
+	is_map = Binary(s, "instanceof", Identifier("Map"))
+	as_obj = Call(Member(Identifier("Object"), "fromEntries"), [s])
+	return Spread(Call(Arrow(["$s"], Ternary(is_map, as_obj, s)), [expr]))
+
+
 @dataclass(slots=True)
 class New(Expr):
 	"""JS new expression: new Ctor(args)"""
@@ -1272,9 +1350,16 @@ class Transformer(Expr, Generic[_F]):
 	def transpile_call(
 		self,
 		args: list[ast.expr],
-		kwargs: dict[str, ast.expr],
+		keywords: list[ast.keyword],
 		ctx: Transpiler,
 	) -> Expr:
+		# Convert keywords to dict, reject spreads
+		kwargs: dict[str, ast.expr] = {}
+		for kw in keywords:
+			if kw.arg is None:
+				label = self.name or "Function"
+				raise TranspileError(f"{label} does not support **spread")
+			kwargs[kw.arg] = kw.value
 		if kwargs:
 			return self.fn(*args, ctx=ctx, **kwargs)
 		return self.fn(*args, ctx=ctx)

pulse/transpiler/py_module.py

@@ -70,7 +70,7 @@ class PyModule(Expr):
 	def transpile_call(
 		self,
 		args: list[ast.expr],
-		kwargs: dict[str, ast.expr],
+		keywords: list[ast.keyword],
 		ctx: Transpiler,
 	) -> Expr:
 		label = self.name or "PyModule"

pulse/transpiler/transpiler.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import ast
 import re
 from collections.abc import Callable, Mapping
-from typing import Any
+from typing import Any, cast
 
 from pulse.transpiler.builtins import BUILTINS, emit_method
 from pulse.transpiler.errors import TranspileError
@@ -31,6 +31,7 @@ from pulse.transpiler.nodes import (
 	If,
 	Literal,
 	Member,
+	New,
 	Return,
 	Spread,
 	Stmt,
@@ -465,7 +466,7 @@ class Transpiler:
 			return self._emit_dict(node)
 
 		if isinstance(node, ast.Set):
-			return Call(
+			return New(
 				Identifier("Set"),
 				[Array([self.emit_expr(e) for e in node.elts])],
 			)
@@ -515,14 +516,14 @@ class Transpiler:
 			arr = self._emit_comprehension_chain(
 				node.generators, lambda: self.emit_expr(node.elt)
 			)
-			return Call(Identifier("Set"), [arr])
+			return New(Identifier("Set"), [arr])
 
 		if isinstance(node, ast.DictComp):
 			pairs = self._emit_comprehension_chain(
 				node.generators,
 				lambda: Array([self.emit_expr(node.key), self.emit_expr(node.value)]),
 			)
-			return Call(Identifier("Map"), [pairs])
+			return New(Identifier("Map"), [pairs])
 
 		if isinstance(node, ast.Lambda):
 			return self._emit_lambda(node)
@@ -596,7 +597,7 @@ class Transpiler:
 			key_expr = self.emit_expr(k)
 			val_expr = self.emit_expr(v)
 			entries.append(Array([key_expr, val_expr]))
-		return Call(Identifier("Map"), [Array(entries)])
+		return New(Identifier("Map"), [Array(entries)])
 
 	def _emit_binop(self, node: ast.BinOp) -> Expr:
 		"""Emit a binary operation."""
@@ -720,37 +721,38 @@ class Transpiler:
 
 	def _emit_call(self, node: ast.Call) -> Expr:
 		"""Emit a function call."""
-		# Collect args and kwargs as raw AST values
-		args_raw = list(node.args)
-		kwargs_raw: dict[str, Any] = {}
-		for kw in node.keywords:
-			if kw.arg is None:
-				raise TranspileError(
-					"Spread props (**kwargs) not yet supported in v2 transpiler"
-				)
-			kwargs_raw[kw.arg] = kw.value
-
 		# Method call: obj.method(args) - try builtin method dispatch
 		if isinstance(node.func, ast.Attribute):
+			# Check for spreads - if present, skip builtin method handling
+			# (let transpile_call decide on spread support)
+			has_spread = any(kw.arg is None for kw in node.keywords)
+
 			obj = self.emit_expr(node.func.value)
 			method = node.func.attr
-			args: list[Expr] = [self.emit_expr(a) for a in args_raw]
-			kwargs: dict[str, Expr] = {
-				k: self.emit_expr(v) for k, v in kwargs_raw.items()
-			}
 
-			# Try builtin method handling with runtime checks
-			result = emit_method(obj, method, args, kwargs)
-			if result is not None:
-				return result
+			# Try builtin method handling only if no spreads
+			if not has_spread:
+				# Safe to cast: has_spread=False means all kw.arg are str (not None)
+				kwargs_raw: dict[str, Any] = {
+					cast(str, kw.arg): kw.value for kw in node.keywords
+				}
+				args: list[Expr] = [self.emit_expr(a) for a in node.args]
+				kwargs: dict[str, Expr] = {
+					k: self.emit_expr(v) for k, v in kwargs_raw.items()
+				}
+				result = emit_method(obj, method, args, kwargs)
+				if result is not None:
+					return result
 
 			# IMPORTANT: derive method expr via transpile_getattr
 			method_expr = obj.transpile_getattr(method, self)
-			return method_expr.transpile_call(args_raw, kwargs_raw, self)
+			return method_expr.transpile_call(
+				list(node.args), list(node.keywords), self
+			)
 
-		# Function call (or other callable expr)
+		# Function call - pass raw keywords (let callee decide on spread support)
 		callee = self.emit_expr(node.func)
-		return callee.transpile_call(args_raw, kwargs_raw, self)
+		return callee.transpile_call(list(node.args), list(node.keywords), self)
 
 	def _emit_attribute(self, node: ast.Attribute) -> Expr:
 		"""Emit an attribute access."""

pulse/user_session.py

@@ -61,6 +61,10 @@ class UserSession(Disposable):
 		# unwrap subscribes the effect to all signals in the session ReactiveDict
 		data = unwrap(self.data)
 		signed_cookie = app.session_store.encode(self.sid, data)
+		if app.cookie.secure is None:
+			raise RuntimeError(
+				"Cookie.secure is not resolved. This is likely an internal error. Ensure App.setup() ran before sessions."
+			)
 		self.set_cookie(
 			name=app.cookie.name,
 			value=signed_cookie,
@@ -83,6 +87,12 @@ class UserSession(Disposable):
 		self._queued_cookies.clear()
 		self.scheduled_cookie_refresh = False
 
+	def get_cookie_value(self, name: str) -> str | None:
+		cookie = self._queued_cookies.get(name)
+		if cookie is None:
+			return None
+		return cookie.value
+
 	def set_cookie(
 		self,
 		name: str,

pulse_framework-0.1.54.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: pulse-framework
+Version: 0.1.54
+Summary: Pulse - Full-stack framework for building real-time React applications in Python
+Requires-Dist: websockets>=12.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: mako>=1.3.10
+Requires-Dist: typer>=0.16.0
+Requires-Dist: python-socketio>=5.13.0
+Requires-Dist: rich>=13.7.1
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: watchfiles>=1.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Pulse Python
+
+Core Python framework for building full-stack reactive web apps with React frontends.
+
+## Architecture
+
+Server-driven UI model: Python components render to VDOM, synced to React via WebSocket. State changes trigger re-renders; diffs are sent to client.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Python Server                                                  │
+│  ┌──────────┐  ┌───────────────┐  ┌──────────────────────────┐  │
+│  │   App    │──│ RenderSession │──│ VDOM Renderer            │  │
+│  │ (FastAPI)│  │ (per browser) │  │ (diff & serialize)       │  │
+│  └──────────┘  └───────────────┘  └──────────────────────────┘  │
+│       │                │                      │                 │
+│       │         ┌──────┴───────┐              │                 │
+│       │         │    Hooks     │              │                 │
+│       │         │ (state/setup)│              │                 │
+│       │         └──────────────┘              │                 │
+└───────┼───────────────────────────────────────┼─────────────────┘
+        │ Socket.IO                             │ VDOM updates
+        ▼                                       ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Browser (React)                                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Folder Structure
+
+```
+src/pulse/
+├── app.py              # Main App class, FastAPI + Socket.IO setup
+├── channel.py          # Bidirectional real-time channels
+├── routing.py          # Route/Layout definitions, URL matching
+├── vdom.py             # VDOM node types (Element, Component, Node)
+├── renderer.py         # VDOM rendering and diffing
+├── render_session.py   # Per-browser session, manages mounted routes
+├── reactive.py         # Signal/Computed/Effect primitives
+├── reactive_extensions.py  # ReactiveList, ReactiveDict, ReactiveSet
+├── state.py            # State management
+├── serializer.py       # Python<->JSON serialization
+├── middleware.py       # Request middleware (prerender, connect, message)
+├── plugin.py           # Plugin interface for extensions
+├── form.py             # Form handling
+├── context.py          # PulseContext (request/session context)
+├── cookies.py          # Cookie management
+├── request.py          # PulseRequest abstraction
+├── user_session.py     # User session storage
+├── helpers.py          # Utilities (CSSProperties, later, repeat)
+├── decorators.py       # @computed, @effect decorators
+├── messages.py         # Client<->server message types
+├── react_component.py  # ReactComponent wrapper for JS libraries
+│
+├── hooks/              # Server-side hooks (like React hooks)
+│   ├── core.py         # Hook registry, HooksAPI
+│   ├── runtime.py      # session(), route(), navigate(), redirect()
+│   ├── states.py       # Reactive state hook
+│   ├── effects.py      # Side effects hook
+│   ├── setup.py        # Initialization hook
+│   ├── init.py         # One-time setup hook
+│   └── stable.py       # Memoization hook
+│
+├── queries/            # Data fetching (like TanStack Query)
+│   ├── query.py        # @query decorator
+│   ├── mutation.py     # @mutation decorator
+│   ├── infinite_query.py  # Pagination support
+│   ├── client.py       # QueryClient for cache management
+│   └── store.py        # Query state store
+│
+├── components/         # Built-in components
+│   ├── for_.py         # <For> loop component
+│   ├── if_.py          # <If> conditional component
+│   └── react_router.py # Link, Outlet for routing
+│
+├── html/               # HTML element bindings
+│   ├── tags.py         # div, span, button, etc.
+│   ├── props.py        # Typed props for HTML elements
+│   ├── events.py       # Event types (MouseEvent, etc.)
+│   └── elements.py     # Element type definitions
+│
+├── transpiler/         # Python->JS transpilation
+│   ├── function.py     # JsFunction, @javascript decorator
+│   └── imports.py      # Import/CssImport for client-side JS
+│
+├── codegen/            # Code generation for React Router
+│   ├── codegen.py      # Generates routes.ts, loaders
+│   └── templates/      # Mako templates for generated code
+│
+├── cli/                # Command-line interface
+│   ├── cmd.py          # pulse run, pulse build
+│   └── processes.py    # Dev server process management
+│
+└── js/                 # JS API stubs for transpilation
+    ├── window.py, document.py, navigator.py
+    ├── array.py, object.py, string.py
+    └── ...
+```
+
+## Key Concepts
+
+### App
+
+Entry point defining routes, middleware, plugins.
+
+```python
+import pulse as ps
+
+app = ps.App(routes=[
+    ps.Route("/", home),
+    ps.Layout("/dashboard", layout, children=[
+        ps.Route("/", dashboard),
+    ]),
+])
+```
+
+### Components
+
+Functions returning VDOM. Use `@ps.component` for stateful components.
+
+```python
+def greeting(name: str):
+    return ps.div(f"Hello, {name}!")
+
+@ps.component
+def counter():
+    count = ps.states.use(0)
+    return ps.button(f"Count: {count()}", onClick=lambda _: count.set(count() + 1))
+```
+
+### Reactivity
+
+- `Signal[T]` - reactive value
+- `Computed[T]` - derived value
+- `Effect` - side effect on change
+
+### Hooks
+
+Server-side hooks via `ps.states`, `ps.effects`, `ps.setup`:
+- `states.use(initial)` - reactive state
+- `effects.use(fn, deps)` - side effects
+- `setup.use(fn)` - one-time initialization
+
+### Queries
+
+Data fetching with caching:
+
+```python
+@ps.query
+async def fetch_user(id: str):
+    return await db.get_user(id)
+```
+
+### Channels
+
+Bidirectional real-time messaging:
+
+```python
+ch = ps.channel("chat")
+
+@ch.on("message")
+def handle_message(data):
+    ch.broadcast("new_message", data)
+```
+
+## Main Exports
+
+- `App`, `Route`, `Layout` - app/routing
+- `component` - server-side component decorator
+- `states`, `effects`, `setup`, `init` - hooks
+- `query`, `mutation`, `infinite_query` - data fetching
+- `channel` - real-time channels
+- `State`, `@computed`, `@effect` - reactivity
+- `ReactiveList`, `ReactiveDict`, `ReactiveSet` - reactive containers
+- `div`, `span`, `button`, ... - HTML elements
+- `For`, `If`, `Link`, `Outlet` - built-in components
+- `@react_component` - wrap JS components
+- `@javascript` - transpile Python to JS