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

pulse/transpiler/imports.py

@@ -0,0 +1,409 @@
+"""Unified JS import system for javascript_v2."""
+
+import inspect
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import (
+	ClassVar,
+	TypeAlias,
+	TypeVar,
+	TypeVarTuple,
+	overload,
+	override,
+)
+
+from pulse.transpiler.context import is_interpreted_mode
+from pulse.transpiler.ids import generate_id
+from pulse.transpiler.nodes import JSExpr
+
+T = TypeVar("T")
+Args = TypeVarTuple("Args")
+R = TypeVar("R")
+
+# Registry key: (name, src, is_default)
+# - Named imports: (name, src, False)
+# - Default/side-effect imports: ("", src, is_default) - dedupe by src only
+_ImportKey: TypeAlias = tuple[str, str, bool]
+_REGISTRY: dict[_ImportKey, "Import"] = {}
+
+
+def _caller_file(depth: int = 2) -> Path:
+	"""Get the file path of the caller.
+
+	Args:
+		depth: How many frames to go back (2 = caller of the function that calls this)
+	"""
+	frame = inspect.currentframe()
+	try:
+		# Walk up the call stack
+		for _ in range(depth):
+			if frame is None:
+				raise RuntimeError("Cannot determine caller frame")
+			frame = frame.f_back
+		if frame is None:
+			raise RuntimeError("Cannot determine caller frame")
+		return Path(frame.f_code.co_filename).resolve()
+	finally:
+		del frame
+
+
+def _is_local_css_path(path: str) -> bool:
+	"""Check if a CSS path refers to a local file vs a package import.
+
+	Local paths:
+	- Start with './' or '../' (relative)
+	- Start with '/' (absolute)
+	- Don't start with '@' (scoped npm package)
+	- Don't look like a bare module specifier
+
+	Package imports:
+	- Start with '@' (e.g., '@mantine/core/styles.css')
+	- Bare specifiers (e.g., 'some-package/styles.css')
+	"""
+	# Relative paths are local
+	if path.startswith("./") or path.startswith("../"):
+		return True
+	# Absolute paths are local
+	if path.startswith("/"):
+		return True
+	# Scoped packages
+	if path.startswith("@"):
+		return False
+	# If it contains no slashes, it could be a local file in current dir
+	# But without './' prefix, treat bare names as package imports for safety
+	# Exception: if it ends with .css and doesn't look like a package
+	if "/" not in path and path.endswith(".css"):
+		# Ambiguous - could be local or package. Require explicit ./
+		return False
+	# Everything else (bare specifiers with paths) are package imports
+	return False
+
+
+class Import(JSExpr):
+	"""Universal import descriptor.
+
+	Import identity is determined by (name, src, is_default):
+	- Named imports: unique by (name, src)
+	- Default imports: unique by src (name is the local binding)
+	- Side-effect imports: unique by src (name is empty)
+
+	When two Import objects reference the same underlying import, they share
+	the same ID, allowing multiple Import objects to target different properties
+	of the same import.
+
+	Examples:
+		# Named import: import { foo } from "./module"
+		foo = Import("foo", "./module")
+
+		# Default import: import React from "react"
+		React = Import("React", "react", is_default=True)
+
+		# Type-only import: import type { Foo } from "./types"
+		Foo = Import("Foo", "./types", is_type_only=True)
+
+		# Side-effect import: import "./styles.css"
+		Import.side_effect("./styles.css")
+
+		# CSS module import with class access
+		styles = Import.css_module("./styles.module.css", relative=True)
+		styles.container  # Returns JSMember for 'container' class
+	"""
+
+	__slots__ = (  # pyright: ignore[reportUnannotatedClassAttribute]
+		"name",
+		"src",
+		"is_default",
+		"is_namespace",
+		"is_type_only",
+		"before",
+		"id",
+		"source_path",
+	)
+
+	is_primary: ClassVar[bool] = True
+
+	name: str
+	src: str
+	is_default: bool
+	is_namespace: bool
+	is_type_only: bool
+	before: tuple[str, ...]
+	id: str
+	source_path: Path | None  # For local CSS files that need to be copied
+
+	def __init__(
+		self,
+		name: str,
+		src: str,
+		*,
+		is_default: bool = False,
+		is_namespace: bool = False,
+		is_type_only: bool = False,
+		before: Sequence[str] = (),
+		source_path: Path | None = None,
+	) -> None:
+		self.name = name
+		self.src = src
+		self.is_default = is_default
+		self.is_namespace = is_namespace
+		self.source_path = source_path
+
+		before_tuple = tuple(before)
+
+		# Dedupe key: for default/side-effect/namespace imports, only src matters
+		key: _ImportKey = (
+			("", src, is_default or is_namespace)
+			if (is_default or is_namespace or name == "")
+			else (name, src, False)
+		)
+
+		if key in _REGISTRY:
+			existing = _REGISTRY[key]
+
+			# Merge: type-only + regular = regular
+			if existing.is_type_only and not is_type_only:
+				existing.is_type_only = False
+
+			# Merge: union of before constraints
+			if before_tuple:
+				merged_before = set(existing.before) | set(before_tuple)
+				existing.before = tuple(sorted(merged_before))
+
+			# Reuse ID and merged values
+			self.id = existing.id
+			self.is_type_only = existing.is_type_only
+			self.before = existing.before
+		else:
+			# New import
+			self.id = generate_id()
+			self.is_type_only = is_type_only
+			self.before = before_tuple
+			_REGISTRY[key] = self
+
+	@classmethod
+	def default(
+		cls,
+		name: str,
+		src: str,
+		*,
+		is_type_only: bool = False,
+		before: Sequence[str] = (),
+	) -> "Import":
+		"""Create a default import."""
+		return cls(
+			name,
+			src,
+			is_default=True,
+			is_type_only=is_type_only,
+			before=before,
+		)
+
+	@classmethod
+	def named(
+		cls,
+		name: str,
+		src: str,
+		*,
+		is_type_only: bool = False,
+		before: Sequence[str] = (),
+	) -> "Import":
+		"""Create a named import."""
+		return cls(
+			name,
+			src,
+			is_default=False,
+			is_type_only=is_type_only,
+			before=before,
+		)
+
+	@classmethod
+	def namespace(
+		cls,
+		name: str,
+		src: str,
+		*,
+		before: Sequence[str] = (),
+	) -> "Import":
+		"""Create a namespace import: import * as name from src."""
+		return cls(
+			name,
+			src,
+			is_namespace=True,
+			before=before,
+		)
+
+	@classmethod
+	def type_(
+		cls,
+		name: str,
+		src: str,
+		*,
+		is_default: bool = False,
+		before: Sequence[str] = (),
+	) -> "Import":
+		"""Create a type-only import."""
+		return cls(name, src, is_default=is_default, is_type_only=True, before=before)
+
+	@property
+	def is_side_effect(self) -> bool:
+		"""True if this is a side-effect only import (no bindings)."""
+		return self.name == "" and not self.is_default
+
+	@property
+	def js_name(self) -> str:
+		"""Unique JS identifier for this import."""
+		return f"{self.name}_{self.id}"
+
+	@override
+	def emit(self) -> str:
+		"""Emit JS code for this import.
+
+		In normal mode: returns the unique JS name (e.g., "Button_1")
+		In interpreted mode: returns a get_object call (e.g., "get_object('Button_1')")
+		"""
+		base = self.js_name
+		if is_interpreted_mode():
+			return f"get_object('{base}')"
+		return base
+
+	@override
+	def __repr__(self) -> str:
+		parts = [f"name={self.name!r}", f"src={self.src!r}"]
+		if self.is_default:
+			parts.append("is_default=True")
+		if self.is_namespace:
+			parts.append("is_namespace=True")
+		if self.is_type_only:
+			parts.append("is_type_only=True")
+		if self.source_path:
+			parts.append(f"source_path={self.source_path!r}")
+		return f"Import({', '.join(parts)})"
+
+
+class CssImport(Import):
+	"""Import for CSS files (both local files and npm packages).
+
+	For local files, tracks the source path and provides a generated filename
+	for the output directory. For npm packages, acts as a regular import.
+
+	Args:
+		path: Path to CSS file. Can be:
+			- Package path (e.g., "@mantine/core/styles.css")
+			- Relative path with relative=True (e.g., "./global.css")
+			- Absolute path (e.g., "/path/to/styles.css")
+		module: If True, import as a CSS module (default export for class access).
+			If False, import for side effects only (global styles).
+		relative: If True, resolve path relative to the caller's file.
+		before: List of import sources that should come after this import.
+
+	Examples:
+		# Side-effect CSS import (global styles)
+		CssImport("@mantine/core/styles.css")
+
+		# CSS module for class access
+		styles = CssImport("./styles.module.css", module=True, relative=True)
+		styles.container  # Returns JSMember for 'container' class
+
+		# Local CSS file (will be copied during codegen)
+		CssImport("./global.css", relative=True)
+	"""
+
+	def __init__(
+		self,
+		path: str,
+		*,
+		module: bool = False,
+		relative: bool = False,
+		before: Sequence[str] = (),
+	) -> None:
+		source_path: Path | None = None
+		import_src = path
+
+		if relative:
+			# Resolve relative to caller's file (depth=2: _caller_file -> __init__ -> caller)
+			caller = _caller_file(depth=2)
+			source_path = (caller.parent / Path(path)).resolve()
+			if not source_path.exists():
+				kind = "CSS module" if module else "CSS file"
+				raise FileNotFoundError(
+					f"{kind} '{path}' not found relative to {caller.parent}"
+				)
+			import_src = str(source_path)
+		elif _is_local_css_path(path):
+			# Absolute local path
+			source_path = Path(path).resolve()
+			if not source_path.exists():
+				kind = "CSS module" if module else "CSS file"
+				raise FileNotFoundError(f"{kind} '{path}' not found")
+			import_src = str(source_path)
+
+		# CSS modules are default imports with "css" name prefix
+		# Side-effect imports have empty name and is_default=False
+		name = "css" if module else ""
+		is_default = module
+
+		super().__init__(
+			name,
+			import_src,
+			is_default=is_default,
+			is_type_only=False,
+			before=before,
+			source_path=source_path,
+		)
+
+	@property
+	def is_local(self) -> bool:
+		"""True if this is a local CSS file (not an npm package)."""
+		return self.source_path is not None
+
+	@property
+	def generated_filename(self) -> str | None:
+		"""Generated filename for local CSS files, or None for package imports."""
+		if self.source_path is None:
+			return None
+		if self.source_path.name.endswith(".module.css"):
+			return f"css_{self.id}.module.css"
+		return f"css_{self.id}.css"
+
+
+def registered_imports() -> list[Import]:
+	"""Get all registered imports."""
+	return list(_REGISTRY.values())
+
+
+def clear_import_registry() -> None:
+	"""Clear the import registry."""
+	_REGISTRY.clear()
+
+
+# =============================================================================
+# js_import decorator/function
+# =============================================================================
+
+
+@overload
+def import_js(
+	name: str, src: str, *, is_default: bool = False
+) -> Callable[[Callable[[*Args], R]], Callable[[*Args], R]]:
+	"Import a JS function for use in `@javascript` functions"
+	...
+
+
+@overload
+def import_js(name: str, src: str, type_: type[T], *, is_default: bool = False) -> T:
+	"Import a JS value for use in `@javascript` functions"
+	...
+
+
+def import_js(
+	name: str, src: str, type_: type[T] | None = None, *, is_default: bool = False
+) -> T | Callable[[Callable[[*Args], R]], Callable[[*Args], R]]:
+	imp = Import.default(name, src) if is_default else Import.named(name, src)
+
+	if type_ is not None:
+		return imp  # pyright: ignore[reportReturnType]
+
+	def decorator(fn: Callable[[*Args], R]) -> Callable[[*Args], R]:
+		return imp  # pyright: ignore[reportReturnType]
+
+	return decorator

pulse/transpiler/js_module.py

@@ -0,0 +1,274 @@
+"""Core infrastructure for JavaScript module bindings.
+
+JS modules are Python modules that map to JavaScript modules/builtins.
+Registration is done by calling register_js_module() from within the module itself.
+"""
+
+from __future__ import annotations
+
+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 pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import JSExpr, JSIdentifier, JSMember, JSNew
+
+# Track functions marked as constructors (by id, since we delete them)
+CONSTRUCTORS: set[int] = set()
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+@dataclass(frozen=True)
+class JsModule:
+	"""Configuration for a JavaScript module binding.
+
+	Attributes:
+		name: The JavaScript identifier (e.g., "Math", "lodash")
+		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
+	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
+
+	@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.
+
+		Returns JSIdentifier for builtins, Import for external modules.
+
+		Raises JSCompilationError if global_scope=True (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.src is None:
+			return JSIdentifier(self.name)
+
+		if self.kind == "default":
+			return Import.default(self.name, self.src)
+		return Import.namespace(self.name, self.src)
+
+	def get_value(self, name: str) -> JSMember | JSConstructor | JSIdentifier | Import:
+		"""Get a member of this module as a JS 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
+			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")
+
+		If name is in constructors, wraps the result in JSConstructor.
+		"""
+		expr: JSMember | JSIdentifier | Import
+		if self.global_scope:
+			# Global scope: members are just identifiers, not members of a module
+			expr = JSIdentifier(name)
+		elif self.src is None:
+			# Builtins: use identifier when name matches module name (Set.Set -> Set)
+			if name == self.name:
+				expr = JSIdentifier(name)
+			else:
+				expr = JSMember(JSIdentifier(self.name), name)
+		elif self.values == "named_import":
+			expr = Import.named(name, self.src)
+		else:
+			expr = JSMember(self.to_js_expr(), name)
+
+		if name in self.constructors:
+			return JSConstructor(expr)
+		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.
+
+	This function:
+	1. Creates a JsModule config and adds it to JS_MODULES
+	2. Sets up __getattr__ on the module for dynamic attribute access
+
+	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`).
+
+	Example (inside pulse/js/math.py):
+		register_js_module(name="Math")  # builtin
+
+	Example (inside pulse/js/react.py):
+		register_js_module(name="React", src="react")  # namespace + named imports (default)
+
+	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]

pulse/transpiler/modules/__init__.py

@@ -0,0 +1,30 @@
+"""Central registration point for all module transpilers.
+
+This module registers all built-in Python and JavaScript 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
+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.typing import PyTyping
+from pulse.transpiler.py_module import register_module
+
+# 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)
+
+# Register Pulse HTML tags for JSX transpilation
+register_module(pulse_tags, PyTags)