vgi-python 0.43.1__py3-none-any.whl → 0.44.0__py3-none-any.whl

vgi/_test_fixtures/aggregate/dynamic.py

@@ -232,7 +232,9 @@ class _DynamicAggregateBase(AggregateFunction[DynamicState]):
                     t = t.filter(null_mask)
             slices.append(t)
         if not slices:
-            return pa.table({c: pa.array([], type=cols[i].type) for i, c in enumerate(col_names)})
+            # pa.nulls(0, ...), not pa.array([], ...): the latter has no
+            # builder for union or extension types.
+            return pa.table({c: pa.nulls(0, type=cols[i].type) for i, c in enumerate(col_names)})
         return pa.concat_tables(slices)
 
     @staticmethod

vgi/_test_fixtures/scalar/_common.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 import pyarrow as pa
 
-from vgi.exceptions import SchemaValidationError
+from vgi.exceptions import ArgumentTypeError
 
 
 def _is_addable_type(dtype: pa.DataType) -> bool:
@@ -66,4 +66,4 @@ def _promote_for_addition(dtype: pa.DataType) -> pa.DataType:
         # accepts that values >= 5e37 will overflow at compute time.
         new_precision = min(dtype.precision + 1, 38)
         return pa.decimal128(new_precision, dtype.scale)
-    raise SchemaValidationError(f"Unsupported numeric type for addition: {dtype}")
+    raise ArgumentTypeError(f"Unsupported numeric type for addition: {dtype}")

vgi/arguments.py

@@ -19,10 +19,11 @@ import typing
 import warnings
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Final, TypeVar, overload
+from typing import TYPE_CHECKING, Any, ClassVar, Final, TypeVar, overload
 
 import pyarrow as pa
 from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.errors import Code
 
 if TYPE_CHECKING:
     from pyarrow import Scalar
@@ -638,6 +639,7 @@ class ArgumentValidationError(ValueError):
         valid_range: Human-readable description of valid values.
         default: Default value (if any) that could be used instead.
         choices: Valid choices, if the argument is constrained to a set.
+        error_code: ``INVALID_ARGUMENT`` -- the caller's input is wrong, not the worker.
 
     """
 
@@ -649,6 +651,7 @@ class ArgumentValidationError(ValueError):
     valid_range: str | None
     default: Any
     choices: Sequence[Any] | None
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
 
     def __init__(
         self,
@@ -1429,10 +1432,12 @@ class Arg[ArgT]:
             field_type: The Arrow type of the column to validate.
 
         Raises:
-            [`SchemaValidationError`][]: If the type bound is not satisfied.
+            [`ArgumentTypeError`][vgi.exceptions.ArgumentTypeError]: If the type bound is
+                not satisfied (a [`SchemaValidationError`][vgi.exceptions.SchemaValidationError]
+                coded ``INVALID_ARGUMENT``).
 
         """
-        from vgi.exceptions import SchemaValidationError
+        from vgi.exceptions import ArgumentTypeError
 
         if self.type_bound is None:
             return
@@ -1446,7 +1451,7 @@ class Arg[ArgT]:
         # OR logic: at least one predicate must pass
         if not any(predicate(field_type) for predicate in predicates):
             predicate_names = [getattr(p, "__name__", str(p)) for p in predicates]
-            raise SchemaValidationError(
+            raise ArgumentTypeError(
                 self.format_error(f"column type {field_type} does not match any of: {', '.join(predicate_names)}")
             )
 

vgi/catalog/attach_option.py

@@ -23,6 +23,7 @@ from dataclasses import dataclass
 from typing import Any, ClassVar
 
 import pyarrow as pa
+from vgi_rpc.errors import Code
 
 from vgi.catalog._descriptor_spec import _DescriptorBase, _extract_specs, _SpecBase
 
@@ -156,10 +157,12 @@ class MissingAttachOptionsError(ValueError):
 
     Attributes:
         missing: Names of the required options that were not supplied.
+        error_code: ``INVALID_ARGUMENT``.
 
     """
 
     missing: list[str]
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
 
     def __init__(self, catalog_name: str, missing: list[str]) -> None:
         """Build the error from the catalog name and the missing option names."""

vgi/catalog/catalog_interface.py

@@ -38,7 +38,7 @@ from vgi_rpc import ArrowSerializableDataclass, ArrowType
 from vgi_rpc.utils import deserialize_record_batch, serialize_record_batch_bytes
 
 from vgi.arguments import Arguments, SecretLookupEntry
-from vgi.exceptions import CatalogReadOnlyError
+from vgi.exceptions import CatalogReadOnlyError, InvalidArgumentError, NotFoundError, UnsupportedOperationError
 from vgi.metadata import (
     ArgumentMonotonicity,
     DistinctDependence,
@@ -100,7 +100,7 @@ __all__ = [
 def _validate_at_params(at_unit: str | None, at_value: str | None) -> None:
     """Validate that at_unit and at_value are both provided or both absent."""
     if bool(at_unit) != bool(at_value):
-        raise ValueError("at_unit and at_value must both be provided or both be None")
+        raise InvalidArgumentError("at_unit and at_value must both be provided or both be None")
 
 
 @dataclass(frozen=True)
@@ -1810,12 +1810,12 @@ class CatalogInterface(ABC):
         If on_conflict is ERROR and the catalog already exists, raise an error.
 
         """
-        raise NotImplementedError("Catalog create not implemented.")
+        raise UnsupportedOperationError("Catalog create not implemented.")
 
     # Drop a catalog
     def catalog_drop(self, *, name: str) -> None:
         """Drop the catalog with the given name."""
-        raise NotImplementedError("Catalog drop not implemented.")
+        raise UnsupportedOperationError("Catalog drop not implemented.")
 
     # Transactions are initiated and driven by DuckDB it is rare for CatalogInterface
     # implementors to implement them, but I want to support them.
@@ -1830,7 +1830,7 @@ class CatalogInterface(ABC):
 
         If the implementation does not support transactions, it can return None.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     def catalog_transaction_commit(
         self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: TransactionOpaqueData
@@ -1839,7 +1839,7 @@ class CatalogInterface(ABC):
 
         If the transaction cannot be committed, an exception should be raised.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     def catalog_transaction_rollback(
         self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: TransactionOpaqueData
@@ -1848,7 +1848,7 @@ class CatalogInterface(ABC):
 
         If the transaction cannot be rolled back, an exception should be raised.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     @abstractmethod
     def catalog_attach(
@@ -1936,7 +1936,7 @@ class CatalogInterface(ABC):
         tags: dict[str, str],
     ) -> None:
         """Create a new schema with the given path, comment, and tags."""
-        raise NotImplementedError("Schema create not implemented.")
+        raise UnsupportedOperationError("Schema create not implemented.")
 
     def schema_drop(
         self,
@@ -1948,7 +1948,7 @@ class CatalogInterface(ABC):
         cascade: bool,
     ) -> None:
         """Drop the schema with the given path."""
-        raise NotImplementedError("Schema drop not implemented.")
+        raise UnsupportedOperationError("Schema drop not implemented.")
 
     @overload
     def schema_contents(
@@ -2034,7 +2034,7 @@ class CatalogInterface(ABC):
             depending on the type parameter.
 
         """
-        raise NotImplementedError("Schema contents not implemented.")
+        raise UnsupportedOperationError("Schema contents not implemented.")
 
     def catalog_contents(
         self,
@@ -2159,7 +2159,7 @@ class CatalogInterface(ABC):
 
         Comments and tags are not supported on table creation.
         """
-        raise NotImplementedError("Table create not implemented.")
+        raise UnsupportedOperationError("Table create not implemented.")
 
     def table_drop(
         self,
@@ -2172,7 +2172,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the table with the given name."""
-        raise NotImplementedError("Table drop not implemented.")
+        raise UnsupportedOperationError("Table drop not implemented.")
 
     def table_comment_set(
         self,
@@ -2185,7 +2185,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for the table with the given name."""
-        raise NotImplementedError("Table comment set not implemented.")
+        raise UnsupportedOperationError("Table comment set not implemented.")
 
     def table_column_comment_set(
         self,
@@ -2199,7 +2199,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for a column in the table."""
-        raise NotImplementedError("Table column comment set not implemented.")
+        raise UnsupportedOperationError("Table column comment set not implemented.")
 
     def table_rename(
         self,
@@ -2212,7 +2212,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the table with the given name to the new name."""
-        raise NotImplementedError("Table rename not implemented.")
+        raise UnsupportedOperationError("Table rename not implemented.")
 
     def table_column_add(
         self,
@@ -2228,7 +2228,7 @@ class CatalogInterface(ABC):
         if_column_not_exists: bool,
     ) -> None:
         """Add a column to the table with the given name."""
-        raise NotImplementedError("Table column add not implemented.")
+        raise UnsupportedOperationError("Table column add not implemented.")
 
     def table_column_drop(
         self,
@@ -2243,7 +2243,7 @@ class CatalogInterface(ABC):
         cascade: bool,
     ) -> None:
         """Drop the column from the table with the given name."""
-        raise NotImplementedError("Table column drop not implemented.")
+        raise UnsupportedOperationError("Table column drop not implemented.")
 
     def table_column_rename(
         self,
@@ -2257,7 +2257,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the column in the table with the given name."""
-        raise NotImplementedError("Table column rename not implemented.")
+        raise UnsupportedOperationError("Table column rename not implemented.")
 
     def table_column_default_set(
         self,
@@ -2271,7 +2271,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the default expression for the column."""
-        raise NotImplementedError("Table column default set not implemented.")
+        raise UnsupportedOperationError("Table column default set not implemented.")
 
     def table_column_default_drop(
         self,
@@ -2284,7 +2284,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the default expression for the column."""
-        raise NotImplementedError("Table column default drop not implemented.")
+        raise UnsupportedOperationError("Table column default drop not implemented.")
 
     def table_column_type_change(
         self,
@@ -2303,7 +2303,7 @@ class CatalogInterface(ABC):
 
         The name of the column to change is taken from the field in the provided schema.
         """
-        raise NotImplementedError("Table column type change not implemented.")
+        raise UnsupportedOperationError("Table column type change not implemented.")
 
     def table_not_null_drop(
         self,
@@ -2316,7 +2316,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the NOT NULL constraint from the column."""
-        raise NotImplementedError("Table NOT NULL drop not implemented.")
+        raise UnsupportedOperationError("Table NOT NULL drop not implemented.")
 
     def table_not_null_set(
         self,
@@ -2329,7 +2329,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the NOT NULL constraint on the column."""
-        raise NotImplementedError("Table NOT NULL set not implemented.")
+        raise UnsupportedOperationError("Table NOT NULL set not implemented.")
 
     def table_scan_function_get(
         self,
@@ -2347,7 +2347,7 @@ class CatalogInterface(ABC):
         Returns information about the VGI table function to call when scanning
         this table. The at_unit and at_value support time travel queries.
         """
-        raise NotImplementedError("Table scan function get not implemented.")
+        raise UnsupportedOperationError("Table scan function get not implemented.")
 
     def table_scan_branches_get(
         self,
@@ -2466,7 +2466,7 @@ class CatalogInterface(ABC):
         For single-branch tables this is ``None`` (or unset for legacy
         overrides).
         """
-        raise NotImplementedError("Table insert not supported.")
+        raise UnsupportedOperationError("Table insert not supported.")
 
     def table_update_function_get(
         self,
@@ -2482,7 +2482,7 @@ class CatalogInterface(ABC):
         to call for updating rows in this table. Input batches will include a
         rowid column plus the columns being updated.
         """
-        raise NotImplementedError("Table update not supported.")
+        raise UnsupportedOperationError("Table update not supported.")
 
     def table_delete_function_get(
         self,
@@ -2498,7 +2498,7 @@ class CatalogInterface(ABC):
         to call for deleting rows from this table. Input batches will contain
         a rowid column identifying the rows to delete.
         """
-        raise NotImplementedError("Table delete not supported.")
+        raise UnsupportedOperationError("Table delete not supported.")
 
     def view_create(
         self,
@@ -2511,7 +2511,7 @@ class CatalogInterface(ABC):
         on_conflict: OnConflict,
     ) -> None:
         """Create a new view with the given definition."""
-        raise NotImplementedError("View create not implemented.")
+        raise UnsupportedOperationError("View create not implemented.")
 
     def view_drop(
         self,
@@ -2524,7 +2524,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the view with the given name."""
-        raise NotImplementedError("View drop not implemented.")
+        raise UnsupportedOperationError("View drop not implemented.")
 
     def view_rename(
         self,
@@ -2537,7 +2537,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the view to the new name."""
-        raise NotImplementedError("View rename not implemented.")
+        raise UnsupportedOperationError("View rename not implemented.")
 
     @abstractmethod
     def view_get(
@@ -2564,7 +2564,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for the view with the given name."""
-        raise NotImplementedError("View comment set not implemented.")
+        raise UnsupportedOperationError("View comment set not implemented.")
 
     # ---- Macros ----
 
@@ -2613,7 +2613,7 @@ class CatalogInterface(ABC):
                 descriptions via the ``vgi_doc`` field metadata key. ``None`` when
                 no per-parameter docs are supplied.
         """
-        raise NotImplementedError("Macro create not implemented.")
+        raise UnsupportedOperationError("Macro create not implemented.")
 
     def macro_drop(
         self,
@@ -2625,7 +2625,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the macro with the given name."""
-        raise NotImplementedError("Macro drop not implemented.")
+        raise UnsupportedOperationError("Macro drop not implemented.")
 
     # ---- Indexes ----
 
@@ -2659,7 +2659,7 @@ class CatalogInterface(ABC):
         options: dict[str, str] | None = None,
     ) -> None:
         """Create a new index on the specified table."""
-        raise NotImplementedError("Index create not implemented.")
+        raise UnsupportedOperationError("Index create not implemented.")
 
     def index_drop(
         self,
@@ -2672,7 +2672,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the index with the given name."""
-        raise NotImplementedError("Index drop not implemented.")
+        raise UnsupportedOperationError("Index drop not implemented.")
 
     def copy_from_formats(
         self,
@@ -3015,7 +3015,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
         del data_version_spec, implementation_version, ctx
         effective_name = self._effective_catalog_name
         if name != effective_name:
-            raise ValueError(f"Unknown catalog: {name!r}. Available: {effective_name}")
+            raise NotFoundError(f"Unknown catalog: {name!r}. Available: {effective_name}")
         validate_required_attach_options(effective_name, self.attach_option_specs, options)
 
         # Serialize settings and secret types for the attach result
@@ -3276,7 +3276,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
 
         table = self._table_registry.get((schema_path_key(schema_path), name.lower()))
         if table is None:
-            raise NotImplementedError(f"Table {schema_path_display(schema_path)}::{name!r} not found in catalog.")
+            raise NotFoundError(f"Table {schema_path_display(schema_path)}::{name!r} not found in catalog.")
 
         write_func = getattr(table, attr_name, None)
         if write_func is None:

vgi/client/aggregate.py

@@ -50,6 +50,7 @@ from typing import Any
 
 import pyarrow as pa
 from vgi_rpc.rpc import RpcError
+from vgi_rpc.utils import empty_batch
 
 from vgi.aggregate_function import GROUP_COLUMN_NAME
 from vgi.arguments import Arguments
@@ -783,12 +784,9 @@ class AggregateClientMixin:
                 batch = next(batches, None)
 
             if not group_keys:
-                results = [
-                    pa.RecordBatch.from_arrays(
-                        [pa.array([], type=field.type) for field in session.output_schema],
-                        schema=session.output_schema,
-                    )
-                ]
+                # empty_batch, not pa.array([], type=...): that has no builder
+                # for union or extension types.
+                results = [empty_batch(session.output_schema)]
             else:
                 results = [
                     session.finalize(range(start, min(start + finalize_chunk_size, len(group_keys))))

vgi/exceptions.py

@@ -14,15 +14,21 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, ClassVar
 
+from vgi_rpc.errors import Code
+
 if TYPE_CHECKING:
     import pyarrow as pa
 
 __all__ = [
+    "ArgumentTypeError",
     "BindStateNotFoundError",
     "CatalogReadOnlyError",
     "ExecutionIdentifierError",
+    "InvalidArgumentError",
+    "NotFoundError",
     "OpaqueDataNotRecognizedError",
     "SchemaValidationError",
+    "UnsupportedOperationError",
 ]
 
 
@@ -55,8 +61,14 @@ class CatalogReadOnlyError(Exception):
     - table_get(), view_get() - get table/view info
     - table_scan_function_get() - get scan function for tables
 
+    Also raised when a write targets a table that has no write function.
+    ``FAILED_PRECONDITION``: the request is well-formed, the catalog is just
+    not in a state that permits it.
+
     """
 
+    error_code: ClassVar[Code] = Code.FAILED_PRECONDITION
+
 
 class OpaqueDataNotRecognizedError(ValueError):
     """An opaque value (``attach_opaque_data`` / ``transaction_opaque_data``) failed to open.
@@ -72,7 +84,7 @@ class OpaqueDataNotRecognizedError(ValueError):
     working.
     """
 
-    error_code: ClassVar[str] = "INVALID_ARGUMENT"
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
     error_kind: ClassVar[str] = "opaque_data_not_recognized"
 
     def __init__(self, field: str) -> None:
@@ -230,3 +242,52 @@ class SchemaValidationError(Exception):
             lines.append(f"    {field.name}: {field.type}{nullable}")
 
         return "\n".join(lines)
+
+
+class ArgumentTypeError(SchemaValidationError):
+    """An argument or input column has a type the function does not accept.
+
+    Raised when a value fails an ``Arg[AnyArrow]`` ``type_bound`` -- e.g.
+    ``double('abc')`` against a numeric-only bound. Unlike its base class,
+    which reports a worker's *own* output violating its declared schema (a
+    bug, sent as ``UNKNOWN``), this is the caller's input being wrong, so it is
+    ``INVALID_ARGUMENT``. Subclasses [`SchemaValidationError`][] so existing
+    handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
+
+
+class InvalidArgumentError(ValueError):
+    """A request's arguments cannot be accepted (``INVALID_ARGUMENT``).
+
+    For argument problems that are not a single argument's constraint (those
+    raise [`ArgumentValidationError`][vgi.arguments.ArgumentValidationError]):
+    no overload matching the supplied argument types, an ambiguous call, or a
+    call shape the function does not take. Subclasses ``ValueError`` so
+    existing handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
+
+
+class NotFoundError(ValueError):
+    """A named function, table, schema, or catalog does not exist (``NOT_FOUND``).
+
+    Subclasses ``ValueError`` so existing handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.NOT_FOUND
+
+
+class UnsupportedOperationError(NotImplementedError):
+    """An operation the SDK or catalog explicitly does not support (``UNIMPLEMENTED``).
+
+    Raised by the [`CatalogInterface`][vgi.catalog.CatalogInterface] defaults
+    for DDL/DML a catalog has not implemented, and by framework paths that are
+    not supported yet. Subclasses ``NotImplementedError`` so existing handlers
+    -- including the ones that treat an unimplemented optional hook as
+    "absent" -- keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.UNIMPLEMENTED

vgi/filter_v2.py

@@ -16,6 +16,7 @@ from typing import Any
 from typing import Literal as TypingLiteral
 
 import pyarrow as pa
+from vgi_rpc.utils import empty_batch
 
 FILTER_ENCODING = "vgi.filters.v2"
 FILTER_VERSION = "2"
@@ -765,10 +766,9 @@ class _Parser:
             and not isinstance(expression, RuntimeFilter)
             and not _REPLAYING_ACCEPTED_STATE.get()
         ):
-            empty = pa.RecordBatch.from_arrays(
-                [pa.array([], type=field.type) for field in self.output_schema],
-                schema=self.output_schema,
-            )
+            # empty_batch, not pa.array([], type=...): that has no builder
+            # for union or extension types.
+            empty = empty_batch(self.output_schema)
             try:
                 _evaluate_expression(expression, empty, self.context)
             except Exception as exc:

vgi/function.py

@@ -147,6 +147,20 @@ class Function(ABC, MetadataMixin):
     # Cache for resolved metadata
     _metadata_cache: ClassVar[ResolvedMetadata | None] = None
 
+    @classmethod
+    def __subclasshook__(cls, subclass: type) -> bool:
+        """Answer ``issubclass`` from the MRO alone.
+
+        Without this, a *failed* ``issubclass(X, SomeFunctionBase)`` makes
+        ``ABCMeta`` call ``issubclass(X, S)`` for every subclass ``S`` of the
+        base, looking for a virtual subclass. A worker that generates one class
+        per function has thousands of them, and the framework asks this about
+        every class, so building a catalog went quadratic in its function count.
+        Function classes are real subclasses, never ``ABC.register``-ed ones,
+        so the MRO is the whole answer.
+        """
+        return cls in getattr(subclass, "__mro__", ())
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """Extract [`Arg`][] descriptors from Annotated type hints.