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

pulse/transpiler/js_module.py

@@ -1,4 +1,4 @@
-"""Core infrastructure for JavaScript module bindings.
+"""Core infrastructure for JavaScript module bindings in transpiler.
 
 JS modules are Python modules that map to JavaScript modules/builtins.
 Registration is done by calling register_js_module() from within the module itself.
@@ -6,269 +6,278 @@ Registration is done by calling register_js_module() from within the module itse
 
 from __future__ import annotations
 
+import ast
 import inspect
 import sys
-from collections.abc import Callable
 from dataclasses import dataclass, field
-from types import FunctionType, ModuleType
-from typing import Any, ClassVar, Literal, TypeVar, override
+from typing import Literal, override
 
-from pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.errors import TranspileError
 from pulse.transpiler.imports import Import
-from pulse.transpiler.nodes import JSExpr, JSIdentifier, JSMember, JSNew
+from pulse.transpiler.nodes import (
+	Expr,
+	Identifier,
+	Member,
+	New,
+)
+from pulse.transpiler.transpiler import Transpiler
+from pulse.transpiler.vdom import VDOMNode
+
+_MODULE_DUNDERS = frozenset(
+	{
+		"__name__",
+		"__file__",
+		"__doc__",
+		"__package__",
+		"__path__",
+		"__cached__",
+		"__loader__",
+		"__spec__",
+		"__builtins__",
+		"__annotations__",
+	}
+)
+
+
+@dataclass(slots=True)
+class Class(Expr):
+	"""Expr wrapper that emits calls as `new ...(...)`.
+
+	Must also behave like the wrapped expression for attribute access,
+	so patterns like `Promise.resolve(...)` work even if `Promise(...)` emits
+	as `new Promise(...)`.
+	"""
+
+	ctor: Expr
+	name: str = ""
 
-# Track functions marked as constructors (by id, since we delete them)
-CONSTRUCTORS: set[int] = set()
+	@override
+	def emit(self, out: list[str]) -> None:
+		self.ctor.emit(out)
 
-F = TypeVar("F", bound=Callable[..., object])
+	@override
+	def render(self) -> VDOMNode:
+		return self.ctor.render()
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		kwargs: dict[str, ast.expr],
+		ctx: Transpiler,
+	) -> Expr:
+		if kwargs:
+			raise TranspileError("Keyword arguments not supported in constructor call")
+		return New(self.ctor, [ctx.emit_expr(a) for a in args])
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		# Convention: trailing underscore escapes Python keywords (e.g. from_ -> from, is_ -> is)
+		js_attr = attr[:-1] if attr.endswith("_") else attr
+		return Member(self.ctor, js_attr)
 
 
 @dataclass(frozen=True)
-class JsModule:
-	"""Configuration for a JavaScript module binding.
+class JsModule(Expr):
+	"""Expr representing a JavaScript module binding.
 
 	Attributes:
-		name: The JavaScript identifier (e.g., "Math", "lodash")
+		name: The JavaScript identifier for the module binding (e.g., "Math", "React"),
+			or None for "global identifier" modules with no module expression.
+		py_name: Python module name for error messages (e.g., "pulse.js.math")
 		src: Import source path. None for builtins.
 		kind: Import kind - "default" or "namespace"
 		values: How attribute access is expressed:
 			- "member": Access as property (e.g., React.useState)
 			- "named_import": Each attribute is a named import (e.g., import { useState } from "react")
 		constructors: Set of names that are constructors (emit with 'new')
-		global_scope: If True, members are registered in global scope. Module imports are disallowed.
 	"""
 
-	name: str
+	name: str | None
+	py_name: str = ""
 	src: str | None = None
 	kind: Literal["default", "namespace"] = "namespace"
 	values: Literal["member", "named_import"] = "named_import"
 	constructors: frozenset[str] = field(default_factory=frozenset)
-	global_scope: bool = False
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be emitted directly - access an attribute")
+
+	@override
+	def render(self) -> VDOMNode:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be rendered directly - access an attribute")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		kwargs: dict[str, ast.expr],
+		ctx: Transpiler,
+	) -> Expr:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be called directly - access an attribute")
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		return self.get_value(attr)
+
+	@override
+	def transpile_subscript(self, key: ast.expr, ctx: Transpiler) -> Expr:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be subscripted")
 
 	@property
 	def is_builtin(self) -> bool:
 		return self.src is None
 
-	def to_js_expr(self) -> JSIdentifier | Import:
-		"""Generate the appropriate JSExpr for this module.
+	def to_expr(self) -> Identifier | Import:
+		"""Generate the appropriate Expr for this module.
 
-		Returns JSIdentifier for builtins, Import for external modules.
+		Returns Identifier for builtins, Import for external modules.
 
-		Raises JSCompilationError if global_scope=True (module imports are disallowed).
+		Raises TranspileError if name is None (module imports are disallowed).
 		"""
-		if self.global_scope:
-			module_name_lower = self.name.lower()
-			msg = (
-				f"Cannot import module '{self.name}' directly. "
-				+ f"Use 'from pulse.js.{module_name_lower} import ...' instead."
-			)
-			raise JSCompilationError(msg)
+		if self.name is None:
+			label = self.py_name or "JS global module"
+			# If a module has no JS module expression, importing it as a module value is meaningless.
+			# Users should import members from the Python module instead.
+			if self.py_name:
+				msg = (
+					f"Cannot import module '{label}' directly. "
+					+ f"Use 'from {self.py_name} import ...' instead."
+				)
+			else:
+				msg = f"Cannot import module '{label}' directly."
+			raise TranspileError(msg)
 
 		if self.src is None:
-			return JSIdentifier(self.name)
+			return Identifier(self.name)
 
-		if self.kind == "default":
-			return Import.default(self.name, self.src)
-		return Import.namespace(self.name, self.src)
+		import_kind = "default" if self.kind == "default" else "named"
+		return Import(self.name, self.src, kind=import_kind)
 
-	def get_value(self, name: str) -> JSMember | JSConstructor | JSIdentifier | Import:
-		"""Get a member of this module as a JS expression.
+	def get_value(self, name: str) -> Member | Class | Identifier | Import:
+		"""Get a member of this module as an expression.
 
-		For global_scope modules: returns JSIdentifier(name) directly (e.g., Set -> Set)
-		For builtins: returns JSMember (e.g., Math.sin), or JSIdentifier if name
+		For global-identifier modules (name=None): returns Identifier(name) directly (e.g., Set -> Set)
+		For builtins: returns Member (e.g., Math.sin), or Identifier if name
 			matches the module name (e.g., Set -> Set, not Set.Set)
-		For external modules with "member" style: returns JSMember (e.g., React.useState)
-		For external modules with "named_import" style: returns a named Import (e.g., import { useState } from "react")
+		For external modules with "member" style: returns Member (e.g., React.useState)
+		For external modules with "named_import" style: returns a named Import
 
-		If name is in constructors, wraps the result in JSConstructor.
+		If name is in constructors, returns a Class that emits `new ...(...)`.
 		"""
-		expr: JSMember | JSIdentifier | Import
-		if self.global_scope:
-			# Global scope: members are just identifiers, not members of a module
-			expr = JSIdentifier(name)
+		# Convention: trailing underscore escapes Python keywords (e.g. from_ -> from, is_ -> is).
+		# We keep the original `name` for constructor detection, but emit the JS name.
+		js_name = name[:-1] if name.endswith("_") else name
+
+		expr: Member | Identifier | Import
+		if self.name is None:
+			# No module expression: members are just identifiers, not members of a module
+			expr = Identifier(js_name)
 		elif self.src is None:
 			# Builtins: use identifier when name matches module name (Set.Set -> Set)
 			if name == self.name:
-				expr = JSIdentifier(name)
+				expr = Identifier(js_name)
 			else:
-				expr = JSMember(JSIdentifier(self.name), name)
+				expr = Member(Identifier(self.name), js_name)
 		elif self.values == "named_import":
-			expr = Import.named(name, self.src)
+			expr = Import(js_name, self.src)
 		else:
-			expr = JSMember(self.to_js_expr(), name)
+			expr = Member(self.to_expr(), js_name)
 
 		if name in self.constructors:
-			return JSConstructor(expr)
+			return Class(expr, name=name)
 		return expr
 
-
-@dataclass
-class JSConstructor(JSExpr):
-	"""Wrapper that emits constructor calls with 'new' keyword.
-
-	When this expression is called, it produces JSNew instead of JSCall.
-	"""
-
-	ctor: JSExpr
-	is_primary: ClassVar[bool] = True
-
-	@override
-	def emit(self) -> str:
-		return self.ctor.emit()
-
 	@override
-	def emit_call(self, args: list[Any], kwargs: dict[str, Any]) -> JSExpr:
-		if kwargs:
-			raise JSCompilationError(
-				"Keyword arguments not supported in constructor call"
-			)
-		return JSNew(self.ctor, [JSExpr.of(a) for a in args])
-
-
-# Registry: Python module -> JsModule config
-JS_MODULES: dict[ModuleType, JsModule] = {}
-
-
-def register_js_module(
-	*,
-	name: str,
-	src: str | None = None,
-	kind: Literal["default", "namespace"] = "namespace",
-	values: Literal["member", "named_import"] = "named_import",
-	global_scope: bool = False,
-) -> None:
-	"""Register the calling Python module as a JavaScript module binding.
-
-	Must be called from within the module being registered. The module is
-	automatically detected from the call stack.
+	@staticmethod
+	def register(  # pyright: ignore[reportIncompatibleMethodOverride]
+		*,
+		name: str | None,
+		src: str | None = None,
+		kind: Literal["default", "namespace"] = "namespace",
+		values: Literal["member", "named_import"] = "named_import",
+	) -> None:
+		"""Register the calling Python module as a JavaScript module binding.
+
+			Must be called from within the module being registered. The module is
+			automatically detected from the call stack.
+
+			This function sets up __getattr__ on the module for dynamic attribute access,
+			and registers the module object in EXPR_REGISTRY so it can be used as a
+			dependency (e.g., `import pulse.js.math as Math`) during transpilation.
+
+			Args:
+				name: The JavaScript identifier for the module binding (e.g., "Math"), or None
+					for modules that expose only global identifiers and cannot be imported as a whole.
+				src: Import source path. None for builtins.
+				kind: Import kind - "default" or "namespace"
+				values: How attribute access works:
+					- "member": Access as property (e.g., Math.sin, React.useState)
+					- "named_import": Each attribute is a named import
+
+		Example (inside pulse/js/math.py):
+			JsModule.register(name="Math")  # builtin
+
+		Example (inside pulse/js/react.py):
+			JsModule.register(name="React", src="react")  # namespace + named imports
+
+		Example (inside pulse/js/set.py):
+			JsModule.register(name=None)  # global identifier builtin (no module binding)
+		"""
+		# Get the calling module from the stack frame
+		frame = inspect.currentframe()
+		assert frame is not None and frame.f_back is not None
+		module_name = frame.f_back.f_globals["__name__"]
+		module = sys.modules[module_name]
 
-	This function:
-	1. Creates a JsModule config and adds it to JS_MODULES
-	2. Sets up __getattr__ on the module for dynamic attribute access
+		# Collect locally defined names and clean up module namespace
+		constructors: set[str] = set()
+		local_names: set[str] = set()
 
-	Args:
-		name: The JavaScript identifier (e.g., "Math")
-		src: Import source path. None for builtins.
-		kind: Import kind - "default" or "namespace"
-		values: How attribute access works:
-			- "member": Access as property (e.g., Math.sin, React.useState)
-			- "named_import": Each attribute is a named import (e.g., import { useState } from "react")
-		global_scope: If True, members are registered in global scope. Module imports
-			(e.g., `import pulse.js.set as Set`) are disallowed. Members are transpiled
-			as direct identifiers (e.g., `Set` -> `Set`, not `Set.Set`).
+		for attr_name in list(vars(module)):
+			if attr_name in _MODULE_DUNDERS:
+				continue
 
-	Example (inside pulse/js/math.py):
-		register_js_module(name="Math")  # builtin
+			obj = getattr(module, attr_name)
+			is_local = not hasattr(obj, "__module__") or obj.__module__ == module_name
 
-	Example (inside pulse/js/react.py):
-		register_js_module(name="React", src="react")  # namespace + named imports (default)
+			if is_local and not attr_name.startswith("_"):
+				local_names.add(attr_name)
+				if inspect.isclass(obj):
+					constructors.add(attr_name)
 
-	Example (inside pulse/js/set.py):
-		register_js_module(name="Set", global_scope=True)  # global scope builtin
-	"""
-	# Get the calling module from the stack frame
-	frame = inspect.currentframe()
-	assert frame is not None and frame.f_back is not None
-	module_name = frame.f_back.f_globals["__name__"]
-	module = sys.modules[module_name]
-
-	# Collect constructor names before deleting functions/classes
-	# Classes are automatically treated as constructors
-	# Only items defined in this module are considered (not imported ones)
-	# Track locally defined names so __getattr__ can distinguish them from imported ones
-
-	def is_defined_in_module(obj: Any) -> bool:
-		"""Check if an object is defined in the current module (not imported)."""
-		return hasattr(obj, "__module__") and obj.__module__ == module_name
-
-	ctor_names: set[str] = set()
-	locally_defined_names: set[str] = set()
-
-	for attr_name in list(vars(module)):
-		# Skip special module attributes
-		if attr_name in (
-			"__name__",
-			"__file__",
-			"__doc__",
-			"__package__",
-			"__path__",
-			"__cached__",
-			"__loader__",
-			"__spec__",
-		):
-			continue
-		attr = getattr(module, attr_name)
-		# Check if this is an imported name (has __module__ that doesn't match)
-		is_imported = hasattr(attr, "__module__") and attr.__module__ != module_name
-		if isinstance(attr, FunctionType):
-			# Functions without __module__ are assumed to be locally defined (stub functions)
-			if not is_imported and (
-				not hasattr(attr, "__module__") or is_defined_in_module(attr)
-			):
-				# Only track non-underscore-prefixed names for exports
-				if not attr_name.startswith("_"):
-					locally_defined_names.add(attr_name)
-					if id(attr) in CONSTRUCTORS:
-						ctor_names.add(attr_name)
-				delattr(module, attr_name)
-			else:
-				# Delete imported functions (including underscore-prefixed)
-				delattr(module, attr_name)
-		elif inspect.isclass(attr):
-			# Only consider classes defined in this module (not imported)
-			if not is_imported and is_defined_in_module(attr):
-				# Only track non-underscore-prefixed names for exports
-				if not attr_name.startswith("_"):
-					locally_defined_names.add(attr_name)
-					ctor_names.add(attr_name)
-				delattr(module, attr_name)
-			else:
-				# Delete imported classes (including underscore-prefixed)
-				delattr(module, attr_name)
-		elif is_imported:
-			# Delete all imported objects (TypeVar, Generic, etc.) including underscore-prefixed
-			delattr(module, attr_name)
-		else:
-			# For objects without __module__, assume they're locally defined
-			# (constants, etc.) - but constants are usually just annotations
-			# so they won't be in vars(module) anyway
-			if not attr_name.startswith("_"):
-				locally_defined_names.add(attr_name)
 			delattr(module, attr_name)
 
-	# Collect constant names from annotations (constants are just type annotations)
-	# before clearing them
-	constant_names: set[str] = set()
-	if hasattr(module, "__annotations__"):
-		for ann_name in module.__annotations__:
-			if not ann_name.startswith("_") and ann_name not in locally_defined_names:
-				constant_names.add(ann_name)
-		# Clear annotations (they're just for IDE hints, not runtime values)
-		module.__annotations__.clear()
-
-	js_module = JsModule(
-		name=name,
-		src=src,
-		kind=kind,
-		values=values,
-		constructors=frozenset(ctor_names),
-		global_scope=global_scope,
-	)
-	JS_MODULES[module] = js_module
-
-	# Include constants in locally_defined_names so they're accessible via __getattr__
-	locally_defined_names.update(constant_names)
-
-	# Set up __getattr__ - all attribute access now goes through here
-	# Capture locally_defined_names in closure
-	_defined_names = locally_defined_names
-
-	def __getattr__(name: str) -> JSMember | JSConstructor | JSIdentifier | Import:
-		if name.startswith("_"):
-			raise AttributeError(name)
-		# Only allow access to locally defined names (functions, classes, constants)
-		if name not in _defined_names:
-			raise AttributeError(name)
-		return js_module.get_value(name)
-
-	module.__getattr__ = __getattr__  # type: ignore[method-assign]
+		# Add annotated constants to local_names
+		if hasattr(module, "__annotations__"):
+			for ann_name in module.__annotations__:
+				if not ann_name.startswith("_"):
+					local_names.add(ann_name)
+			module.__annotations__.clear()
+
+		# Invariants: a module without a JS module binding cannot be imported from a JS source.
+		if name is None and src is not None:
+			raise ValueError("name=None is only supported for builtins (src=None)")
+
+		js_module = JsModule(
+			name=name,
+			py_name=module.__name__,
+			src=src,
+			kind=kind,
+			values=values,
+			constructors=frozenset(constructors),
+		)
+		# Register the module object itself so `import pulse.js.math as Math` resolves via EXPR_REGISTRY.
+		Expr.register(module, js_module)
+
+		def __getattr__(name: str) -> Member | Class | Identifier | Import:
+			if name.startswith("_") or name not in local_names:
+				raise AttributeError(name)
+			return js_module.get_value(name)
+
+		module.__getattr__ = __getattr__  # type: ignore[method-assign]

pulse/transpiler/modules/__init__.py

@@ -1,30 +1,33 @@
 """Central registration point for all module transpilers.
 
-This module registers all built-in Python and JavaScript modules for transpilation.
+This module registers all built-in Python modules for transpilation.
 Import this module to ensure all transpilers are available.
 """
 
 import asyncio as asyncio_builtin
 import json as json_builtin
 import math as math_builtin
-import re as re_builtin
 import typing as typing_builtin
 
-import pulse.html.tags as pulse_tags
+import pulse as pulse_module
+import pulse.dom.tags as pulseTags
 from pulse.transpiler.modules.asyncio import PyAsyncio
 from pulse.transpiler.modules.json import PyJson
 from pulse.transpiler.modules.math import PyMath
-from pulse.transpiler.modules.re import PyRe
-from pulse.transpiler.modules.tags import PyTags
+from pulse.transpiler.modules.pulse.tags import PulseTags
 from pulse.transpiler.modules.typing import PyTyping
-from pulse.transpiler.py_module import register_module
+from pulse.transpiler.py_module import PyModule
 
 # Register built-in Python modules
-register_module(asyncio_builtin, PyAsyncio)
-register_module(json_builtin, PyJson)
-register_module(math_builtin, PyMath)
-register_module(re_builtin, PyRe)
-register_module(typing_builtin, PyTyping)
+PyModule.register(math_builtin, PyMath)
+PyModule.register(json_builtin, PyJson)
+PyModule.register(asyncio_builtin, PyAsyncio)
+PyModule.register(typing_builtin, PyTyping)
 
-# Register Pulse HTML tags for JSX transpilation
-register_module(pulse_tags, PyTags)
+# Register Pulse DOM tags for JSX transpilation
+# This covers `from pulse.dom import tags; tags.div(...)`
+PyModule.register(pulseTags, PulseTags)
+
+# Register main pulse module for transpilation
+# This covers `import pulse as ps; ps.div(...)`
+PyModule.register(pulse_module, PulseTags)

pulse/transpiler/modules/asyncio.py

@@ -1,38 +1,57 @@
-"""Python asyncio module transpilation to JavaScript Promise operations.
-
-This module provides transpilation from Python's `asyncio` module to JavaScript's `Promise` methods.
-"""
-
-from pulse.transpiler.nodes import JSArray, JSExpr, JSIdentifier, JSMemberCall
+"""Python asyncio module transpilation to JavaScript Promise operations."""
+
+from __future__ import annotations
+
+from typing import Any, cast, final
+
+from pulse.transpiler.nodes import (
+	Array,
+	Binary,
+	Call,
+	Expr,
+	Identifier,
+	Literal,
+	Member,
+	Ternary,
+)
 from pulse.transpiler.py_module import PyModule
+from pulse.transpiler.transpiler import Transpiler
 
+_Promise = Identifier("Promise")
 
+
+@final
 class PyAsyncio(PyModule):
 	"""Provides transpilation for Python asyncio functions to JavaScript Promise methods."""
 
 	@staticmethod
-	def gather(*coros: JSExpr, **kwargs: JSExpr) -> JSExpr:
+	def gather(*coros: Any, return_exceptions: Any = False, ctx: Transpiler) -> Expr:
 		"""Transpile asyncio.gather to Promise.all or Promise.allSettled.
 
 		Args:
 			*coros: Variable number of coroutine/promise expressions
-			**kwargs: Keyword arguments, including return_exceptions
-
-		Returns:
-			JSExpr representing Promise.all([...]) or Promise.allSettled([...])
+			return_exceptions: If True, use Promise.allSettled
+			ctx: Transpiler context
 		"""
-		# Convert coros to array
-		promises = JSArray(list(coros))
-
-		# Check return_exceptions keyword argument
-		return_exceptions = kwargs.get("return_exceptions")
-		if return_exceptions is not None:
-			# Check if it's a boolean true (JSBoolean(True))
-			from pulse.transpiler.nodes import JSBoolean
-
-			if isinstance(return_exceptions, JSBoolean) and return_exceptions.value:
-				# Promise.allSettled returns results with status
-				return JSMemberCall(JSIdentifier("Promise"), "allSettled", [promises])
-
-		# Default: Promise.all fails fast on first rejection
-		return JSMemberCall(JSIdentifier("Promise"), "all", [promises])
+		promises = Array([ctx.emit_expr(c) for c in coros])
+		all_call = Call(Member(_Promise, "all"), [promises])
+		all_settled_call = Call(Member(_Promise, "allSettled"), [promises])
+
+		# Optimized: literal True -> allSettled
+		if return_exceptions is True or (
+			isinstance(return_exceptions, Literal) and return_exceptions.value is True
+		):
+			return all_settled_call
+
+		# Optimized: literal False or default -> all
+		if return_exceptions is False or (
+			isinstance(return_exceptions, Literal) and return_exceptions.value is False
+		):
+			return all_call
+
+		# General case: emit ternary on the expression
+		return Ternary(
+			Binary(ctx.emit_expr(cast(Any, return_exceptions)), "===", Literal(True)),
+			all_settled_call,
+			all_call,
+		)

pulse/transpiler/modules/json.py

@@ -1,20 +1,24 @@
 """Python json module transpilation to JavaScript JSON."""
 
-from pulse.transpiler.nodes import JSExpr, JSIdentifier, JSMemberCall
-from pulse.transpiler.py_module import PyModule
+from __future__ import annotations
+
+from typing import Any, final
 
+from pulse.transpiler.nodes import Call, Expr, Identifier, Member
+from pulse.transpiler.py_module import PyModule
+from pulse.transpiler.transpiler import Transpiler
 
-def JSONCall(name: str, *args: JSExpr) -> JSExpr:
-	return JSMemberCall(JSIdentifier("JSON"), name, list(args))
+_JSON = Identifier("JSON")
 
 
+@final
 class PyJson(PyModule):
 	"""Provides transpilation for Python json functions to JavaScript."""
 
 	@staticmethod
-	def dumps(obj: JSExpr) -> JSExpr:
-		return JSONCall("stringify", obj)
+	def dumps(obj: Any, *, ctx: Transpiler) -> Expr:
+		return Call(Member(_JSON, "stringify"), [ctx.emit_expr(obj)])
 
 	@staticmethod
-	def loads(s: JSExpr) -> JSExpr:
-		return JSONCall("parse", s)
+	def loads(s: Any, *, ctx: Transpiler) -> Expr:
+		return Call(Member(_JSON, "parse"), [ctx.emit_expr(s)])