pulse-framework 0.1.62__py3-none-any.whl

pulse/transpiler/dynamic_import.py

@@ -0,0 +1,130 @@
+"""Dynamic import primitive for code-splitting.
+
+Provides `import_` for inline dynamic imports in @javascript functions:
+
+    @javascript
+    def load_chart():
+        return import_("./Chart").then(lambda m: m.default)
+
+For lazy-loaded React components, use Import(lazy=True) with React.lazy:
+
+    from pulse.js.react import React, lazy
+
+    # Low-level: Import(lazy=True) creates a factory, wrap with React.lazy
+    factory = Import("./Chart", lazy=True)
+    LazyChart = Jsx(React.lazy(factory))
+
+    # High-level: lazy() helper combines both
+    LazyChart = lazy("./Chart")
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pulse.transpiler.assets import LocalAsset, register_local_asset
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.imports import is_local_path, resolve_local_path
+from pulse.transpiler.nodes import Expr, Member
+
+if TYPE_CHECKING:
+	from pulse.transpiler.transpiler import Transpiler
+
+
+@dataclass(slots=True)
+class DynamicImport(Expr):
+	"""Represents a dynamic import() expression.
+
+	Emits as: import("src")
+
+	Supports method chaining for .then():
+	    import_("./foo").then(lambda m: m.bar)
+	    -> import("./foo").then(m => m.bar)
+	"""
+
+	src: str
+	asset: LocalAsset | None = None
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		if self.asset:
+			out.append(f'import("{self.asset.import_path()}")')
+		else:
+			out.append(f'import("{self.src}")')
+
+	@override
+	def render(self):
+		raise TypeError("DynamicImport cannot be rendered to VDOM")
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		"""Allow .then() and other method chaining."""
+		return Member(self, attr)
+
+
+class DynamicImportFn(Expr):
+	"""Sentinel expr that intercepts import_() calls.
+
+	When used in a @javascript function:
+	    import_("./module")
+
+	Transpiles to:
+	    import("./module")
+
+	For local paths, resolves the file and registers it for asset copying.
+	"""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		raise TypeError(
+			"import_ cannot be emitted directly - call it with a source path"
+		)
+
+	@override
+	def render(self):
+		raise TypeError("import_ cannot be rendered to VDOM")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		"""Handle import_("source") calls."""
+		if keywords:
+			raise TranspileError("import_() does not accept keyword arguments")
+		if len(args) != 1:
+			raise TranspileError("import_() takes exactly 1 argument")
+
+		# Extract string literal from AST
+		src_node = args[0]
+		if not isinstance(src_node, ast.Constant) or not isinstance(
+			src_node.value, str
+		):
+			raise TranspileError("import_() argument must be a string literal")
+
+		src = src_node.value
+		asset: LocalAsset | None = None
+
+		# Resolve local paths and register asset
+		if is_local_path(src):
+			if ctx.source_file is None:
+				raise TranspileError(
+					"Cannot resolve relative import_() path: source file unknown"
+				)
+			source_path = resolve_local_path(src, ctx.source_file)
+			if source_path:
+				asset = register_local_asset(source_path)
+			else:
+				raise TranspileError(
+					f"import_({src!r}) references a local path that does not exist"
+				)
+
+		return DynamicImport(src, asset)
+
+
+# Singleton for use in deps
+import_ = DynamicImportFn()

pulse/transpiler/emit_context.py

@@ -0,0 +1,49 @@
+"""Emit context for code generation."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Literal
+
+
+@dataclass
+class EmitContext:
+	"""Context for emit operations during route code generation.
+
+	Stores information about the current route file being generated,
+	allowing emit methods to compute correct relative paths.
+
+	Usage:
+		with EmitContext(route_file_path="routes/users/index.tsx"):
+			js_code = emit(fn.transpile())
+	"""
+
+	route_file_path: str
+	"""Path to route file from pulse folder root, e.g. 'routes/users/index.tsx'"""
+
+	_token: Token[EmitContext | None] | None = field(default=None, repr=False)
+
+	@classmethod
+	def get(cls) -> EmitContext | None:
+		"""Get current emit context, or None if not set."""
+		return _EMIT_CONTEXT.get()
+
+	def __enter__(self) -> EmitContext:
+		self._token = _EMIT_CONTEXT.set(self)
+		return self
+
+	def __exit__(
+		self,
+		exc_type: type[BaseException] | None = None,
+		exc_val: BaseException | None = None,
+		exc_tb: TracebackType | None = None,
+	) -> Literal[False]:
+		if self._token is not None:
+			_EMIT_CONTEXT.reset(self._token)
+			self._token = None
+		return False
+
+
+_EMIT_CONTEXT: ContextVar[EmitContext | None] = ContextVar("emit_context", default=None)

pulse/transpiler/errors.py

@@ -0,0 +1,96 @@
+"""Transpiler-specific error classes."""
+
+from __future__ import annotations
+
+import ast
+
+
+class TranspileError(Exception):
+	"""Error during transpilation with optional source location."""
+
+	message: str
+	node: ast.expr | ast.stmt | ast.excepthandler | None
+	source: str | None
+	filename: str | None
+	func_name: str | None
+	source_start_line: int | None
+
+	def __init__(
+		self,
+		message: str,
+		*,
+		node: ast.expr | ast.stmt | ast.excepthandler | None = None,
+		source: str | None = None,
+		filename: str | None = None,
+		func_name: str | None = None,
+		source_start_line: int | None = None,
+	) -> None:
+		self.message = message
+		self.node = node
+		self.source = source
+		self.filename = filename
+		self.func_name = func_name
+		self.source_start_line = source_start_line
+		super().__init__(self._format_message())
+
+	def _format_message(self) -> str:
+		"""Format the error message with source location if available."""
+		parts = [self.message]
+
+		if self.node is not None and hasattr(self.node, "lineno"):
+			loc_parts: list[str] = []
+			if self.func_name:
+				loc_parts.append(f"in {self.func_name}")
+			display_lineno = self.node.lineno
+			if self.source_start_line is not None:
+				display_lineno = self.source_start_line + self.node.lineno - 1
+			if self.filename:
+				loc_parts.append(f"at {self.filename}:{display_lineno}")
+			else:
+				loc_parts.append(f"at line {display_lineno}")
+
+			display_line = None
+			display_col = None
+			if self.source:
+				lines = self.source.splitlines()
+				if 0 < self.node.lineno <= len(lines):
+					source_line = lines[self.node.lineno - 1]
+					display_line = source_line.expandtabs(4)
+					if hasattr(self.node, "col_offset"):
+						prefix = source_line[: self.node.col_offset]
+						display_col = len(prefix.expandtabs(4))
+
+			if hasattr(self.node, "col_offset"):
+				col = display_col if display_col is not None else self.node.col_offset
+				loc_parts[-1] += f":{col}"
+
+			if loc_parts:
+				parts.append(" ".join(loc_parts))
+
+			# Show the source line if available
+			if display_line is not None:
+				parts.append(f"\n  {display_line}")
+				# Add caret pointing to column
+				if display_col is not None:
+					parts.append("  " + " " * display_col + "^")
+
+		return "\n".join(parts) if len(parts) > 1 else parts[0]
+
+	def with_context(
+		self,
+		*,
+		node: ast.expr | ast.stmt | ast.excepthandler | None = None,
+		source: str | None = None,
+		filename: str | None = None,
+		func_name: str | None = None,
+		source_start_line: int | None = None,
+	) -> TranspileError:
+		"""Return a new TranspileError with additional context."""
+		return TranspileError(
+			self.message,
+			node=node or self.node,
+			source=source or self.source,
+			filename=filename or self.filename,
+			func_name=func_name or self.func_name,
+			source_start_line=source_start_line or self.source_start_line,
+		)