Supported Python subset¶
@script() translates a subset of Python into ONNX when the decorator runs.
Calling the resulting function runs its original Python body eagerly, with
ONNX operators evaluated by the selected evaluator. A construct that runs
eagerly is not necessarily exportable.
This page lists the supported forms. See the tutorial for type annotations, attributes, constants, and complete examples.
Syntax and execution boundary¶
Construct |
Compiled ONNX |
Eager execution / boundary |
|---|---|---|
Tensor arithmetic and comparisons |
Expressions such as |
Tensor wrappers follow ONNX operator semantics, not NumPy promotion rules. Arbitrary Python or NumPy calls are not translated. |
Chained comparisons |
|
Python evaluates chained comparisons with truth testing, not elementwise conjunction. |
Returns |
Return a value, or a tuple of output values, at function-body level, after any control flow. A nested graph function has its own function-body return and return annotation. |
Eager execution preserves a Python tuple of outputs. Exported model runners instead return an ordered list of graph outputs. |
Return inside control flow |
A |
Early returns run eagerly but cannot be exported. |
Conditional statements |
|
Use a scalar Boolean tensor as the condition. Both branches must produce matching ONNX types. |
Loops |
|
Eager mode runs the Python loop. |
Indexing and slicing |
Scalar indices and slices such as |
If the step is a runtime value, both bounds must be explicit: |
Nested graph functions |
Define |
Eager evaluation requires the |
Captured graph values |
A captured value must not be reassigned between graph definition and graph use. |
Pass state through explicit graph inputs and outputs. |
For example, use a single return after the conditional:
from onnxscript import BOOL, FLOAT, opset17 as op, script
@script()
def choose(x: FLOAT["N"], condition: BOOL) -> FLOAT["N"]:
if condition:
result = op.Add(x, 1)
else:
result = op.Sub(x, 1)
return result
See the tutorial’s control-flow and graph-attribute examples for complete loops and nested graphs. Script-time constant attribute expressions follow the rules in the script constants section.
Printing is a debugging aid¶
A standalone print(...) statement is allowed but omitted from the compiled
graph, including its arguments. It runs in eager mode, so it can be used to
inspect eager values. Other expression statements and Python I/O are not
exported.
Custom operators are a separate execution contract¶
An operator call qualified by an Opset can target a custom domain:
from onnxscript import script, values
custom = values.Opset("example.custom", 1)
@script()
def transform(x):
return custom.Transform(x, mode="fast")
The compiler emits this node even without a registered operator schema. Without a schema, positional arguments become ONNX inputs and keyword arguments become ONNX attributes; schema-based argument checks and scalar casts are skipped. The compiler does not verify that the operator exists, so a misspelled operator name may not be caught at decoration time.
Running the node requires a runtime implementation (or an included ONNX function). The built-in eager evaluators require an operator schema.
Compiler/eager parity and return conventions¶
The paired tests in tests/eager_mode_test.py export models, run them, and
compare the results with eager execution of the original Python bodies. They
check values, dtypes, shapes, output counts, and output types for:
Boundary |
Representative coverage |
|---|---|
Optional operator inputs |
|
Function arguments |
Default and explicit scalar attribute arguments, and out-of-order keyword arguments. |
Scalar promotion |
Literals mixed with |
Output wrapping |
Rank-zero and vector arrays, tensor wrappers, mixed array/tensor inputs, single outputs, and tuples of outputs. |
Control flow and graph attributes |
Both conditional branches, zero and nonzero loop counts, forward/reverse/dynamic slices, separate comparisons, and a directly nested |
Eager input and output conventions: Python integer inputs become int64
tensors and Python float inputs use NumPy’s default floating dtype. If any
tensor input is a NumPy array (including one in an input sequence), eager
tensor results are returned as NumPy arrays. With only onnxscript.tensor.Tensor
or Python scalar inputs, results are returned as Tensor objects. Tuple and
list containers are preserved, and a single output is not wrapped in a tuple.
Attribute arguments do not affect output wrapping.
Tests run under both ONNX Runtime and ONNX’s reference evaluator, with these
reference-evaluator exceptions: local-function calls with omitted attribute
defaults and counted loops with an omitted initial condition run the exported
model with ONNX Runtime only; the captured-value Scan case is skipped for the
reference evaluator when its Scan implementation does not pass outer-scope
values to the body.
Negative syntax and custom-domain/printing boundaries are covered in
tests/language_support_test.py.