Merge feature/example-arrow-type into test/example-functions-serialization

Resolve conflict in tests/test_argument_spec.py by keeping both:
- TestExampleFunctionsSerialization (from this branch)
- TestArgumentSpecRepr (from feature/example-arrow-type)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rustyconover

tests/test_argument_spec.py

@@ -769,3 +769,57 @@ def test_double_column_uses_explicit_utf8(self) -> None:
         specs = extract_argument_specs(DoubleColumnFunction)
         column_spec = next(s for s in specs if s.name == "column")
         assert column_spec.arrow_type == pa.utf8()
+
+
+class TestArgumentSpecRepr:
+    """Test ArgumentSpec __repr__ method."""
+
+    def test_positional_argument_repr(self) -> None:
+        """Positional argument should show integer position."""
+        spec = ArgumentSpec(name="count", position=0, arrow_type=pa.int64())
+        result = repr(spec)
+        assert 'name="count"' in result
+        assert "pos=0" in result
+        assert "int64" in result
+        assert "flags=" not in result  # No flags when all False
+
+    def test_named_argument_repr(self) -> None:
+        """Named argument should show quoted string position."""
+        spec = ArgumentSpec(name="format", position="format", arrow_type=pa.utf8())
+        result = repr(spec)
+        assert 'name="format"' in result
+        assert 'pos="format"' in result
+        assert "string" in result or "utf8" in result
+
+    def test_flags_shown_when_true(self) -> None:
+        """Flags should only appear when True."""
+        spec = ArgumentSpec(
+            name="data",
+            position=0,
+            arrow_type=pa.null(),
+            is_table_input=True,
+        )
+        result = repr(spec)
+        assert "flags=[table_input]" in result
+
+    def test_multiple_flags(self) -> None:
+        """Multiple flags should all be shown."""
+        spec = ArgumentSpec(
+            name="cols",
+            position=0,
+            arrow_type=pa.utf8(),
+            is_varargs=True,
+        )
+        result = repr(spec)
+        assert "varargs" in result
+
+    def test_any_type_flag(self) -> None:
+        """any_type flag should be shown."""
+        spec = ArgumentSpec(
+            name="value",
+            position=0,
+            arrow_type=pa.null(),
+            is_any_type=True,
+        )
+        result = repr(spec)
+        assert "any_type" in result

vgi/argument_spec.py

@@ -109,6 +109,17 @@ class ArgumentSpec:
         is_varargs: True if this argument collects all remaining positional
             arguments (varargs=True).
 
+    Note:
+        For named arguments, the Python attribute name (``name``) and the SQL
+        key (``position``) are assumed to be identical. This is the standard
+        convention::
+
+            format = Arg[str]("format")  # name="format", position="format"
+
+        If they differ, the ``position`` value will be lost during schema
+        round-trip serialization, as only ``name`` is stored in the Arrow
+        schema field name.
+
     """
 
     name: str
@@ -118,6 +129,27 @@ class ArgumentSpec:
     is_any_type: bool = False
     is_varargs: bool = False
 
+    def __repr__(self) -> str:
+        """Return concise repr showing key attributes."""
+        # Build position display: integer or quoted string
+        pos = self.position if isinstance(self.position, int) else f'"{self.position}"'
+
+        # Build flags list (only show if True)
+        flags = []
+        if self.is_table_input:
+            flags.append("table_input")
+        if self.is_any_type:
+            flags.append("any_type")
+        if self.is_varargs:
+            flags.append("varargs")
+
+        flags_str = f", flags=[{', '.join(flags)}]" if flags else ""
+
+        return (
+            f'ArgumentSpec(name="{self.name}", pos={pos}, '
+            f"type={self.arrow_type}{flags_str})"
+        )
+
 
 # =============================================================================
 # Serialization Functions

vgi/arguments.py

@@ -530,6 +530,19 @@ def transform(self, batch):
                 # Validation happens automatically on first access
                 ...
 
+    Note:
+        For named arguments (string position), the Python attribute name should
+        match the SQL key. This is the standard convention::
+
+            format = Arg[str]("format")  # Recommended: attribute == key
+
+        Avoid using different names::
+
+            output_format = Arg[str]("format")  # Not recommended
+
+        While this works at runtime, it can cause issues with metadata
+        serialization where only one name is preserved.
+
     """
 
     __slots__ = (