pulse-framework 0.1.46__py3-none-any.whl → 0.1.47__py3-none-any.whl

pulse/transpiler/py_module.py

@@ -0,0 +1,119 @@
+"""Python module transpilation system for javascript_v2.
+
+Provides infrastructure for mapping Python modules (like `math`) to JavaScript equivalents.
+For direct JavaScript module bindings, use the pulse.js.* module system instead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any, TypeAlias, cast, override
+
+from pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.nodes import JSExpr, JSTransformer
+
+# Type alias for module transpilers - either a PyModule class or a dict
+# The dict can contain JSExpr or Callable[..., JSExpr] during construction,
+# but will be normalized to only JSExpr before storage
+PyModuleTranspiler: TypeAlias = dict[str, JSExpr]
+
+
+@dataclass
+class PyModuleExpr(JSExpr):
+	"""JSExpr for a Python module imported as a whole (e.g., `import math`).
+
+	Holds a transpiler dict mapping attribute names to JSExpr.
+	Attribute access looks up the attr in the dict and returns the result.
+	"""
+
+	transpiler: dict[str, JSExpr]
+
+	@override
+	def emit(self) -> str:
+		raise JSCompilationError("PyModuleExpr cannot be emitted directly")
+
+	@override
+	def emit_call(self, args: list[Any], kwargs: dict[str, Any]) -> JSExpr:
+		raise JSCompilationError("PyModuleExpr cannot be called directly")
+
+	@override
+	def emit_subscript(self, indices: list[Any]) -> JSExpr:
+		raise JSCompilationError("PyModuleExpr cannot be subscripted")
+
+	@override
+	def emit_getattr(self, attr: str) -> JSExpr:
+		value = self.transpiler.get(attr)
+		if value is None:
+			raise JSCompilationError(f"Module has no attribute '{attr}'")
+		# transpiler always contains JSExpr (wrapping happens in register_module)
+		return value
+
+
+class PyModule:
+	"""Base class for Python module transpilation mappings.
+
+	Subclasses define static methods and class attributes that map Python module
+	functions and constants to their JavaScript equivalents.
+
+	Example:
+		class PyMath(PyModule):
+			# Constants - JSExpr values
+			pi = JSMember(JSIdentifier("Math"), "PI")
+
+			# Functions - return JSExpr
+			@staticmethod
+			def floor(x: JSExpr) -> JSExpr:
+				return JSMemberCall(JSIdentifier("Math"), "floor", [x])
+	"""
+
+
+PY_MODULES: dict[ModuleType, PyModuleTranspiler] = {}
+
+
+def register_module(
+	module: ModuleType,
+	transpilation: type[PyModule] | dict[str, JSExpr | Callable[..., JSExpr]],
+) -> None:
+	"""Register a Python module for transpilation.
+
+	Args:
+		module: The Python module to register (e.g., `math`, `pulse.html.tags`)
+		transpilation: Either a PyModule subclass or a dict mapping attribute names
+			to JSExpr (for constants) or Callable[..., JSExpr] (for functions).
+			Callables will be wrapped in JSTransformer during registration.
+	"""
+	# Convert PyModule class to dict if needed (wraps callables)
+	transpiler_dict: PyModuleTranspiler = {}
+
+	# Get items to iterate over - either from dict or PyModule class
+	if isinstance(transpilation, dict):
+		items = transpilation.items()
+	else:
+		# Convert PyModule class to (name, attr) pairs
+		items = (
+			(attr_name, getattr(transpilation, attr_name, None))
+			for attr_name in dir(transpilation)
+			if not attr_name.startswith("_")
+		)
+
+	# Normalize: wrap callables in JSTransformer and register via JSExpr.register
+	for attr_name, attr in items:
+		if isinstance(attr, JSExpr):
+			pass
+		elif callable(attr):
+			# Wrap callables in JSTransformer so result always contains JSExpr
+			attr = JSTransformer(cast(Callable[..., JSExpr], attr))
+		else:
+			# Skip non-JSExpr, non-callable values
+			continue
+
+		transpiler_dict[attr_name] = attr
+		# Register the module attribute value for lookup by id
+		module_value = getattr(module, attr_name, None)
+		if module_value is not None:
+			JSExpr.register(module_value, attr)
+
+	# Store as dict (now normalized to only JSExpr)
+	PY_MODULES[module] = transpiler_dict