This is an automated email from the ASF dual-hosted git repository.

tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git


The following commit(s) were added to refs/heads/main by this push:
     new 139f56f14 [FEAT] Add T.function.builder for explicit Python 
construction (#145)
139f56f14 is described below

commit 139f56f146810100449d8a00d1f2f3132c57fe99
Author: Tianqi Chen <[email protected]>
AuthorDate: Sat Oct 31 19:10:26 2026 -0400

    [FEAT] Add T.function.builder for explicit Python construction (#145)
    
    Add `@T.function.builder` for explicit IR construction with Python
    assignments, control flow and ordinary calls. It shares signature
    declarations, unquoted and postponed source annotations, and
    mixed-module forward declarations with `@T.function`; IR function calls
    use `T.call_global_var_(callee, args)`. Decorator registration
    explicitly selects its definition kind: FUNCTION by default, BUILDER for
    `T.function.builder`.
    
    One internal SCRIPT/HOST/BUILDER traversal mode separates script
    lowering, host expressions and builder bodies. Builder bodies use
    ordinary statement traversal with expression locations; explicit frames,
    void emissions and ordinary helpers may have unknown locations because
    no statement scopes are injected. Prescan collects header facts and
    identifiers for generated-name hygiene, and compiled body helpers retain
    their original Python globals and closure cells.
    
    Sugar `@T.function` rejects explicit control-flow frames with a
    source-located diagnostic directing users to sugar syntax or builder
    mode. Public stores and region operations remain available, and both
    modes print ordinary TVMScript IR.
---
 docs/reference/python/tirx.script.rst              |   1 +
 examples/ir_walkthrough/run_all_cpu.sh             |   8 +-
 python/tvm_tirx/script/parser/entry.py             |  47 +++-
 python/tvm_tirx/script/parser/prescan.py           |  48 +++-
 python/tvm_tirx/script/parser/protocol_registry.py |   3 +
 python/tvm_tirx/script/parser/transpile.py         | 234 ++++++++++++------
 python/tvm_tirx/tirx/script/__init__.py            |  62 ++++-
 tests/python/tirx/script/test_function_builder.py  | 262 +++++++++++++++++++++
 8 files changed, 576 insertions(+), 89 deletions(-)

diff --git a/docs/reference/python/tirx.script.rst 
b/docs/reference/python/tirx.script.rst
index 51a755b35..d11acf476 100644
--- a/docs/reference/python/tirx.script.rst
+++ b/docs/reference/python/tirx.script.rst
@@ -516,6 +516,7 @@ Functions
    unpack_
    while_
    function
+   function.builder
    function_
    arg_
    func_name_
diff --git a/examples/ir_walkthrough/run_all_cpu.sh 
b/examples/ir_walkthrough/run_all_cpu.sh
index 1121cb72b..b482878f2 100755
--- a/examples/ir_walkthrough/run_all_cpu.sh
+++ b/examples/ir_walkthrough/run_all_cpu.sh
@@ -18,8 +18,12 @@
 set -ex
 cd "$(dirname "$0")"
 
-# Print, parse, and build add_one
-python printing_and_parsing.py
+# The imported printed example uses Python 3.12 type-parameter syntax.
+if python -c 'import sys; sys.exit(sys.version_info < (3, 12))'; then
+    python printing_and_parsing.py
+else
+    echo "Skipping printing_and_parsing.py: requires Python 3.12 or newer."
+fi
 
 # Functions, modules, and global variables
 python functions_and_modules.py
diff --git a/python/tvm_tirx/script/parser/entry.py 
b/python/tvm_tirx/script/parser/entry.py
index 4517a1b79..3d0a88c7f 100644
--- a/python/tvm_tirx/script/parser/entry.py
+++ b/python/tvm_tirx/script/parser/entry.py
@@ -189,6 +189,39 @@ def _recompose_builder(
         if original is None:
             # Only new defaults can redirect the already-translated text 
scopes.
             global_names.intersection_update(definition_scope)
+        if generated.preserve_python_scope and original is not None:
+            # Compile once with the existing wrapper, then restore live Python
+            # globals/cells while retaining generated declaration/location 
cells.
+            # Capturing injected values avoids writing into the source globals.
+            for captured in required.intersection(namespace) - global_names:
+                definition_scope.setdefault(captured, namespace[captured])
+            for captured in original.__code__.co_freevars:
+                if captured not in retained:
+                    definition_scope.setdefault(captured, None)
+
+            def restore(function, original=original, retained=retained):
+                cells = dict(zip(function.__code__.co_freevars, 
function.__closure__ or ()))
+                cells.update(
+                    (key, cell)
+                    for key, cell in zip(original.__code__.co_freevars, 
original.__closure__ or ())
+                    if key not in retained
+                )
+                rebound = FunctionType(
+                    function.__code__,
+                    original.__globals__,
+                    function.__name__,
+                    function.__defaults__,
+                    tuple(cells[key] for key in function.__code__.co_freevars) 
or None,
+                )
+                rebound.__kwdefaults__ = function.__kwdefaults__
+                return rebound
+
+            alias = make_fresh_name("_scope")
+            namespace[alias] = restore
+            body.decorator_list.append(ast.copy_location(ast.Name(alias, 
ast.Load()), body))
+            if global_names:
+                body.body.insert(0, 
ast.copy_location(ast.Global(sorted(global_names)), body))
+            continue
         source_closure = _read_closure_values(original) if original is not 
None else {}
         for captured in sorted(source_closure.keys() - retained - parameters):
             value = (
@@ -276,8 +309,13 @@ def _is_inside_ir_module(function: FunctionType, frame: 
FrameType) -> bool:
     return False
 
 
-def make_decorator(builder: object, *, namespace_path: str) -> Callable[..., 
Any]:
-    """Create a function decorator with an explicit construction namespace.
+def make_decorator(
+    builder: object,
+    *,
+    namespace_path: str,
+    definition_kind: protocol_registry.DefinitionKind = 
protocol_registry.DefinitionKind.FUNCTION,
+) -> Callable[..., Any]:
+    """Create a function decorator with an explicit namespace and construction 
kind.
 
     Parameters
     ----------
@@ -285,6 +323,9 @@ def make_decorator(builder: object, *, namespace_path: str) 
-> Callable[..., Any
         Namespace implementing the function construction protocol.
     namespace_path : str
         Canonical registered syntax key, such as "tirx.function".
+    definition_kind : protocol_registry.DefinitionKind, optional
+        Construction behavior registered for this syntax key. Defaults to 
FUNCTION;
+        pass BUILDER for explicit Python construction without sugar lowering.
 
     Returns
     -------
@@ -313,7 +354,7 @@ def make_decorator(builder: object, *, namespace_path: str) 
-> Callable[..., Any
     pass directly to ``builder.function_``; the language variant hook owns 
their defaults.
     """
 
-    protocol_registry.DEFINITION_KIND[namespace_path] = 
protocol_registry.DefinitionKind.FUNCTION
+    protocol_registry.DEFINITION_KIND[namespace_path] = definition_kind
 
     def decorator(function: FunctionType | None = None, **options: Any) -> Any:
         """Parse a Python function into a function of the selected IR language 
variant.
diff --git a/python/tvm_tirx/script/parser/prescan.py 
b/python/tvm_tirx/script/parser/prescan.py
index 2b0988d93..e884b6688 100644
--- a/python/tvm_tirx/script/parser/prescan.py
+++ b/python/tvm_tirx/script/parser/prescan.py
@@ -145,10 +145,18 @@ def resolve_namespace_value(node: ast.AST | None, 
environment: Mapping[str, obje
 # serve separate purposes and retain their own declaration facts.
 def _match_special_func(node: ast.AST | None, namespaces: Mapping[str, str]) 
-> str | None:
     """Match direct X.member syntax without evaluating a callee or receiver."""
+    suffix = ""
+    if (
+        isinstance(node, ast.Attribute)
+        and node.attr == "builder"
+        and isinstance(node.value, ast.Attribute)
+        and node.value.attr == "function"
+    ):
+        node, suffix = node.value, ".builder"
     if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
         root = namespaces.get(node.value.id)
         if root is not None:
-            return f"{root}.{node.attr}"
+            return f"{root}.{node.attr}{suffix}"
     return None
 
 
@@ -333,6 +341,7 @@ class PrescanCollector(ast.NodeVisitor):
                 protocol_registry.DEFINITION_KIND.get(path)
                 in (
                     protocol_registry.DefinitionKind.FUNCTION,
+                    protocol_registry.DefinitionKind.BUILDER,
                     protocol_registry.DefinitionKind.MACRO,
                 )
                 for path in paths
@@ -486,16 +495,24 @@ class PrescanCollector(ast.NodeVisitor):
         self.scope = node
         self.functions.append(node)
         self.bindings[node] = []
+        kind = None
         for decorator in node.decorator_list:
             target = decorator.func if isinstance(decorator, ast.Call) else 
decorator
-            if isinstance(target, ast.Attribute) and 
protocol_registry.DEFINITION_KIND.get(
+            kind = protocol_registry.DEFINITION_KIND.get(
                 _match_special_func(target, self.namespaces)
-            ) in (
+            )
+            if isinstance(target, ast.Attribute) and kind in (
                 protocol_registry.DefinitionKind.FUNCTION,
+                protocol_registry.DefinitionKind.BUILDER,
                 protocol_registry.DefinitionKind.MACRO,
                 protocol_registry.DefinitionKind.PYTHON,
             ):
-                namespace = resolve_namespace_value(target.value, 
self.environment)
+                namespace = resolve_namespace_value(
+                    target.value.value
+                    if kind == protocol_registry.DefinitionKind.BUILDER
+                    else target.value,
+                    self.environment,
+                )
                 if namespace is not None:
                     self.builder = namespace
                     break
@@ -551,14 +568,31 @@ class PrescanCollector(ast.NodeVisitor):
         self.visit(node.args)
         for parameter in getattr(node, "type_params", ()):
             self.visit(parameter)
-        for statement in node.body:
-            self.visit(statement)
+        if kind == protocol_registry.DefinitionKind.BUILDER:
+            # Only reserve identifiers against generated-name collisions. 
Python
+            # owns body bindings and aliases; sugar semantic analysis stops 
here.
+            for statement in node.body:
+                for child in ast.walk(statement):
+                    # Include nested definitions, arguments, import 
roots/aliases
+                    # and pattern captures, whose names need not be ast.Name 
nodes.
+                    self.names.update(
+                        value.split(".")[0]
+                        for field in ("id", "name", "arg", "asname", "rest")
+                        if isinstance(value := getattr(child, field, None), 
str)
+                    )
+                    # These declarations store their identifiers in a name 
list.
+                    if isinstance(child, ast.Global | ast.Nonlocal):
+                        self.names.update(child.names)
+        else:
+            for statement in node.body:
+                self.visit(statement)
         for decorator in node.decorator_list:
             self.visit(decorator)
         if node.returns:
             self._check_annotation(node.returns)
             self.visit(node.returns)
-        self._validate_symbols(node)
+        if kind != protocol_registry.DefinitionKind.BUILDER:
+            self._validate_symbols(node)
         self.functions.pop()
         self.scope, self.builder = old_scope, old_builder
 
diff --git a/python/tvm_tirx/script/parser/protocol_registry.py 
b/python/tvm_tirx/script/parser/protocol_registry.py
index 488a7f110..d09d7540d 100644
--- a/python/tvm_tirx/script/parser/protocol_registry.py
+++ b/python/tvm_tirx/script/parser/protocol_registry.py
@@ -46,6 +46,7 @@ class DefinitionKind(IntEnum):
     """Construction behavior of a definition's canonical source decorator."""
 
     FUNCTION = auto()
+    BUILDER = auto()
     MACRO = auto()
     PYTHON = auto()
 
@@ -53,6 +54,8 @@ class DefinitionKind(IntEnum):
 SCALAR_ANNOTATION_DTYPE: dict[str, object] = {}
 MUTABLE_CELL_DECL: dict[str, frozenset[str]] = {}
 DEFINITION_KIND: dict[str, DefinitionKind] = {}
+# Explicit control frames with a required source-language statement form.
+WITH_FRAME_SUGAR: dict[str, str] = {}
 
 
 def register_scalar_annotation(
diff --git a/python/tvm_tirx/script/parser/transpile.py 
b/python/tvm_tirx/script/parser/transpile.py
index 432d8fd27..57a26956d 100644
--- a/python/tvm_tirx/script/parser/transpile.py
+++ b/python/tvm_tirx/script/parser/transpile.py
@@ -40,6 +40,7 @@ import ast
 import builtins
 from collections.abc import Callable, Iterator, Mapping
 from contextlib import contextmanager
+from enum import Enum, auto
 from types import FunctionType
 from typing import Any, NamedTuple, NoReturn, TypeVar
 
@@ -56,6 +57,12 @@ _Node = TypeVar("_Node", bound=ast.AST)
 _Value = TypeVar("_Value")
 
 
+class _RewriteMode(Enum):
+    SCRIPT = auto()
+    HOST = auto()
+    BUILDER = auto()
+
+
 def _require_constexpr_arg(value: _Value, name: str) -> _Value:
     """Return the constexpr argument value, or raise if it is missing.
 
@@ -139,6 +146,7 @@ class GeneratedBuilder(NamedTuple):
     original_func_name: str
     # Generated bindings preserved while restoring source globals/closures.
     protected_names: set[str]
+    preserve_python_scope: bool = False
 
 
 class ModuleContext:
@@ -251,9 +259,9 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         self.function = function
         # Macro return policy is fixed for one invocation.
         self.preserve_return = preserve_return
-        # Bypass syntax-to-builder lowering.
-        # Still traverse children and instrument source calls with locs.
-        self.bypass_ast_rewrite = False
+        # HOST keeps Python operators and call contexts; BUILDER also locates
+        # expressions, without call lambdas that would change Python body 
scope.
+        self.rewrite_mode = _RewriteMode.SCRIPT
         # Only free reads that cross a scope boundary use the definition 
snapshot.
         self.annotation_reads: set[ast.Name] = set()
         # Only this expression's result is already located by its enclosing 
emit_.
@@ -399,15 +407,13 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         return result
 
     @contextmanager
-    def _bypass_rewrite(self) -> Iterator[None]:
-        # Only constexpr operands and module host syntax keep Python operators.
-        # The same visitor still instruments their source calls and restores 
mode.
-        old = self.bypass_ast_rewrite
-        self.bypass_ast_rewrite = True
+    def rewrite_mode_scope(self, mode: _RewriteMode) -> Iterator[None]:
+        old = self.rewrite_mode
+        self.rewrite_mode = mode
         try:
             yield
         finally:
-            self.bypass_ast_rewrite = old
+            self.rewrite_mode = old
 
     @contextmanager
     def _rewrite_annotation(self, reads: set[ast.Name]) -> Iterator[None]:
@@ -429,6 +435,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     expr
         # -------------------------------------------------
         # The same visitor keeps Python operators and still instruments nested 
source calls.
+        if self.rewrite_mode == _RewriteMode.BUILDER:
+            return None
         if not isinstance(node, ast.Call) or not 
self._is_constexpr_annotation(node.func):
             return None
         if len(node.args) != 1 or node.keywords or isinstance(node.args[0], 
ast.Starred):
@@ -475,7 +483,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         return (
             self._attach_loc(result, node)
             if isinstance(node.ctx, ast.Load)
-            and not self.bypass_ast_rewrite
+            and self.rewrite_mode != _RewriteMode.HOST
             and not fixed_namespace
             else result
         )
@@ -499,7 +507,12 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     _L_i([a, b])
         # -------------------------------------------------
         result = self.generic_visit(node)
-        return result if self.bypass_ast_rewrite else self._attach_loc(result, 
node)
+        return (
+            self._attach_loc(result, node)
+            if self.rewrite_mode != _RewriteMode.HOST
+            and not isinstance(getattr(node, "ctx", None), ast.Store | ast.Del)
+            else result
+        )
 
     visit_Tuple = visit_List
     visit_Set = visit_List
@@ -531,7 +544,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         node.value = self.visit(node.value)
         node.slice = self._rewrite_index(node.slice)
-        if not self.bypass_ast_rewrite and isinstance(node.ctx, ast.Load):
+        if self.rewrite_mode != _RewriteMode.HOST and isinstance(node.ctx, 
ast.Load):
             return self._attach_loc(node, node)
         return node
 
@@ -539,13 +552,13 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         """Recognize fixed source module aliases from existing binding 
records."""
         if not isinstance(node, ast.Name):
             return False
-        if node.id == self.module.module_name:
-            return True
         records = [
             item
             for item in 
self.module.prescan_ctx.bindings.get(self.function.current_scope, ())
             if item.name == node.id
         ]
+        if node.id == self.module.module_name:
+            return True
         return bool(records) and all(item.kind == BindingKind.MODULE_ALIAS for 
item in records)
 
     def _visit_direct_operand(self, node: ast.expr) -> ast.expr:
@@ -574,14 +587,15 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         binding_value = node is self.binding_expression
         marker = self._read_constexpr_operand(node)
         if marker is not None:
-            with self._bypass_rewrite():
+            with self.rewrite_mode_scope(_RewriteMode.HOST):
                 return self.visit(marker)
-        global_call = (
-            isinstance(node.func, ast.Name) and node.func.id in 
self.module.global_func_names
-        ) or (
-            isinstance(node.func, ast.Attribute)
-            and self._is_module_owner(node.func.value)
-            and node.func.attr in self.module.global_func_names
+        global_call = self.rewrite_mode == _RewriteMode.SCRIPT and (
+            (isinstance(node.func, ast.Name) and node.func.id in 
self.module.global_func_names)
+            or (
+                isinstance(node.func, ast.Attribute)
+                and self._is_module_owner(node.func.value)
+                and node.func.attr in self.module.global_func_names
+            )
         )
         # Visit source callee/arguments first. A normalized range callee is
         # assembled afterward, but its original arguments keep normal 
rewriting.
@@ -599,7 +613,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     X.call_global_var_(declared_global, [x, y])
         # -------------------------------------------------
-        if global_call and not self.bypass_ast_rewrite:
+        if global_call:
             if node.keywords:
                 self._raise_error(node, "Global function calls require 
positional arguments")
             node = self._call(
@@ -617,6 +631,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         # Calls retain their construction context; bind_ owns ordinary RHS 
attribution.
         if self.module.track_loc and callee is None:
+            if self.rewrite_mode == _RewriteMode.BUILDER:
+                return self._attach_loc(node, node)
             # _L_i.ctx(lambda: callee(*args, **keywords))
             return ast.copy_location(
                 ast.Call(
@@ -638,11 +654,11 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         # An explicit constexpr operand retains ordinary Python not.
         node = self.generic_visit(node)
-        if isinstance(node.op, ast.Not) and not self.bypass_ast_rewrite:
+        if isinstance(node.op, ast.Not) and self.rewrite_mode == 
_RewriteMode.SCRIPT:
             return self._attach_loc(
                 self._call(self.function.dialect_prefix, "not_", 
[node.operand], node), node
             )
-        return self._attach_loc(node, node) if not self.bypass_ast_rewrite 
else node
+        return self._attach_loc(node, node) if self.rewrite_mode != 
_RewriteMode.HOST else node
 
     def visit_BinOp(self, node: ast.BinOp) -> ast.expr:
         # -------------------- Pattern --------------------
@@ -654,7 +670,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         return (
             self._attach_loc(self.generic_visit(node), node)
-            if not self.bypass_ast_rewrite
+            if self.rewrite_mode != _RewriteMode.HOST
             else self.generic_visit(node)
         )
 
@@ -667,14 +683,18 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     enabled and expr
         # -------------------------------------------------
         # Unmarked IR operands use X.and_ or X.or_.
-        if self.bypass_ast_rewrite:
-            return self.generic_visit(node)
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return (
+                self._attach_loc(self.generic_visit(node), node)
+                if self.rewrite_mode != _RewriteMode.HOST
+                else self.generic_visit(node)
+            )
 
         def lower(position: int) -> ast.expr:
             value = node.values[position]
             marker = self._read_constexpr_operand(value)
             if marker is not None:
-                with self._bypass_rewrite():
+                with self.rewrite_mode_scope(_RewriteMode.HOST):
                     left = self.visit(marker)
                 if position + 1 == len(node.values):
                     return left
@@ -705,11 +725,15 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     yes if test else no
         # -------------------------------------------------
         # Unmarked tests use X.if_then_else_.
-        if self.bypass_ast_rewrite:
-            return self.generic_visit(node)
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return (
+                self._attach_loc(self.generic_visit(node), node)
+                if self.rewrite_mode != _RewriteMode.HOST
+                else self.generic_visit(node)
+            )
         marker = self._read_constexpr_operand(node.test)
         if marker is not None:
-            with self._bypass_rewrite():
+            with self.rewrite_mode_scope(_RewriteMode.HOST):
                 test = self.visit(marker)
             return ast.copy_location(
                 ast.IfExp(test, self.visit(node.body), 
self.visit(node.orelse)), node
@@ -750,8 +774,12 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     X.and_(X.lt_(0, i), X.lt_(i, 10))
         # -------------------------------------------------
         # Only names and numeric literals may be repeated in a simple chain.
-        if self.bypass_ast_rewrite:
-            return self.generic_visit(node)
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return (
+                self._attach_loc(self.generic_visit(node), node)
+                if self.rewrite_mode != _RewriteMode.HOST
+                else self.generic_visit(node)
+            )
         operands = [node.left, *node.comparators]
         if len(node.ops) > 1:
             for operand in operands:
@@ -777,7 +805,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         )
         return self._attach_loc(result, node)
 
-    def visit_NamedExpr(self, node: ast.NamedExpr) -> NoReturn:
+    def visit_NamedExpr(self, node: ast.NamedExpr) -> ast.expr:
         # -------------------- Pattern --------------------
         # Python source:
         #     (x := value)
@@ -785,6 +813,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     raise SyntaxError("Assignment expressions are unsupported")
         # -------------------------------------------------
+        if self.rewrite_mode == _RewriteMode.BUILDER:
+            return self.generic_visit(node)
         # Source assignment expressions have no builder declaration contract.
         self._raise_error(node, "Unsupported expression: NamedExpr")
 
@@ -809,6 +839,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     X.setitem_(a, slice(start, stop, step), value)
         # -------------------------------------------------
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return self.generic_visit(node)
         if isinstance(node, ast.Slice):
             return ast.copy_location(
                 ast.Call(
@@ -1024,7 +1056,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     a = X.bind_(temporary, name="a")
         #     b = X.bind_(temporary, name="b")
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         ordinary = any(self._uses_ordinary_binding(target) for target in 
node.targets)
         value_loc = self.module.make_loc_expr(node.value) if ordinary else None
@@ -1077,7 +1109,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             )
         return result
 
-    def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.AnnAssign | 
list[ast.stmt]:
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.stmt | 
list[ast.stmt]:
         # -------------------- Pattern --------------------
         # Python source:
         #     x: X.int32 = value
@@ -1085,7 +1117,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     x = X.decl_mutable_cell_(value, ty=X.int32, name="x")
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         if not isinstance(node.target, ast.Name):
             self._raise_error(node.target, "An annotated binding requires a 
name")
@@ -1100,7 +1132,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             annotation = self.visit(node.annotation)
         return self._bind(node.target, value, node, ty=annotation, 
value_loc=value_loc)
 
-    def visit_AugAssign(self, node: ast.AugAssign) -> ast.AugAssign | 
list[ast.stmt]:
+    def visit_AugAssign(self, node: ast.AugAssign) -> ast.stmt | 
list[ast.stmt]:
         key: ast.expr
         load: ast.expr
         value: ast.expr
@@ -1115,7 +1147,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     X.setitem_(base, key, old + value)
         # -------------------------------------------------
         # Base, index, load and RHS each evaluate once; name targets use 
declaration dispatch.
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         if isinstance(node.target, ast.Name):
             value = ast.copy_location(
@@ -1158,7 +1190,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         )
         return statements
 
-    def visit_Expr(self, node: ast.Expr) -> ast.Expr:
+    def visit_Expr(self, node: ast.Expr) -> ast.stmt:
         # -------------------- Pattern --------------------
         # Python source:
         #     f()
@@ -1166,7 +1198,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     X.emit_(_L_i.ctx(lambda: f()), loc=_L_i)
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         previous, self.emitted_expression = self.emitted_expression, node.value
         try:
@@ -1175,7 +1207,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             self.emitted_expression = previous
         return ast.copy_location(ast.Expr(self._call_dialect("emit_", [value], 
node)), node)
 
-    def visit_Return(self, node: ast.Return) -> ast.Return | ast.Expr:
+    def visit_Return(self, node: ast.Return) -> ast.stmt:
         # -------------------- Pattern --------------------
         # Python source:
         #     return x
@@ -1184,8 +1216,10 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     X.return_(x)
         # -------------------------------------------------
         # Macro and bypass modes retain ordinary Python return.
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return self.generic_visit(node)
         value = self.visit(node.value) if node.value else None
-        if self.preserve_return or self.bypass_ast_rewrite:
+        if self.preserve_return:
             return ast.copy_location(ast.Return(value), node)
         return ast.copy_location(
             ast.Expr(self._call_dialect("return_", [] if value is None else 
[value], node)), node
@@ -1201,7 +1235,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         return (
             node
-            if self.bypass_ast_rewrite
+            if self.rewrite_mode != _RewriteMode.SCRIPT
             else ast.copy_location(ast.Expr(self._call_dialect("break_", [], 
node)), node)
         )
 
@@ -1215,11 +1249,11 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # -------------------------------------------------
         return (
             node
-            if self.bypass_ast_rewrite
+            if self.rewrite_mode != _RewriteMode.SCRIPT
             else ast.copy_location(ast.Expr(self._call_dialect("continue_", 
[], node)), node)
         )
 
-    def visit_Assert(self, node: ast.Assert) -> ast.Assert | ast.Expr:
+    def visit_Assert(self, node: ast.Assert) -> ast.stmt:
         # -------------------- Pattern --------------------
         # Python source:
         #     assert condition, message
@@ -1227,7 +1261,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     X.assert_(condition, message)
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         message = self.visit(node.msg) if node.msg else ast.Constant("")
         return ast.copy_location(
@@ -1242,7 +1276,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             ast.copy_location(ast.Expr(ast.Call(ast.Name(name, ast.Load()), 
[], [])), node),
         ]
 
-    def visit_If(self, node: ast.If) -> ast.If | list[ast.stmt]:
+    def visit_If(self, node: ast.If) -> ast.stmt | list[ast.stmt]:
         # -------------------- Pattern --------------------
         # Python source:
         #     if I.constexpr(flag):
@@ -1253,10 +1287,10 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #         X.emit_(body())
         # -------------------------------------------------
         marker = self._read_constexpr_operand(node.test)
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         if marker is not None:
-            with self._bypass_rewrite():
+            with self.rewrite_mode_scope(_RewriteMode.HOST):
                 condition = self.visit(marker)
             return ast.copy_location(
                 ast.If(
@@ -1353,7 +1387,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     with X.for_(X.grid(n), names="i") as i:
         #         X.emit_(body(i))
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         if node.orelse:
             self._raise_error(node, "A construction loop does not support an 
else clause")
@@ -1426,7 +1460,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #     with X.while_(condition):
         #         X.emit_(body())
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         if node.orelse:
             self._raise_error(node, "A construction loop does not support an 
else clause")
@@ -1448,9 +1482,18 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #         X.emit_(body(value))
         # -------------------------------------------------
         # Ordinary regions use Python locals; native dataflow outputs retain 
identity.
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return self.generic_visit(node)
         item, rest = node.items[0], node.items[1:]
+        if isinstance(item.context_expr, ast.Call):
+            key = 
self.module.prescan_ctx._match_special_func(item.context_expr.func)
+            syntax = protocol_registry.WITH_FRAME_SUGAR.get(key)
+            if syntax is not None:
+                self._raise_error(
+                    item.context_expr,
+                    f"Explicit control-flow frame {key} is not allowed in 
script syntax; "
+                    f"use a {syntax} statement or @T.function.builder",
+                )
         body: list[ast.stmt] = (
             [ast.copy_location(ast.With(rest, node.body), node)] if rest else 
node.body
         )
@@ -1514,14 +1557,23 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         #             X.emit_(body())
         #         build()
         # -------------------------------------------------
-        if self.bypass_ast_rewrite:
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
             return node
-        kind, _ = self.read_function_metadata(node, allow_python=True)
+        kind, _, _ = self.read_function_metadata(node, allow_python=True)
         if kind is None:
             return node
         declaration, _, body = self.create_function_builder_fragments(node, 
local_function=True)
         return [*declaration, body]
 
+    def visit_match_case(self, node: ast.match_case) -> ast.match_case:
+        if self.rewrite_mode == _RewriteMode.SCRIPT:
+            return self.generic_visit(node)
+        # Pattern attributes are syntax, not expressions that can be wrapped.
+        if node.guard is not None:
+            node.guard = self.visit(node.guard)
+        node.body = self.transform_statements(node.body)
+        return node
+
     def visit_Nonlocal(self, node: ast.Nonlocal) -> ast.Pass:
         # -------------------- Pattern --------------------
         # Python source:
@@ -1530,6 +1582,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         # Builder:
         #     pass
         # -------------------------------------------------
+        if self.rewrite_mode != _RewriteMode.SCRIPT:
+            return node
         # Source closure declarations do not mutate the host closure during 
build.
         return ast.copy_location(ast.Pass(), node)
 
@@ -1544,13 +1598,13 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         return node
 
     def generic_visit(self, node: _Node) -> _Node:
-        if isinstance(node, ast.stmt) and not self.bypass_ast_rewrite:
+        if isinstance(node, ast.stmt) and self.rewrite_mode == 
_RewriteMode.SCRIPT:
             self._raise_error(node, f"Unsupported statement: 
{type(node).__name__}")
         return super().generic_visit(node)
 
     def read_function_metadata(
         self, node: ast.FunctionDef, *, allow_python: bool = False
-    ) -> tuple[object | None, ast.Dict]:
+    ) -> tuple[object | None, ast.Dict, protocol_registry.DefinitionKind | 
None]:
         """Read the construction namespace from a qualified source 
decorator."""
         for decorator in node.decorator_list:
             target = decorator.func if isinstance(decorator, ast.Call) else 
decorator
@@ -1562,12 +1616,20 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                 protocol_registry.DefinitionKind.MACRO,
                 protocol_registry.DefinitionKind.PYTHON,
             ):
-                return None, ast.Dict([], [])
-            if kind != protocol_registry.DefinitionKind.FUNCTION:
+                return None, ast.Dict([], []), kind
+            if kind not in (
+                protocol_registry.DefinitionKind.FUNCTION,
+                protocol_registry.DefinitionKind.BUILDER,
+            ):
                 continue
             # A matched decorator is a direct member of a fixed root. 
Construction
             # needs that root's actual builder, not another syntax/value 
resolution.
-            namespace = self.module.environment[target.value.id]
+            root = (
+                target.value.value
+                if kind == protocol_registry.DefinitionKind.BUILDER
+                else target.value
+            )
+            namespace = self.module.environment[root.id]
             if (
                 self.module.root_function_kwargs is not None
                 and self.module.module_name is None
@@ -1576,12 +1638,16 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                 # The public root decorator already evaluated its arguments 
once.
                 # Even an empty mapping overrides the source options 
expression.
                 kwargs = self.module.root_function_kwargs
-                return namespace, ast.copy_location(
-                    ast.Dict(
-                        [ast.Constant(key) for key in kwargs],
-                        [self._inject(value) for value in kwargs.values()],
+                return (
+                    namespace,
+                    ast.copy_location(
+                        ast.Dict(
+                            [ast.Constant(key) for key in kwargs],
+                            [self._inject(value) for value in kwargs.values()],
+                        ),
+                        node,
                     ),
-                    node,
+                    kind,
                 )
             keys, values = [], []
             if isinstance(decorator, ast.Call):
@@ -1591,9 +1657,9 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                     if keyword.arg != "check_well_formed":
                         keys.append(ast.Constant(keyword.arg) if keyword.arg 
is not None else None)
                         values.append(keyword.value)
-            return namespace, ast.copy_location(ast.Dict(keys, values), node)
+            return namespace, ast.copy_location(ast.Dict(keys, values), node), 
kind
         if allow_python:
-            return None, ast.Dict([], [])
+            return None, ast.Dict([], []), None
         self._raise_error(
             node,
             f"Function {node.name!r} requires a qualified construction 
decorator "
@@ -2096,8 +2162,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
         definition snapshot. Signature assignments expose each parameter to 
later
         annotations, while body helpers preserve source globals and closures.
         """
-        kind, options = self.read_function_metadata(node)
-        builder = self._function_namespace(node, kind)
+        namespace, options, kind = self.read_function_metadata(node)
+        builder = self._function_namespace(node, namespace)
         frame, body_name = self.module.make_fresh_name("_fn"), 
self.module.make_fresh_name("_build")
         # Keep the shared module context, but activate fresh lexical state for 
this
         # function. Saving its caller locally avoids a context ownership 
back-reference.
@@ -2107,6 +2173,10 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             parameters = [*node.args.posonlyargs, *node.args.args, 
*node.args.kwonlyargs]
             if node.args.vararg or node.args.kwarg:
                 self._raise_error(node, "IR signatures require ordinary named 
parameters")
+            if kind == protocol_registry.DefinitionKind.BUILDER and (
+                node.args.defaults or any(value is not None for value in 
node.args.kw_defaults)
+            ):
+                self._raise_error(node, "Builder parameters cannot have 
defaults")
             annotations = [parameter.annotation for parameter in parameters]
             returns = node.returns
             captures = self.module.make_fresh_name("_definition")
@@ -2147,8 +2217,8 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                         returns,
                     )
                 )
-            with self._bypass_rewrite():
-                options = self.visit(options)
+            with self.rewrite_mode_scope(_RewriteMode.HOST):
+                options.values = [self.visit(value) for value in 
options.values]
             frame_declaration, body_entry = self._create_function_frame(
                 node,
                 options,
@@ -2165,19 +2235,31 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                 frame=frame,
                 const_args=const_args,
             )
-            body.extend(self.transform_statements(node.body))
+            # Builder mode shares declarations and locations, but its body 
keeps
+            # Python control flow and bindings; only explicit calls construct 
IR.
+            if kind == protocol_registry.DefinitionKind.BUILDER:
+                with self.rewrite_mode_scope(_RewriteMode.BUILDER):
+                    body.extend(self.transform_statements(node.body))
+            else:
+                body.extend(self.transform_statements(node.body))
             definition = self._create_definition(body_name, body, node)
             if not local_function:
                 protected = (
                     {item.name for item in getattr(node, "type_params", ())}
                     | {node.name}
                     | set(self.module.global_func_names)
-                    | self.module.prescan_ctx.namespaces.keys()
                 )
+                if kind != protocol_registry.DefinitionKind.BUILDER:
+                    protected |= self.module.prescan_ctx.namespaces.keys()
                 if self.module.module_name:
                     protected.add(self.module.module_name)
                 self.module.generated_builders.append(
-                    GeneratedBuilder(definition, node.name, protected)
+                    GeneratedBuilder(
+                        definition,
+                        node.name,
+                        protected,
+                        kind == protocol_registry.DefinitionKind.BUILDER,
+                    )
                 )
             # -------------------- Pattern --------------------
             # Python source:
@@ -2331,7 +2413,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
             if not isinstance(member, ast.FunctionDef):
                 # Source class statements are host setup inside the native 
module;
                 # global-info registration therefore precedes dependent 
annotations.
-                with self._bypass_rewrite():
+                with self.rewrite_mode_scope(_RewriteMode.HOST):
                     body.append(self.visit(member))
                 targets = (
                     member.targets
@@ -2351,7 +2433,7 @@ class IRBuilderTranspiler(ast.NodeTransformer):
                         body.append(self._assign(target.id, value, target))
                 continue
             function = member
-            kind, _ = self.read_function_metadata(function)
+            kind, _, _ = self.read_function_metadata(function)
             if kind is None:
                 # -------------------- Pattern --------------------
                 # Python source:
diff --git a/python/tvm_tirx/tirx/script/__init__.py 
b/python/tvm_tirx/tirx/script/__init__.py
index 602b4d083..5ca4eb940 100644
--- a/python/tvm_tirx/tirx/script/__init__.py
+++ b/python/tvm_tirx/tirx/script/__init__.py
@@ -32,7 +32,7 @@ def _initialize() -> None:
     _initializing = True
     try:
         from tvm_tirx.ir._expose_api import _init_exposed_type_api
-        from tvm_tirx.script.parser import entry, register_namespace
+        from tvm_tirx.script.parser import entry, protocol_registry, 
register_namespace
         from tvm_tirx.tirx.layout import Axis
 
         from . import ir_builder as builder
@@ -53,6 +53,66 @@ def _initialize() -> None:
             ),
             jit=make_jit(builder, namespace_path="tirx.jit"),
         )
+        globals()["function"].builder = entry.make_decorator(
+            builder,
+            namespace_path="tirx.function.builder",
+            definition_kind=protocol_registry.DefinitionKind.BUILDER,
+        )
+        globals()["function"].builder.__doc__ = """Build a TIRx function with 
Python body semantics.
+
+        Use at the definition site with inspectable source. Assignments, loops,
+        conditionals and returns execute as Python; explicit 
``T.serial``-family
+        frames, ``T.if_``/``T.then_``/``T.else_``, ``T.assign``, ``T.bind_`` 
and
+        ``T.return_`` construct IR. Signature annotations are re-evaluated from
+        source, including postponed annotations; write expressions without 
quotes.
+
+        Shares ``T.function`` options, expression locations and module 
declarations.
+        Statement locations are not injected: explicit frames, void emissions 
and
+        IR emitted inside ordinary Python helpers may have unknown locations.
+        Use ``T.call_global_var_(callee, args)`` for explicit IR function 
calls.
+        The resulting IR prints as ordinary ``@T.function`` TVMScript.
+
+        Examples
+        --------
+        Python loops execute while building; ``T.serial`` creates an IR loop:
+
+        .. code-block:: python
+
+            from tvm_tirx.script import tirx as T
+
+            @T.function.builder
+            def add_rows(A: T.Tensor((2, 4), T.float32), B: T.Tensor((2, 4), 
T.float32)):
+                for row in range(2):
+                    with T.serial(4) as col:
+                        T.assign(B[row, col], A[row, col] + 1)
+
+        Mixed modules share declarations, so explicit calls can refer to a 
later
+        function:
+
+        .. code-block:: python
+
+            @T.ir_module
+            class Module:
+                @T.function.builder
+                def main(A: T.Tensor((4,), T.int32)):
+                    with T.serial(4) as i:
+                        T.assign(A[i], T.call_global_var_(Module.add_one, 
[A[i]]))
+
+                @T.function
+                def add_one(value: T.int32) -> T.int32:
+                    return value + 1
+        """
+        for name, syntax in {
+            "serial": "for",
+            "parallel": "for",
+            "unroll": "for",
+            "vectorized": "for",
+            "grid": "for",
+            "for_": "for",
+            "if_": "if",
+            "while_": "while",
+        }.items():
+            protocol_registry.WITH_FRAME_SUGAR[f"tirx.{name}"] = syntax
         namespace = _sys.modules[__name__]
         register_namespace("tirx", namespace)
         register_namespace("Axis", Axis)
diff --git a/tests/python/tirx/script/test_function_builder.py 
b/tests/python/tirx/script/test_function_builder.py
new file mode 100644
index 000000000..8b09726a6
--- /dev/null
+++ b/tests/python/tirx/script/test_function_builder.py
@@ -0,0 +1,262 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Python construction semantics, shared declarations and source 
diagnostics."""
+
+import linecache
+from types import SimpleNamespace
+
+import pytest
+
+from tvm_tirx import ir
+from tvm_tirx.script import from_source
+from tvm_tirx.script import ir as I
+from tvm_tirx.script import tirx as T
+from tvm_tirx.script.ir_builder import IRBuilder
+
+
+def test_builder_python_semantics_and_sugar_round_trip(monkeypatch):
+    visited = []
+    counter = 0
+    monkeypatch.setitem(globals(), "_builder_global", 0)
+
+    def read_counter():
+        return counter
+
+    @T.function.builder(private=True)
+    def built(A: T.Tensor((4,), T.int32)):
+        global _builder_global
+        nonlocal counter
+        counter += 1
+        _builder_global += 1
+
+        def bump():
+            nonlocal counter
+            counter += 1
+
+        bump()
+        assert read_counter() == 2 and globals()["_builder_global"] == 1
+        _host0 = _L_0 = 7
+        assert _host0 == _L_0 == 7
+        I = SimpleNamespace(constexpr=lambda value: visited.append(value) or 
value)  # noqa: E741
+        assert I.constexpr(7) == 7 and visited == [7]
+        assert not (False and visited.append("and"))
+        assert True or visited.append("or")
+        assert (3 if True else visited.append("if")) == 3
+        I.value = 7
+        match 7:
+            case I.value if visited.append("guard") is None:
+                assert visited == [7, "guard"]
+            case _:
+                raise AssertionError("unreachable")
+        visited.clear()
+        try:
+            raise ValueError("caught")
+        except ValueError as error:
+            assert str(error) == "caught"
+        finally:
+            temporary = 1
+        del temporary
+        assert "temporary" not in locals()
+        indices = [0, 1, 2]
+        indices[1:2] = [3]
+        visited.append(first := indices[0])
+        local_values = locals
+        assert first == 0 and local_values()["first"] == 0
+        visited.clear()
+        for offset in indices:
+            if offset == 3:
+                continue
+            visited.append(offset)
+            T.assign(A[0], offset)
+        count = 0
+        while count < 2:
+            count += 1
+            if count == 2:
+                break
+        assert count == 2 and visited == [0, 2]
+        with T.device_entry():
+            with T.grid(2, 2) as (i, j):
+                value = T.bind_(i + j, name="value")
+                with T.if_(value > 0):
+                    with T.then_():
+                        T.assign(A[value], value + 1)
+                    with T.else_():
+                        T.assign(A[value], 0)
+        return
+        T.assign(A[0], 99)
+
+    @T.function(private=True)
+    def expected(A: T.Tensor((4,), T.int32)):
+        A[0] = 0
+        A[0] = 2
+        with T.device_entry():
+            for i, j in T.grid(2, 2):
+                value = i + j
+                if value > 0:
+                    T.assign(A[value], value + 1)
+                else:
+                    T.assign(A[value], 0)
+
+    assert visited == [0, 2] and counter == 2 and _builder_global == 1
+    ir.assert_structural_equal(built, expected)
+    printed = built.script()
+    assert "@T.function(private=True)" in printed and ".builder" not in printed
+    ir.assert_structural_equal(built, from_source(printed, extra_vars={"T": 
T}))
+
+
[email protected]("namespace", [I, T])
+def test_builder_mixed_module_forward_declarations(namespace):
+    helper = SimpleNamespace(leaf=lambda value: value + 2)
+
+    @namespace.ir_module
+    class Mixed:
+        @T.function.builder
+        def built(A: T.Tensor((4,), T.int32)):
+            def leaf(value):
+                return value + 1
+
+            assert leaf(4) == 5
+            module = Mixed
+            with T.serial(4) as i:
+                T.assign(A[i], T.call_global_var_(module.sugar, [i]))
+            T.call_global_var_(Mixed.store, [A])
+            for module in [helper]:
+                assert module.leaf(4) == 6
+            from math import floor as leaf
+
+            assert leaf(4.1) == 4
+
+        @T.function
+        def sugar(value: T.int32) -> T.int32:
+            return Mixed.leaf(value)
+
+        @T.function.builder(private=True)
+        def leaf(value: T.int32) -> T.int32:
+            T.return_(value + 1)
+
+        @T.function.builder
+        def store(A: T.Tensor((4,), T.int32)):
+            T.assign(A[0], 1)
+
+    call = Mixed["built"].body[0].body[0].value
+    assert call.op.same_as(Mixed.get_global_var("sugar"))
+    assert 
Mixed["sugar"].body[0].value.op.same_as(Mixed.get_global_var("leaf"))
+    assert len(Mixed["built"].body) == 2
+    assert 
Mixed["built"].body[1].value.op.same_as(Mixed.get_global_var("store"))
+    ir.assert_structural_equal(Mixed, from_source(Mixed.script(), 
extra_vars={"T": T, "I": I}))
+
+
+def test_builder_annotations_options_and_locations(monkeypatch):
+    checked = []
+    monkeypatch.setattr(T, "check_well_formed_", checked.append)
+    dtype = T.int32
+    tensor = T.Tensor((4,), dtype)
+
+    def helper(A):
+        T.assign(A[0], A[0] + 1)
+
+    @T.function.builder(private=True, persistent=True)
+    def built(A: tensor, /, value: dtype, *, step: dtype) -> dtype:
+        with T.serial(4) as i:
+            T.assign(A[i], (value + step) * (i + 1))
+        helper(A)
+        T.return_(value)
+
+    assert checked == [built]
+    assert "global_symbol" not in built.attrs and 
built.attrs["tirx.persistent_kernel"] == 1
+    assert [parameter.name for parameter in built.params] == ["A", "value", 
"step"]
+    assert built.params[0].ty.same_as(tensor) and built.ret_type == 
ir.PrimType("int32")
+    parameter = built.params[0].loc
+    assert (
+        linecache.getline(__file__, parameter.start_line)[
+            parameter.start_column - 1 : parameter.end_column - 1
+        ]
+        == "A: tensor"
+    )
+    loop, helper_store, _ = built.body.seq
+    assert isinstance(loop.loc, ir.UnknownLoc)
+    store = loop.body[0]
+    expression = store.value.a.loc
+    assert (
+        linecache.getline(__file__, expression.start_line)[
+            expression.start_column - 1 : expression.end_column - 1
+        ]
+        == "value + step"
+    )
+    assert "T.assign(A[i]" in linecache.getline(__file__, store.loc.start_line)
+    assert isinstance(helper_store.loc, ir.UnknownLoc)
+    assert isinstance(helper_store.value.loc, ir.UnknownLoc)
+
+    source = (
+        "from __future__ import annotations\n"
+        "@T.function.builder(check_well_formed=False)\n"
+        "def future(n: T.int32, A: T.Tensor((n,), T.int32)): T.assign(A[0], 
n)\n"
+    )
+    future = from_source(source, extra_vars={"T": T})
+    assert future.params[0].ty == ir.PrimType("int32") and checked == [built]
+    with pytest.raises(RuntimeError, match="body failed"):
+
+        @T.function.builder
+        def failed():
+            T.evaluate(0)
+            raise RuntimeError("body failed")
+
+    assert not IRBuilder.is_in_scope()
+
+
[email protected](
+    "source, message",
+    [
+        ("def f(value): pass", "requires an annotation"),
+        ("def f(value: T.int32 = 1): pass", "cannot have defaults"),
+        ("def f(*values: T.int32): pass", "ordinary named parameters"),
+        ("def f(): yield 1", "Unsupported expression: Yield"),
+        ('def f(value: "T.int32"): pass', "Quoted annotations are not 
supported"),
+        ('def f() -> "T.int32": pass', "Quoted annotations are not supported"),
+    ],
+)
+def test_builder_source_errors_and_cleanup(source, message):
+    with pytest.raises(SyntaxError, match=message) as error:
+        from_source("@T.function.builder\n" + source, extra_vars={"T": T})
+    assert (error.value.filename, error.value.lineno) == ("<str>", 2)
+    assert not IRBuilder.is_in_scope()
+
+
[email protected](
+    "context, sugar",
+    [
+        ("serial(4)", "for"),
+        ("parallel(4)", "for"),
+        ("unroll(4)", "for"),
+        ("vectorized(4)", "for"),
+        ("grid(2, 3)", "for"),
+        ("for_(range(4))", "for"),
+        ("if_(True)", "if"),
+        ("while_(True)", "while"),
+    ],
+)
+def test_parser_rejects_explicit_control_frames_at_source(context, sugar):
+    source = (
+        f"@X.function\ndef f():\n    with X.device_entry(), X.{context}:\n     
   X.evaluate(0)\n"
+    )
+    with pytest.raises(
+        SyntaxError, match=f"use a {sugar} statement or @T.function.builder"
+    ) as error:
+        from_source(source, extra_vars={"X": T})
+    assert (error.value.filename, error.value.lineno) == ("<str>", 3)
+    assert error.value.offset == source.splitlines()[2].index(f"X.{context}") 
+ 1
+    assert error.value.end_offset == len(source.splitlines()[2])

Reply via email to