Deprecate ir.Input in favor of ir.val (#185)

Deprecate `ir.Input` in favor of the clearer `ir.val`, since `ir.Input`
doesn't really create "Inputs" but instead is a convenience for creating
a value.

---------

Signed-off-by: Justin Chu <justinchuby@users.noreply.github.com>

Author: justinchuby

docs/getting_started.ipynb

@@ -15,7 +15,7 @@ An in-memory IR that supports the full ONNX spec, designed for graph constructio
 ## Get started
 
 ```{toctree}
-:maxdepth: 1
+:maxdepth: 2
 
 Overview <self>
 getting_started

docs/index.md

@@ -293,7 +293,7 @@ def replace_all_uses_with(
     We want to replace the node A with a new node D::
 
         >>> import onnx_ir as ir
-        >>> input = ir.Input("input")
+        >>> input = ir.val("input")
         >>> node_a = ir.Node("", "A", [input])
         >>> node_b = ir.Node("", "B", node_a.outputs)
         >>> node_c = ir.Node("", "C", node_a.outputs)

src/onnx_ir/_convenience/__init__.py

@@ -159,16 +159,16 @@ def node(
     doc_string: str | None = None,
     metadata_props: dict[str, str] | None = None,
 ) -> ir.Node:
-    """Create an :class:`~onnx_ir.Node`.
+    """Create a :class:`~onnx_ir.Node`.
 
     This is a convenience constructor for creating a Node that supports Python
     objects as attributes.
 
     Example::
 
         >>> import onnx_ir as ir
-        >>> input_a = ir.Input("A", shape=ir.Shape([1, 2]), type=ir.TensorType(ir.DataType.INT32))
-        >>> input_b = ir.Input("B", shape=ir.Shape([1, 2]), type=ir.TensorType(ir.DataType.INT32))
+        >>> input_a = ir.val("A", shape=[1, 2], type=ir.TensorType(ir.DataType.INT32))
+        >>> input_b = ir.val("B", shape=[1, 2], type=ir.TensorType(ir.DataType.INT32))
         >>> node = ir.node(
         ...     "SomeOp",
         ...     inputs=[input_a, input_b],
@@ -218,7 +218,7 @@ def node(
 
 
 def val(
-    name: str,
+    name: str | None,
     dtype: ir.DataType | None = None,
     shape: ir.Shape | Sequence[int | str | None] | None = None,
     *,
@@ -255,7 +255,7 @@ def val(
             when you want to create an initializer. The type and shape can be obtained from the tensor.
 
     Returns:
-        A value with the given name and type.
+        A Value object.
     """
     if const_value is not None:
         const_tensor_type = _core.TensorType(const_value.dtype)

src/onnx_ir/_convenience/_constructors.py

@@ -45,7 +45,7 @@
 
 import ml_dtypes
 import numpy as np
-from typing_extensions import TypeIs
+from typing_extensions import TypeIs, deprecated
 
 import onnx_ir
 from onnx_ir import (
@@ -2275,6 +2275,7 @@ def is_initializer(self) -> bool:
         return self._is_initializer
 
 
+@deprecated("Input is deprecated since 0.1.9. Use ir.val(...) instead.")
 def Input(
     name: str | None = None,
     shape: Shape | None = None,

src/onnx_ir/_core.py

@@ -166,7 +166,7 @@ def _simple_model(self) -> ir.Model:
         node_0 = ir.Node(
             "",
             "Op_0",
-            inputs=[ir.Input("input_0"), ir.Input("input_1")],
+            inputs=[ir.val("input_0"), ir.val("input_1")],
             num_outputs=2,
             name="node_0",
         )

src/onnx_ir/external_data_test.py

@@ -16,7 +16,7 @@ class TestIdentityEliminationPass(unittest.TestCase):
     def test_eliminate_identity_not_graph_output(self):
         """Test: y = Identity(x) where y is not a graph output."""
         # Create a simple model: input -> Identity -> Add -> output
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -110,7 +110,7 @@ def test_eliminate_identity_with_output_renaming(self):
     def test_keep_identity_when_both_input_and_output_are_graph_boundaries(self):
         """Test: y = Identity(x) where y is graph output AND x is graph input."""
         # Create graph input
-        input_value = ir.Input(
+        input_value = ir.val(
             "graph_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -150,7 +150,7 @@ def test_keep_identity_when_both_input_and_output_are_graph_boundaries(self):
     def test_multiple_identity_nodes(self):
         """Test elimination of multiple Identity nodes in different scenarios."""
         # Create graph input
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -203,7 +203,7 @@ def test_multiple_identity_nodes(self):
 
     def test_invalid_identity_node_skipped(self):
         """Test that invalid Identity nodes are skipped."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -261,7 +261,7 @@ def test_identity_with_none_input_skipped(self):
 
     def test_no_identity_nodes(self):
         """Test pass on a graph with no Identity nodes."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -311,7 +311,7 @@ def test_empty_graph(self):
 
     def test_chain_of_identities(self):
         """Test elimination of a chain of Identity nodes."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -362,7 +362,7 @@ def test_chain_of_identities(self):
 
     def test_non_standard_domain_identity_skipped(self):
         """Test that Identity nodes with non-standard domain are skipped."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -404,7 +404,7 @@ def test_non_standard_domain_identity_skipped(self):
 
     def test_non_identity_node_skipped(self):
         """Test that non-Identity nodes are skipped (covers line 55)."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -438,7 +438,7 @@ def test_non_identity_node_skipped(self):
     def test_function_with_identity_elimination(self):
         """Test that Identity nodes in functions are processed."""
         # Create function with Identity node
-        func_input = ir.Input(
+        func_input = ir.val(
             "func_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -470,7 +470,7 @@ def test_function_with_identity_elimination(self):
         )
 
         # Create a main graph
-        main_input = ir.Input(
+        main_input = ir.val(
             "main_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -508,7 +508,7 @@ def test_function_with_identity_elimination(self):
 
     def test_multiple_graph_outputs_with_identity(self):
         """Test case where graph has multiple outputs and only one is the Identity output."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 

src/onnx_ir/passes/common/identity_elimination_test.py

@@ -16,7 +16,7 @@ class TestNameFixPass(unittest.TestCase):
     def test_assign_names_to_unnamed_values(self):
         """Test ensuring all values have names even if IR auto-assigned them."""
         # Create a simple model with auto-assigned names
-        input_value = ir.Input(
+        input_value = ir.val(
             None, shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )  # Will get auto-assigned name when added to graph
 
@@ -53,7 +53,7 @@ def test_assign_names_to_unnamed_values(self):
     def test_assign_names_to_unnamed_nodes(self):
         """Test ensuring all nodes have names even if IR auto-assigned them."""
         # Create a simple model
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -88,7 +88,7 @@ def test_assign_names_to_unnamed_nodes(self):
     def test_assigns_names_when_truly_unnamed(self):
         """Test that the pass assigns names when values/nodes are created without names and manually cleared."""
         # Create a model and manually clear names to test assignment
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -124,13 +124,13 @@ def test_assigns_names_when_truly_unnamed(self):
     def test_handles_global_uniqueness_across_subgraphs(self):
         """Test that names are unique globally, including across subgraphs."""
         # Create main graph input
-        main_input = ir.Input(
+        main_input = ir.val(
             "main_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
         # Create a simple subgraph for an If node
         # Subgraph input and output (with potential name conflicts)
-        sub_input = ir.Input(
+        sub_input = ir.val(
             "main_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )  # Same name as main input - should cause conflict
 
@@ -147,7 +147,7 @@ def test_handles_global_uniqueness_across_subgraphs(self):
         )
 
         # Create condition input for If node
-        condition_input = ir.Input(
+        condition_input = ir.val(
             "condition", shape=ir.Shape([]), type=ir.TensorType(ir.DataType.BOOL)
         )
 
@@ -236,10 +236,10 @@ def test_handles_global_uniqueness_across_subgraphs(self):
     def test_handle_duplicate_value_names(self):
         """Test handling duplicate value names by making them unique."""
         # Create values with duplicate names
-        input1 = ir.Input(
+        input1 = ir.val(
             "duplicate_name", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
-        input2 = ir.Input(
+        input2 = ir.val(
             "duplicate_name", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -276,7 +276,7 @@ def test_handle_duplicate_value_names(self):
 
     def test_handle_duplicate_node_names(self):
         """Test handling duplicate node names by making them unique."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -321,7 +321,7 @@ def test_handle_duplicate_node_names(self):
 
     def test_no_modification_when_all_names_unique(self):
         """Test that the pass doesn't modify anything when all names are already unique."""
-        input_value = ir.Input(
+        input_value = ir.val(
             "unique_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 
@@ -359,7 +359,7 @@ def test_no_modification_when_all_names_unique(self):
     def test_graph_inputs_outputs_have_precedence(self):
         """Test that graph inputs and outputs keep their names when there are conflicts."""
         # Create an input with a specific name
-        input_value = ir.Input(
+        input_value = ir.val(
             "important_input", shape=ir.Shape([2, 2]), type=ir.TensorType(ir.DataType.FLOAT)
         )
 

src/onnx_ir/passes/common/naming_test.py

@@ -711,7 +711,7 @@ def _deserialize_graph(
 
     # Create values for initializers and inputs
     initializer_tensors = [deserialize_tensor(tensor) for tensor in proto.initializer]
-    inputs = [_core.Input(info.name) for info in proto.input]
+    inputs = [_core.Value(name=info.name) for info in proto.input]
     for info, value in zip(proto.input, inputs):
         deserialize_value_info_proto(info, value)
 
@@ -869,7 +869,7 @@ def deserialize_function(proto: onnx.FunctionProto) -> _core.Function:
     Returns:
         An IR Function object representing the ONNX function.
     """
-    inputs = [_core.Input(name) for name in proto.input]
+    inputs = [_core.Value(name=name) for name in proto.input]
     values: dict[str, _core.Value] = {v.name: v for v in inputs}  # type: ignore[misc]
     value_info = {info.name: info for info in getattr(proto, "value_info", [])}
 

src/onnx_ir/serde.py

@@ -447,7 +447,7 @@ def test_deserialize_graph_handles_unsorted_graph(self):
         node_0 = ir.Node(
             "",
             "Op_0",
-            inputs=[ir.Input("input_0"), ir.Input("input_1")],
+            inputs=[ir.val("input_0"), ir.val("input_1")],
             num_outputs=2,
             name="node_0",
         )