pixeltable 0.2.22__py3-none-any.whl → 0.2.24__py3-none-any.whl

pixeltable/__init__.py

@@ -3,8 +3,8 @@ from .dataframe import DataFrame
 from .exceptions import Error
 from .exprs import RELATIVE_PATH_ROOT
 from .func import Aggregator, Function, expr_udf, uda, udf
-from .globals import (array, configure_logging, create_dir, create_table, create_view, drop_dir, drop_table, get_table,
-                      init, list_dirs, list_functions, list_tables, move)
+from .globals import (array, configure_logging, create_dir, create_snapshot, create_table, create_view, drop_dir,
+                      drop_table, get_table, init, list_dirs, list_functions, list_tables, move)
 from .type_system import (Array, ArrayType, Audio, AudioType, Bool, BoolType, ColumnType, Document, DocumentType, Float,
                           FloatType, Image, ImageType, Int, IntType, Json, JsonType, Required, String, StringType,
                           Timestamp, TimestampType, Video, VideoType)

pixeltable/__version__.py

@@ -1,3 +1,3 @@
 # These version placeholders will be replaced during build.
-__version__ = "0.2.22"
-__version_tuple__ = (0, 2, 22)
+__version__ = "0.2.24"
+__version_tuple__ = (0, 2, 24)

pixeltable/catalog/column.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional
 
 import sqlalchemy as sql
 
@@ -35,7 +35,6 @@ class Column:
     sa_col_type: Optional[sql.sqltypes.TypeEngine]
     sa_errormsg_col: Optional[sql.schema.Column]
     sa_errortype_col: Optional[sql.schema.Column]
-    compute_func: Optional[Callable]
     _value_expr: Optional[exprs.Expr]
     value_expr_dict: Optional[dict[str, Any]]
     dependent_cols: set[Column]
@@ -43,7 +42,7 @@ class Column:
 
     def __init__(
             self, name: Optional[str], col_type: Optional[ts.ColumnType] = None,
-            computed_with: Optional[Union[exprs.Expr, Callable]] = None,
+            computed_with: Optional[exprs.Expr] = None,
             is_pk: bool = False, stored: bool = True, media_validation: Optional[MediaValidation] = None,
             col_id: Optional[int] = None, schema_version_add: Optional[int] = None,
             schema_version_drop: Optional[int] = None, sa_col_type: Optional[sql.sqltypes.TypeEngine] = None,
@@ -54,7 +53,7 @@ class Column:
         Args:
             name: column name; None for system columns (eg, index columns)
             col_type: column type; can be None if the type can be derived from ``computed_with``
-            computed_with: a callable or an Expr object that computes the column value
+            computed_with: an Expr that computes the column value
             is_pk: if True, this column is part of the primary key
             stored: determines whether a computed column is present in the stored table or recomputed on demand
             col_id: column ID (only used internally)
@@ -64,11 +63,6 @@ class Column:
           col_type is None
         - when loaded from md store: ``computed_with`` is set and col_type is set
 
-        ``computed_with`` is a Callable:
-        - the callable's parameter names must correspond to existing columns in the table for which this Column
-          is being used
-        - ``col_type`` needs to be set to the callable's return type
-
         ``stored`` (only valid for computed image columns):
         - if True: the column is present in the stored table
         - if False: the column is not present in the stored table and recomputed during a query
@@ -80,22 +74,14 @@ class Column:
         if col_type is None and computed_with is None:
             raise excs.Error(f'Column `{name}`: col_type is required if computed_with is not specified')
 
-        self._value_expr = None
-        self.compute_func = None
+        self._value_expr: Optional[exprs.Expr] = None
         self.value_expr_dict = value_expr_dict
         if computed_with is not None:
             value_expr = exprs.Expr.from_object(computed_with)
             if value_expr is None:
-                # computed_with needs to be a Callable
-                if not callable(computed_with):
-                    raise excs.Error(
-                        f'Column {name}: computed_with needs to be either a Pixeltable expression or a Callable, '
-                        f'but it is a {type(computed_with)}')
-                if col_type is None:
-                    raise excs.Error(f'Column {name}: col_type is required if computed_with is a Callable')
-                # we need to turn the computed_with function into an Expr, but this requires resolving
-                # column name references and for that we need to wait until we're assigned to a Table
-                self.compute_func = computed_with
+                raise excs.Error(
+                    f'Column {name}: computed_with needs to be a valid Pixeltable expression, '
+                    f'but it is a {type(computed_with)}')
             else:
                 self._value_expr = value_expr.copy()
                 self.col_type = self._value_expr.col_type
@@ -158,7 +144,7 @@ class Column:
 
     @property
     def is_computed(self) -> bool:
-        return self.compute_func is not None or self._value_expr is not None or self.value_expr_dict is not None
+        return self._value_expr is not None or self.value_expr_dict is not None
 
     @property
     def is_stored(self) -> bool:

pixeltable/catalog/insertable_table.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Dict, Iterable, List, Optional, overload
+from typing import Any, Iterable, Literal, Optional, overload
 from uuid import UUID
 
 import sqlalchemy.orm as orm
@@ -13,7 +13,7 @@ from pixeltable.env import Env
 from pixeltable.utils.filecache import FileCache
 
 from .catalog import Catalog
-from .globals import UpdateStatus, MediaValidation
+from .globals import MediaValidation, UpdateStatus
 from .table import Table
 from .table_version import TableVersion
 from .table_version_path import TableVersionPath
@@ -36,7 +36,7 @@ class InsertableTable(Table):
     @classmethod
     def _create(
         cls, dir_id: UUID, name: str, schema: dict[str, ts.ColumnType], df: Optional[pxt.DataFrame],
-        primary_key: List[str], num_retained_versions: int, comment: str, media_validation: MediaValidation
+        primary_key: list[str], num_retained_versions: int, comment: str, media_validation: MediaValidation
     ) -> InsertableTable:
         columns = cls._create_columns(schema)
         cls._verify_schema(columns)
@@ -79,15 +79,31 @@ class InsertableTable(Table):
 
     @overload
     def insert(
-            self, rows: Iterable[Dict[str, Any]], /, *, print_stats: bool = False, fail_on_exception: bool = True
+        self,
+        rows: Iterable[dict[str, Any]],
+        /,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort'
     ) -> UpdateStatus: ...
 
     @overload
-    def insert(self, *, print_stats: bool = False, fail_on_exception: bool = True, **kwargs: Any) -> UpdateStatus: ...
+    def insert(
+        self,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: Any
+    ) -> UpdateStatus: ...
 
     def insert(  # type: ignore[misc]
-            self, rows: Optional[Iterable[dict[str, Any]]] = None, /, *, print_stats: bool = False,
-            fail_on_exception: bool = True, **kwargs: Any
+        self,
+        rows: Optional[Iterable[dict[str, Any]]] = None,
+        /,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: Any
     ) -> UpdateStatus:
         if rows is None:
             rows = [kwargs]
@@ -96,6 +112,8 @@ class InsertableTable(Table):
             if len(kwargs) > 0:
                 raise excs.Error('`kwargs` cannot be specified unless `rows is None`.')
 
+        fail_on_exception = on_error == 'abort'
+
         if not isinstance(rows, list):
             raise excs.Error('rows must be a list of dictionaries')
         if len(rows) == 0:
@@ -121,7 +139,7 @@ class InsertableTable(Table):
         FileCache.get().emit_eviction_warnings()
         return status
 
-    def _validate_input_rows(self, rows: List[Dict[str, Any]]) -> None:
+    def _validate_input_rows(self, rows: list[dict[str, Any]]) -> None:
         """Verify that the input rows match the table schema"""
         valid_col_names = set(self._schema.keys())
         reqd_col_names = set(self._tbl_version_path.tbl_version.get_required_col_names())

pixeltable/catalog/table.py

@@ -6,7 +6,7 @@ import json
 import logging
 from pathlib import Path
 from typing import _GenericAlias  # type: ignore[attr-defined]
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Literal, Optional, Set, Sequence, Tuple, Type, Union, overload
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Literal, Optional, Sequence, Union, overload
 from uuid import UUID
 
 import pandas as pd
@@ -125,7 +125,7 @@ class Table(SchemaObject):
     def __getattr__(self, name: str) -> 'pxt.exprs.ColumnRef':
         """Return a ColumnRef for the given name.
         """
-        return getattr(self._tbl_version_path, name)
+        return self._tbl_version_path.get_column_ref(name)
 
     @overload
     def __getitem__(self, name: str) -> 'pxt.exprs.ColumnRef': ...
@@ -217,6 +217,12 @@ class Table(SchemaObject):
         """Return the number of rows in this table."""
         return self._df().count()
 
+    @property
+    def columns(self) -> list[str]:
+        """Return the names of the columns in this table. """
+        cols = self._tbl_version_path.columns()
+        return [c.name for c in cols]
+
     @property
     def _schema(self) -> dict[str, ts.ColumnType]:
         """Return the schema (column names and column types) of this table."""
@@ -250,7 +256,7 @@ class Table(SchemaObject):
     def _media_validation(self) -> MediaValidation:
         return self._tbl_version.media_validation
 
-    def _description(self) -> pd.DataFrame:
+    def _description(self, cols: Optional[Iterable[Column]] = None) -> pd.DataFrame:
         cols = self._tbl_version_path.columns()
         df = pd.DataFrame({
             'Column Name': [c.name for c in cols],
@@ -259,8 +265,8 @@ class Table(SchemaObject):
         })
         return df
 
-    def _description_html(self) -> pandas.io.formats.style.Styler:
-        pd_df = self._description()
+    def _description_html(self, cols: Optional[Iterable[Column]] = None) -> pandas.io.formats.style.Styler:
+        pd_df = self._description(cols)
         # white-space: pre-wrap: print \n as newline
         # th: center-align headings
         return (
@@ -329,30 +335,74 @@ class Table(SchemaObject):
             raise excs.Error(f'Column name must be a string, got {type(col_name)}')
         if not isinstance(spec, (ts.ColumnType, exprs.Expr, type, _GenericAlias)):
             raise excs.Error(f'Column spec must be a ColumnType, Expr, or type, got {type(spec)}')
-        self.add_column(type=None, stored=None, print_stats=False, on_error='abort', **{col_name: spec})
+        self.add_column(stored=None, print_stats=False, on_error='abort', **{col_name: spec})
+
+    def add_columns(
+        self,
+        schema: dict[str, Union[ts.ColumnType, builtins.type, _GenericAlias]]
+    ) -> UpdateStatus:
+        """
+        Adds multiple columns to the table. The columns must be concrete (non-computed) columns; to add computed columns,
+        use [`add_computed_column()`][pixeltable.catalog.Table.add_computed_column] instead.
+
+        The format of the `schema` argument is identical to the format of the schema in a call to
+        [`create_table()`][pixeltable.globals.create_table].
+
+        Args:
+            schema: A dictionary mapping column names to types.
+
+        Returns:
+            Information about the execution status of the operation.
+
+        Raises:
+            Error: If any column name is invalid or already exists.
+
+        Examples:
+            Add multiple columns to the table `my_table`:
+
+            >>> tbl = pxt.get_table('my_table')
+            ... schema = {
+            ...     'new_col_1': pxt.Int,
+            ...     'new_col_2': pxt.String,
+            ... }
+            ... tbl.add_columns(schema)
+        """
+        self._check_is_dropped()
+        col_schema = {
+            col_name: {'type': ts.ColumnType.normalize_type(spec, nullable_default=True, allow_builtin_types=False)}
+            for col_name, spec in schema.items()
+        }
+        new_cols = self._create_columns(col_schema)
+        for new_col in new_cols:
+            self._verify_column(new_col, set(self._schema.keys()), set(self._query_names))
+        status = self._tbl_version.add_columns(new_cols, print_stats=False, on_error='abort')
+        FileCache.get().emit_eviction_warnings()
+        return status
 
+    # TODO: add_column() still supports computed columns for backward-compatibility. In the future, computed columns
+    #     will be supported only through add_computed_column(). At that point, we can remove the `stored`,
+    #     `print_stats`, and `on_error` parameters, and change the method body to simply call self.add_columns(kwargs),
+    #     simplifying the code. For the time being, there's some obvious code duplication.
     def add_column(
-            self,
-            *,
-            type: Union[ts.ColumnType, builtins.type, _GenericAlias, None] = None,
-            stored: Optional[bool] = None,
-            print_stats: bool = False,
-            on_error: Literal['abort', 'ignore'] = 'abort',
-            **kwargs: Union[ts.ColumnType, builtins.type, _GenericAlias, exprs.Expr, Callable]
+        self,
+        *,
+        stored: Optional[bool] = None,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: Union[ts.ColumnType, builtins.type, _GenericAlias, exprs.Expr]
     ) -> UpdateStatus:
         """
         Adds a column to the table.
 
         Args:
-            kwargs: Exactly one keyword argument of the form `column_name=type` or `column_name=expression`.
-            type: The type of the column. Only valid and required if `value-expression` is a Callable.
+            kwargs: Exactly one keyword argument of the form `col_name=col_type`.
             stored: Whether the column is materialized and stored or computed on demand. Only valid for image columns.
             print_stats: If `True`, print execution metrics during evaluation.
             on_error: Determines the behavior if an error occurs while evaluating the column expression for at least one
                 row.
 
-                - If `on_error='abort'`, then an exception will be raised and the column will not be added.
-                - If `on_error='ignore'`, then execution will continue and the column will be added. Any rows
+                - `'abort'`: an exception will be raised and the column will not be added.
+                - `'ignore'`: execution will continue and the column will be added. Any rows
                   with errors will have a `None` value for the column, with information about the error stored in the
                   corresponding `tbl.col_name.errortype` and `tbl.col_name.errormsg` fields.
 
@@ -370,53 +420,79 @@ class Table(SchemaObject):
             Alternatively, this can also be expressed as:
 
             >>> tbl['new_col'] = pxt.Int
+        """
+        self._check_is_dropped()
+        # verify kwargs and construct column schema dict
+        if len(kwargs) != 1:
+            raise excs.Error(
+                f'add_column() requires exactly one keyword argument of the form "col_name=col_type"; '
+                f'got {len(kwargs)} instead ({", ".join(list(kwargs.keys()))})'
+            )
+        col_name, spec = next(iter(kwargs.items()))
+        if not is_valid_identifier(col_name):
+            raise excs.Error(f'Invalid column name: {col_name!r}')
+
+        col_schema: dict[str, Any] = {}
+        if isinstance(spec, (ts.ColumnType, builtins.type, _GenericAlias)):
+            col_schema['type'] = ts.ColumnType.normalize_type(spec, nullable_default=True, allow_builtin_types=False)
+        else:
+            col_schema['value'] = spec
+        if stored is not None:
+            col_schema['stored'] = stored
+
+        new_col = self._create_columns({col_name: col_schema})[0]
+        self._verify_column(new_col, set(self._schema.keys()), set(self._query_names))
+        status = self._tbl_version.add_columns([new_col], print_stats=print_stats, on_error=on_error)
+        FileCache.get().emit_eviction_warnings()
+        return status
 
-            For a table with int column `int_col`, add a column that is the factorial of ``int_col``. The names of
-            the parameters of the Callable must correspond to existing column names (the column values are then passed
-            as arguments to the Callable). In this case, the column type needs to be specified explicitly:
+    def add_computed_column(
+        self,
+        *,
+        stored: Optional[bool] = None,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: exprs.Expr
+    ) -> UpdateStatus:
+        """
+        Adds a computed column to the table.
 
-            >>> tbl.add_column(factorial=lambda int_col: math.factorial(int_col), type=pxt.Int)
+        Args:
+            kwargs: Exactly one keyword argument of the form `col_name=expression`.
 
-            For a table with an image column ``frame``, add an image column ``rotated`` that rotates the image by
-            90 degrees. In this case, the column type is inferred from the expression. Also, the column is not stored
-            (by default, computed image columns are not stored but recomputed on demand):
+        Returns:
+            Information about the execution status of the operation.
 
-            >>> tbl.add_column(rotated=tbl.frame.rotate(90))
+        Raises:
+            Error: If the column name is invalid or already exists.
 
-            Alternatively, this can also be expressed as:
+        Examples:
+            For a table with an image column `frame`, add an image column `rotated` that rotates the image by
+            90 degrees:
 
-            >>> tbl['rotated'] = tbl.frame.rotate(90)
+            >>> tbl.add_computed_column(rotated=tbl.frame.rotate(90))
 
             Do the same, but now the column is unstored:
 
-            >>> tbl.add_column(rotated=tbl.frame.rotate(90), stored=False)
+            >>> tbl.add_computed_column(rotated=tbl.frame.rotate(90), stored=False)
         """
         self._check_is_dropped()
-        # verify kwargs and construct column schema dict
         if len(kwargs) != 1:
             raise excs.Error(
-                f'add_column() requires exactly one keyword argument of the form "column-name=type|value-expression"; '
-                f'got {len(kwargs)} instead ({", ".join(list(kwargs.keys()))})'
+                f'add_computed_column() requires exactly one keyword argument of the form "column-name=type|value-expression"; '
+                f'got {len(kwargs)} arguments instead ({", ".join(list(kwargs.keys()))})'
             )
         col_name, spec = next(iter(kwargs.items()))
         if not is_valid_identifier(col_name):
             raise excs.Error(f'Invalid column name: {col_name!r}')
-        if isinstance(spec, (ts.ColumnType, builtins.type, _GenericAlias, exprs.Expr)) and type is not None:
-            raise excs.Error(f'add_column(): keyword argument "type" is redundant')
 
-        col_schema: dict[str, Any] = {}
-        if isinstance(spec, (ts.ColumnType, builtins.type, _GenericAlias)):
-            col_schema['type'] = ts.ColumnType.normalize_type(spec, nullable_default=True)
-        else:
-            col_schema['value'] = spec
-        if type is not None:
-            col_schema['type'] = ts.ColumnType.normalize_type(type, nullable_default=True)
+        col_schema: dict[str, Any] = {'value': spec}
         if stored is not None:
             col_schema['stored'] = stored
 
         new_col = self._create_columns({col_name: col_schema})[0]
         self._verify_column(new_col, set(self._schema.keys()), set(self._query_names))
-        status = self._tbl_version.add_column(new_col, print_stats=print_stats, on_error=on_error)
+        status = self._tbl_version.add_columns([new_col], print_stats=print_stats, on_error=on_error)
         FileCache.get().emit_eviction_warnings()
         return status
 
@@ -429,39 +505,29 @@ class Table(SchemaObject):
         """
         assert isinstance(spec, dict)
         valid_keys = {'type', 'value', 'stored', 'media_validation'}
-        has_type = False
         for k in spec.keys():
             if k not in valid_keys:
                 raise excs.Error(f'Column {name}: invalid key {k!r}')
 
+        if 'type' not in spec and 'value' not in spec:
+            raise excs.Error(f"Column {name}: 'type' or 'value' must be specified")
+
         if 'type' in spec:
-            has_type = True
             if not isinstance(spec['type'], (ts.ColumnType, type, _GenericAlias)):
                 raise excs.Error(f'Column {name}: "type" must be a type or ColumnType, got {spec["type"]}')
 
         if 'value' in spec:
-            value_spec = spec['value']
-            value_expr = exprs.Expr.from_object(value_spec)
+            value_expr = exprs.Expr.from_object(spec['value'])
             if value_expr is None:
-                # needs to be a Callable
-                if not callable(value_spec):
-                    raise excs.Error(
-                        f'Column {name}: value needs to be either a Pixeltable expression or a Callable, '
-                        f'but it is a {type(value_spec)}')
-                if 'type' not in spec:
-                    raise excs.Error(f'Column {name}: "type" is required if value is a Callable')
-            else:
-                has_type = True
-                if 'type' in spec:
-                    raise excs.Error(f'Column {name}: "type" is redundant if value is a Pixeltable expression')
+                raise excs.Error(f'Column {name}: value must be a Pixeltable expression.')
+            if 'type' in spec:
+                raise excs.Error(f"Column {name}: 'type' is redundant if 'value' is specified")
 
         if 'media_validation' in spec:
             _ = catalog.MediaValidation.validated(spec['media_validation'], f'Column {name}: media_validation')
 
         if 'stored' in spec and not isinstance(spec['stored'], bool):
             raise excs.Error(f'Column {name}: "stored" must be a bool, got {spec["stored"]}')
-        if not has_type:
-            raise excs.Error(f'Column {name}: "type" is required')
 
     @classmethod
     def _create_columns(cls, schema: dict[str, Any]) -> list[Column]:
@@ -475,19 +541,15 @@ class Table(SchemaObject):
             stored = True
 
             if isinstance(spec, (ts.ColumnType, type, _GenericAlias)):
-                col_type = ts.ColumnType.normalize_type(spec, nullable_default=True)
+                col_type = ts.ColumnType.normalize_type(spec, nullable_default=True, allow_builtin_types=False)
             elif isinstance(spec, exprs.Expr):
                 # create copy so we can modify it
                 value_expr = spec.copy()
-            elif callable(spec):
-                raise excs.Error(
-                    f'Column {name} computed with a Callable: specify using a dictionary with '
-                    f'the "value" and "type" keys (e.g., "{name}": {{"value": <Callable>, "type": pxt.Int}})'
-                )
             elif isinstance(spec, dict):
                 cls._validate_column_spec(name, spec)
                 if 'type' in spec:
-                    col_type = ts.ColumnType.normalize_type(spec['type'], nullable_default=True)
+                    col_type = ts.ColumnType.normalize_type(
+                        spec['type'], nullable_default=True, allow_builtin_types=False)
                 value_expr = spec.get('value')
                 if value_expr is not None and isinstance(value_expr, exprs.Expr):
                     # create copy so we can modify it
@@ -499,6 +561,8 @@ class Table(SchemaObject):
                     catalog.MediaValidation[media_validation_str.upper()] if media_validation_str is not None
                     else None
                 )
+            else:
+                raise excs.Error(f'Invalid value for column {name!r}')
 
             column = Column(
                 name, col_type=col_type, computed_with=value_expr, stored=stored, is_pk=primary_key,
@@ -508,7 +572,7 @@ class Table(SchemaObject):
 
     @classmethod
     def _verify_column(
-            cls, col: Column, existing_column_names: Set[str], existing_query_names: Optional[Set[str]] = None
+            cls, col: Column, existing_column_names: set[str], existing_query_names: Optional[set[str]] = None
     ) -> None:
         """Check integrity of user-supplied Column and supply defaults"""
         if is_system_column_name(col.name):
@@ -529,7 +593,7 @@ class Table(SchemaObject):
     @classmethod
     def _verify_schema(cls, schema: list[Column]) -> None:
         """Check integrity of user-supplied schema and set defaults"""
-        column_names: Set[str] = set()
+        column_names: set[str] = set()
         for col in schema:
             cls._verify_column(col, column_names)
             column_names.add(col.name)
@@ -710,7 +774,7 @@ class Table(SchemaObject):
 
     def _drop_index(
             self, *, column_name: Optional[str] = None, idx_name: Optional[str] = None,
-            _idx_class: Optional[Type[index.IndexBase]] = None
+            _idx_class: Optional[type[index.IndexBase]] = None
     ) -> None:
         if self._tbl_version_path.is_snapshot():
             raise excs.Error('Cannot drop an index from a snapshot')
@@ -741,36 +805,68 @@ class Table(SchemaObject):
 
     @overload
     def insert(
-            self, rows: Iterable[dict[str, Any]], /, *, print_stats: bool = False, fail_on_exception: bool = True
+        self,
+        rows: Iterable[dict[str, Any]],
+        /,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort'
     ) -> UpdateStatus: ...
 
     @overload
-    def insert(self, *, print_stats: bool = False, fail_on_exception: bool = True, **kwargs: Any) -> UpdateStatus: ...
+    def insert(
+        self,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: Any
+    ) -> UpdateStatus: ...
 
     @abc.abstractmethod  # type: ignore[misc]
     def insert(
-            self, rows: Optional[Iterable[dict[str, Any]]] = None, /, *, print_stats: bool = False,
-            fail_on_exception: bool = True, **kwargs: Any
+        self,
+        rows: Optional[Iterable[dict[str, Any]]] = None,
+        /,
+        *,
+        print_stats: bool = False,
+        on_error: Literal['abort', 'ignore'] = 'abort',
+        **kwargs: Any
     ) -> UpdateStatus:
         """Inserts rows into this table. There are two mutually exclusive call patterns:
 
         To insert multiple rows at a time:
-        ``insert(rows: Iterable[dict[str, Any]], /, *, print_stats: bool = False, fail_on_exception: bool = True)``
+
+        ```python
+        insert(
+            rows: Iterable[dict[str, Any]],
+            /,
+            *,
+            print_stats: bool = False,
+            on_error: Literal['abort', 'ignore'] = 'abort'
+        )```
 
         To insert just a single row, you can use the more concise syntax:
-        ``insert(*, print_stats: bool = False, fail_on_exception: bool = True, **kwargs: Any)``
+
+        ```python
+        insert(
+            *,
+            print_stats: bool = False,
+            on_error: Literal['abort', 'ignore'] = 'abort',
+            **kwargs: Any
+        )```
 
         Args:
             rows: (if inserting multiple rows) A list of rows to insert, each of which is a dictionary mapping column
                 names to values.
             kwargs: (if inserting a single row) Keyword-argument pairs representing column names and values.
-            print_stats: If ``True``, print statistics about the cost of computed columns.
-            fail_on_exception:
-                Determines how exceptions in computed columns and invalid media files (e.g., corrupt images)
-                are handled.
-                If ``False``, store error information (accessible as column properties 'errortype' and 'errormsg')
-                for those cases, but continue inserting rows.
-                If ``True``, raise an exception that aborts the insert.
+            print_stats: If `True`, print statistics about the cost of computed columns.
+            on_error: Determines the behavior if an error occurs while evaluating a computed column or detecting an
+                invalid media file (such as a corrupt image) for one of the inserted rows.
+
+                - If `on_error='abort'`, then an exception will be raised and the rows will not be inserted.
+                - If `on_error='ignore'`, then execution will continue and the rows will be inserted. Any cells
+                  with errors will have a `None` value for that cell, with information about the error stored in the
+                  corresponding `tbl.col_name.errortype` and `tbl.col_name.errormsg` fields.
 
         Returns:
             An [`UpdateStatus`][pixeltable.UpdateStatus] object containing information about the update.
@@ -781,7 +877,7 @@ class Table(SchemaObject):
                 - The table is a view or snapshot.
                 - The table has been dropped.
                 - One of the rows being inserted does not conform to the table schema.
-                - An error occurs during processing of computed columns, and `fail_on_exception=True`.
+                - An error occurs during processing of computed columns, and `on_error='ignore'`.
 
         Examples:
             Insert two rows into the table `my_table` with three int columns ``a``, ``b``, and ``c``.
@@ -867,7 +963,7 @@ class Table(SchemaObject):
 
         # pseudo-column _rowid: contains the rowid of the row to update and can be used instead of the primary key
         has_rowid = _ROWID_COLUMN_NAME in rows[0]
-        rowids: list[Tuple[int, ...]] = []
+        rowids: list[tuple[int, ...]] = []
         if len(pk_col_names) == 0 and not has_rowid:
             raise excs.Error('Table must have primary key for batch update')