Move is_default from SchemaInfo to default_schema on CatalogAttachResult

Replace the is_default boolean field on SchemaInfo with a default_schema
string field on CatalogAttachResult. This makes the default schema a
property of the catalog attachment rather than each schema.

Changes:
- CatalogAttachResult: Add default_schema field
- SchemaInfo: Remove is_default field
- Update all catalog implementations and tests
- Update documentation

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

Author: rustyconover

README.md

@@ -19,6 +19,7 @@
 
 ```python
 # my_worker.py
+from typing import Annotated
 from vgi import ScalarFunction, Arg, Worker
 import pyarrow as pa
 import pyarrow.compute as pc
@@ -29,7 +30,7 @@ class Greeting(ScalarFunction):
     class Meta:
         output_type = pa.string()
 
-    col_name = Arg[str](0, doc="Column containing names")
+    col_name: Annotated[str, Arg(0, doc="Column containing names")]
 
     def compute(self, batch: pa.RecordBatch) -> pa.Array:
         names = batch.column(self.col_name)
@@ -106,6 +107,7 @@ A worker is a Python script that defines one or more functions:
 ```python
 #!/usr/bin/env python
 # my_worker.py
+from typing import Annotated
 import pyarrow as pa
 import pyarrow.compute as pc
 from vgi import ScalarFunction, Arg, Worker
@@ -117,7 +119,7 @@ class UpperCase(ScalarFunction):
     class Meta:
         output_type = pa.string()
 
-    col_name = Arg[str](0, doc="Column to uppercase")
+    col_name: Annotated[str, Arg(0, doc="Column to uppercase")]
 
     def compute(self, batch: pa.RecordBatch) -> pa.Array:
         return pc.utf8_upper(batch.column(self.col_name))
@@ -155,11 +157,11 @@ Your function is now available in DuckDB. Ship the Python script to your team, a
 
 ## Going Further: Type-Safe Arguments
 
-For production use, you'll want type validation. Use `Arg[AnyArrow]` with `type_bound` to ensure columns have the correct type:
+For production use, you'll want type validation. Use `AnyArrowValue` with `type_bound` to ensure columns have the correct type:
 
 ```python
-from vgi import ScalarFunction, Arg, Worker
-from vgi.arguments import AnyArrow
+from typing import Annotated
+from vgi import ScalarFunction, Arg, AnyArrowValue, Worker
 import pyarrow as pa
 import pyarrow.compute as pc
 
@@ -170,8 +172,8 @@ class AddColumns(ScalarFunction):
     class Meta:
         output_type = pa.int64()
 
-    left = Arg[AnyArrow](0, type_bound=pa.types.is_integer, doc="First column")
-    right = Arg[AnyArrow](1, type_bound=pa.types.is_integer, doc="Second column")
+    left: Annotated[AnyArrowValue, Arg(0, type_bound=pa.types.is_integer, doc="First column")]
+    right: Annotated[AnyArrowValue, Arg(1, type_bound=pa.types.is_integer, doc="Second column")]
 
     def compute(self, batch: pa.RecordBatch) -> pa.Array:
         return pc.add(
@@ -188,8 +190,8 @@ SELECT add_columns(price, tax) as total FROM orders;
 -- Error: Column 'name' has type string, expected integer
 ```
 
-Key differences from `Arg[str]`:
-- `Arg[AnyArrow]` validates the column's Arrow type at bind time
+Key differences from `Annotated[str, Arg(...)]`:
+- `AnyArrowValue` validates the column's Arrow type at bind time
 - `type_bound` specifies which types are allowed
 - Access the column name via `.value` (e.g., `self.left.value`)
 
@@ -214,7 +216,7 @@ class Double(ScalarFunction):
     class Meta:
         output_type = pa.int64()
 
-    col_name = Arg[str](0)
+    col_name: Annotated[str, Arg(0)]
 
     def compute(self, batch: pa.RecordBatch) -> pa.Array:
         return pc.multiply(batch.column(self.col_name), 2)
@@ -229,7 +231,7 @@ class Sequence(TableFunctionGenerator):
     class Meta:
         max_workers = 1
 
-    count = Arg[int](0)
+    count: Annotated[int, Arg(0)]
 
     @property
     def output_schema(self) -> pa.Schema:
@@ -257,7 +259,7 @@ class Sum(TableInOutFunction):
     class Meta:
         max_workers = 1  # Aggregations need single worker
 
-    col_name = Arg[str](0)
+    col_name: Annotated[str, Arg(0)]
 
     def bind(self) -> None:
         self.total = 0

docs/argument-serialization.md

@@ -36,10 +36,10 @@ Positional arguments have no special metadata. Their position index is
 determined by their order in the schema.
 
 ```python
-# Arg[int](0) becomes:
+# count: Annotated[int, Arg(0)] becomes:
 pa.field("count", pa.int64())
 
-# Arg[str](1) becomes:
+# name: Annotated[str, Arg(1)] becomes:
 pa.field("name", pa.utf8())
 ```
 
@@ -49,35 +49,35 @@ Named arguments have `vgi_arg=named` metadata. The field name is the
 argument key used in SQL.
 
 ```python
-# Arg[str]("format") becomes:
+# format: Annotated[str, Arg("format")] becomes:
 pa.field("format", pa.utf8(), metadata={b"vgi_arg": b"named"})
 ```
 
 ## Special Types
 
 ### Table Input
 
-Table input arguments (`Arg[TableInput]`) receive streaming RecordBatches
-rather than scalar values.
+Table input arguments (`Annotated[TableInput, Arg(...)]`) receive streaming
+RecordBatches rather than scalar values.
 
 - **Arrow type**: `pa.null()`
 - **Metadata**: `{b"vgi_type": b"table"}`
 
 ```python
-# Arg[TableInput](1) becomes:
+# data: Annotated[TableInput, Arg(1)] becomes:
 pa.field("data", pa.null(), metadata={b"vgi_type": b"table"})
 ```
 
 ### Any Type
 
-Any-type arguments (`Arg[AnyArrow]`) accept any valid Arrow scalar type
-at runtime.
+Any-type arguments (`Annotated[AnyArrowValue, Arg(...)]`) accept any valid
+Arrow scalar type at runtime.
 
 - **Arrow type**: `pa.null()`
 - **Metadata**: `{b"vgi_type": b"any"}`
 
 ```python
-# Arg[AnyArrow](0) becomes:
+# value: Annotated[AnyArrowValue, Arg(0)] becomes:
 pa.field("value", pa.null(), metadata={b"vgi_type": b"any"})
 ```
 
@@ -90,7 +90,7 @@ arguments from their position onwards.
 - **Metadata**: `{b"vgi_varargs": b"true"}`
 
 ```python
-# Arg[str](0, varargs=True) becomes:
+# columns: Annotated[tuple[str, ...], Arg(0, varargs=True)] becomes:
 pa.field("columns", pa.utf8(), metadata={b"vgi_varargs": b"true"})
 ```
 
@@ -100,7 +100,7 @@ Fields can have multiple metadata keys. For example, a named argument
 that accepts any type:
 
 ```python
-# Arg[AnyArrow]("threshold") becomes:
+# threshold: Annotated[AnyArrowValue, Arg("threshold")] becomes:
 pa.field("threshold", pa.null(), metadata={
     b"vgi_arg": b"named",
     b"vgi_type": b"any",
@@ -112,10 +112,12 @@ pa.field("threshold", pa.null(), metadata={
 ### Example 1: Simple Function
 
 ```python
+from typing import Annotated
+
 class MyFunction(TableInOutFunction):
-    count = Arg[int](0)           # Positional 0
-    name = Arg[str](1)            # Positional 1
-    verbose = Arg[bool]("verbose") # Named
+    count: Annotated[int, Arg(0)]           # Positional 0
+    name: Annotated[str, Arg(1)]            # Positional 1
+    verbose: Annotated[bool, Arg("verbose")] # Named
 
 # Serializes to:
 schema = pa.schema([
@@ -128,9 +130,12 @@ schema = pa.schema([
 ### Example 2: Function with Table Input
 
 ```python
+from typing import Annotated
+from vgi.arguments import TableInput
+
 class TransformFunction(TableInOutFunction):
-    multiplier = Arg[float](0)
-    data: TableInput = Arg[TableInput](1)
+    multiplier: Annotated[float, Arg(0)]
+    data: Annotated[TableInput, Arg(1)]
 
 # Serializes to:
 schema = pa.schema([
@@ -142,8 +147,10 @@ schema = pa.schema([
 ### Example 3: Function with Varargs
 
 ```python
+from typing import Annotated
+
 class SumColumnsFunction(TableInOutFunction):
-    columns = Arg[str](0, varargs=True)
+    columns: Annotated[tuple[str, ...], Arg(0, varargs=True)]
 
 # Serializes to:
 schema = pa.schema([
@@ -154,12 +161,16 @@ schema = pa.schema([
 ### Example 4: Complex Function
 
 ```python
+from typing import Annotated
+from vgi import AnyArrowValue
+from vgi.arguments import TableInput
+
 class ComplexFunction(TableInOutFunction):
-    count = Arg[int](0)
-    data: TableInput = Arg[TableInput](1)
-    extra = Arg[float](2, varargs=True)
-    format = Arg[str]("format")
-    threshold: AnyArrow = Arg[AnyArrow]("threshold")
+    count: Annotated[int, Arg(0)]
+    data: Annotated[TableInput, Arg(1)]
+    extra: Annotated[tuple[float, ...], Arg(2, varargs=True)]
+    format: Annotated[str, Arg("format")]
+    threshold: Annotated[AnyArrowValue, Arg("threshold")]
 
 # Serializes to:
 schema = pa.schema([

docs/catalog-interface.md

@@ -131,6 +131,7 @@ Returned by `catalog_attach()` with attachment metadata:
 | `catalog_version_frozen` | `bool` | Whether metadata will change |
 | `catalog_version` | `int` | Current version (increments on changes) |
 | `attach_id_required` | `bool` | Whether attach_id must be persisted |
+| `default_schema` | `str` | Name of the default schema (usually "main") |
 
 ### SchemaInfo
 
@@ -140,7 +141,6 @@ Information about a schema in a catalog:
 |-------|------|-------------|
 | `attach_id` | `AttachId` | Parent attachment |
 | `name` | `str` | Schema name |
-| `is_default` | `bool` | Whether this is the default schema |
 | `comment` | `str \| None` | Optional description |
 | `tags` | `dict[str, str]` | Key-value metadata |
 
@@ -307,7 +307,7 @@ class MyReadOnlyCatalog(ReadOnlyCatalogInterface):
 
     def schema_get(self, *, attach_id, transaction_id, name) -> SchemaInfo | None:
         if name == "main":
-            return SchemaInfo(attach_id=attach_id, name="main", is_default=True, comment=None, tags={})
+            return SchemaInfo(attach_id=attach_id, name="main", comment=None, tags={})
         return None
 
     # table_get, view_get return None by default
@@ -643,7 +643,6 @@ class SimpleCatalog(CatalogInterface):
             return SchemaInfo(
                 attach_id=attach_id,
                 name="main",
-                is_default=True,
                 comment="Default schema",
                 tags={},
             )

docs/generator-api.md

@@ -11,6 +11,7 @@ including yielding log messages during processing. For most use cases, prefer th
 ### Basic Template
 
 ```python
+from typing import Annotated
 import pyarrow as pa
 import pyarrow.compute as pc
 from vgi import ScalarFunctionGenerator, Output, Arg
@@ -19,7 +20,7 @@ from vgi.log import Level, Message
 class MyScalarFunction(ScalarFunctionGenerator):
     """Transform each row to a single output value."""
 
-    col_name = Arg[str](0, doc="Name of the column to transform")
+    col_name: Annotated[str, Arg(0, doc="Name of the column to transform")]
 
     @property
     def output_schema(self) -> pa.Schema:
@@ -77,6 +78,7 @@ Use `TableFunctionGenerator` when you need to generate data without receiving in
 ### Basic Template
 
 ```python
+from typing import Annotated
 import pyarrow as pa
 from vgi import TableFunctionGenerator, Output, Arg
 from vgi.table_function import TableCardinality
@@ -88,7 +90,7 @@ class MyTableFunction(TableFunctionGenerator):
         name = "my_table_function"
         max_workers = 1  # Or None for parallel
 
-    count = Arg[int](0, doc="Number of rows to generate")
+    count: Annotated[int, Arg(0, doc="Number of rows to generate")]
     BATCH_SIZE = 1000
 
     @property

docs/metadata.md

@@ -7,6 +7,7 @@ Functions can define a nested `Meta` class to provide introspection metadata. No
 Metadata works with all function types: `ScalarFunction`, `TableFunctionGenerator`, and `TableInOutFunction`.
 
 ```python
+from typing import Annotated
 from vgi import TableInOutFunction, Arg
 
 class SumColumnsFunction(TableInOutFunction):
@@ -18,13 +19,14 @@ class SumColumnsFunction(TableInOutFunction):
         categories = ["aggregation", "numeric"]
         max_workers = 1  # Single-threaded (used by max_processes property)
 
-    column_name = Arg[str]("column", default=None, doc="Column to sum (optional)")
+    column_name: Annotated[str | None, Arg("column", default=None, doc="Column to sum")]
 
     def transform(self, batch):
         ...
 ```
 
 ```python
+from typing import Annotated
 from vgi import ScalarFunction, Arg
 from vgi.arguments import AnyArrow
 import pyarrow as pa
@@ -38,7 +40,7 @@ class DoubleValues(ScalarFunction):
         output_type = AnyArrow  # Dynamic type - depends on input
         categories = ["numeric", "transform"]
 
-    col_name = Arg[str](0, doc="Name of the column to double")
+    col_name: Annotated[str, Arg(0, doc="Name of the column to double")]
 
     @property
     def output_type(self) -> pa.DataType:

tests/catalog/test_catalog_interface.py

@@ -88,7 +88,6 @@ def schema_get(
             return SchemaInfo(
                 attach_id=attach_id,
                 name="main",
-                is_default=True,
                 comment=None,
                 tags={},
             )
@@ -142,7 +141,6 @@ def test_schemas_returns_main(self) -> None:
 
         assert len(schemas) == 1
         assert schemas[0].name == "main"
-        assert schemas[0].is_default is True
         assert schemas[0].comment is None
         assert schemas[0].tags == {}
 

tests/catalog/test_integration.py

@@ -53,7 +53,6 @@ def test_default_main_schema_exists(self) -> None:
 
         assert len(schemas) == 1
         assert schemas[0].name == "main"
-        assert schemas[0].is_default is True
 
     def test_schema_get_main(self) -> None:
         """Can get the main schema."""