pixeltable 0.4.17__py3-none-any.whl → 0.4.19__py3-none-any.whl

pixeltable/exprs/column_ref.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-import copy
-from typing import Any, Optional, Sequence
+from typing import TYPE_CHECKING, Any, Sequence, cast
 from uuid import UUID
 
 import sqlalchemy as sql
 
-import pixeltable as pxt
-from pixeltable import catalog, exceptions as excs, iterators as iters
+import pixeltable.catalog as catalog
+import pixeltable.exceptions as excs
+import pixeltable.iterators as iters
 
 from ..utils.description_helper import DescriptionHelper
 from ..utils.filecache import FileCache
@@ -16,6 +16,9 @@ from .expr import Expr
 from .row_builder import RowBuilder
 from .sql_element_cache import SqlElementCache
 
+if TYPE_CHECKING:
+    from pixeltable.dataframe import DataFrame, DataFrameResultSet
+
 
 class ColumnRef(Expr):
     """A reference to a table column
@@ -44,36 +47,34 @@ class ColumnRef(Expr):
 
     col: catalog.Column  # TODO: merge with col_handle
     col_handle: catalog.ColumnHandle
-    reference_tbl: Optional[catalog.TableVersionPath]
+    reference_tbl: catalog.TableVersionPath | None
     is_unstored_iter_col: bool
-    iter_arg_ctx: Optional[RowBuilder.EvalCtx]
-    base_rowid_len: int
-    base_rowid: Sequence[Optional[Any]]
-    iterator: Optional[iters.ComponentIterator]
-    pos_idx: Optional[int]
-    id: int
     perform_validation: bool  # if True, performs media validation
+    iter_arg_ctx: RowBuilder.EvalCtx | None
+    base_rowid_len: int  # number of rowid columns in the base table
+
+    # execution state
+    base_rowid: Sequence[Any | None]
+    iterator: iters.ComponentIterator | None
+    pos_idx: int
 
     def __init__(
         self,
         col: catalog.Column,
-        reference_tbl: Optional[catalog.TableVersionPath] = None,
-        perform_validation: Optional[bool] = None,
+        reference_tbl: catalog.TableVersionPath | None = None,
+        perform_validation: bool | None = None,
     ):
         super().__init__(col.col_type)
-        assert col.tbl is not None
         self.col = col
         self.reference_tbl = reference_tbl
-        self.col_handle = catalog.ColumnHandle(col.tbl.handle, col.id)
+        self.col_handle = col.handle
 
-        self.is_unstored_iter_col = col.tbl.is_component_view and col.tbl.is_iterator_column(col) and not col.is_stored
+        self.is_unstored_iter_col = col.is_iterator_col and not col.is_stored
         self.iter_arg_ctx = None
-        # number of rowid columns in the base table
-        self.base_rowid_len = col.tbl.base.get().num_rowid_columns() if self.is_unstored_iter_col else 0
-        self.base_rowid = [None] * self.base_rowid_len
+        self.base_rowid_len = 0
+        self.base_rowid = []
         self.iterator = None
-        # index of the position column in the view's primary key; don't try to reference tbl.store_tbl here
-        self.pos_idx = col.tbl.num_rowid_columns() - 1 if self.is_unstored_iter_col else None
+        self.pos_idx = 0
 
         self.perform_validation = False
         if col.col_type.is_media_type():
@@ -99,14 +100,14 @@ class ColumnRef(Expr):
     def _id_attrs(self) -> list[tuple[str, Any]]:
         return [
             *super()._id_attrs(),
-            ('tbl_id', self.col.tbl.id),
+            ('tbl_id', self.col.tbl_handle.id),
             ('col_id', self.col.id),
             ('perform_validation', self.perform_validation),
         ]
 
     # override
     def _retarget(self, tbl_versions: dict[UUID, catalog.TableVersion]) -> ColumnRef:
-        target = tbl_versions[self.col.tbl.id]
+        target = tbl_versions[self.col.tbl_handle.id]
         assert self.col.id in target.cols_by_id
         col = target.cols_by_id[self.col.id]
         return ColumnRef(col, self.reference_tbl)
@@ -144,33 +145,6 @@ class ColumnRef(Expr):
 
         return super().__getattr__(name)
 
-    def find_embedding_index(
-        self, idx_name: Optional[str], method_name: str
-    ) -> dict[str, catalog.TableVersion.IndexInfo]:
-        """Return IndexInfo for a column, with an optional given name"""
-        from pixeltable import index
-
-        # determine index to use
-        idx_info_dict = self.col.get_idx_info(self.reference_tbl)
-
-        embedding_idx_info = {
-            info: value for info, value in idx_info_dict.items() if isinstance(value.idx, index.EmbeddingIndex)
-        }
-        if len(embedding_idx_info) == 0:
-            raise excs.Error(f'No indices found for {method_name!r} on column {self.col.name!r}')
-        if idx_name is not None and idx_name not in embedding_idx_info:
-            raise excs.Error(f'Index {idx_name!r} not found for {method_name!r} on column {self.col.name!r}')
-        if len(embedding_idx_info) > 1:
-            if idx_name is None:
-                raise excs.Error(
-                    f'Column {self.col.name!r} has multiple indices; use the index name to disambiguate: '
-                    f'`{method_name}(..., idx=<index_name>)`'
-                )
-            idx_info = {idx_name: embedding_idx_info[idx_name]}
-        else:
-            idx_info = embedding_idx_info
-        return idx_info
-
     def recompute(self, *, cascade: bool = True, errors_only: bool = False) -> catalog.UpdateStatus:
         cat = catalog.Catalog.get()
         # lock_mutable_tree=True: we need to be able to see whether any transitive view has column dependents
@@ -185,49 +159,52 @@ class ColumnRef(Expr):
             FileCache.get().emit_eviction_warnings()
             return status
 
-    def similarity(self, item: Any, *, idx: Optional[str] = None) -> Expr:
+    def similarity(self, item: Any, *, idx: str | None = None) -> Expr:
         from .similarity_expr import SimilarityExpr
 
         return SimilarityExpr(self, item, idx_name=idx)
 
-    def embedding(self, *, idx: Optional[str] = None) -> ColumnRef:
-        idx_info = self.find_embedding_index(idx, 'embedding')
-        assert len(idx_info) == 1
-        col = copy.copy(next(iter(idx_info.values())).val_col)
-        col.name = f'{self.col.name}_embedding_{idx if idx is not None else ""}'
-        # col.create_sa_cols()
-        return ColumnRef(col)
+    def embedding(self, *, idx: str | None = None) -> ColumnRef:
+        from pixeltable.index import EmbeddingIndex
+
+        idx_info = self.tbl.get().get_idx(self.col, idx, EmbeddingIndex)
+        return ColumnRef(idx_info.val_col)
 
-    def default_column_name(self) -> Optional[str]:
+    @property
+    def tbl(self) -> catalog.TableVersionHandle:
+        return self.reference_tbl.tbl_version if self.reference_tbl is not None else self.col.tbl_handle
+
+    def default_column_name(self) -> str | None:
         return self.col.name if self.col is not None else None
 
     def _equals(self, other: ColumnRef) -> bool:
         return self.col == other.col and self.perform_validation == other.perform_validation
 
-    def _df(self) -> 'pxt.dataframe.DataFrame':
-        from pixeltable import plan
+    def _df(self) -> 'DataFrame':
+        import pixeltable.plan as plan
+        from pixeltable.dataframe import DataFrame
 
         if self.reference_tbl is None:
             # No reference table; use the current version of the table to which the column belongs
-            tbl = catalog.Catalog.get().get_table_by_id(self.col.tbl.id)
+            tbl = catalog.Catalog.get().get_table_by_id(self.col.tbl_handle.id)
             return tbl.select(self)
         else:
             # Explicit reference table; construct a DataFrame directly from it
-            return pxt.DataFrame(plan.FromClause([self.reference_tbl])).select(self)
+            return DataFrame(plan.FromClause([self.reference_tbl])).select(self)
 
-    def show(self, *args: Any, **kwargs: Any) -> 'pxt.dataframe.DataFrameResultSet':
+    def show(self, *args: Any, **kwargs: Any) -> 'DataFrameResultSet':
         return self._df().show(*args, **kwargs)
 
-    def head(self, *args: Any, **kwargs: Any) -> 'pxt.dataframe.DataFrameResultSet':
+    def head(self, *args: Any, **kwargs: Any) -> 'DataFrameResultSet':
         return self._df().head(*args, **kwargs)
 
-    def tail(self, *args: Any, **kwargs: Any) -> 'pxt.dataframe.DataFrameResultSet':
+    def tail(self, *args: Any, **kwargs: Any) -> 'DataFrameResultSet':
         return self._df().tail(*args, **kwargs)
 
     def count(self) -> int:
         return self._df().count()
 
-    def distinct(self) -> 'pxt.dataframe.DataFrame':
+    def distinct(self) -> 'DataFrame':
         """Return distinct values in this column."""
         return self._df().distinct()
 
@@ -244,7 +221,7 @@ class ColumnRef(Expr):
         return self._descriptors().to_html()
 
     def _descriptors(self) -> DescriptionHelper:
-        tbl = catalog.Catalog.get().get_table_by_id(self.col.tbl.id)
+        tbl = catalog.Catalog.get().get_table_by_id(self.col.tbl_handle.id)
         helper = DescriptionHelper()
         helper.append(f'Column\n{self.col.name!r}\n(of table {tbl._path()!r})')
         helper.append(tbl._col_descriptor([self.col.name]))
@@ -253,7 +230,18 @@ class ColumnRef(Expr):
             helper.append(idxs)
         return helper
 
-    def sql_expr(self, _: SqlElementCache) -> Optional[sql.ColumnElement]:
+    def prepare(self) -> None:
+        from pixeltable import store
+
+        if not self.is_unstored_iter_col:
+            return
+        col = self.col_handle.get()
+        self.base_rowid_len = col.get_tbl().base.get().num_rowid_columns()
+        self.base_rowid = [None] * self.base_rowid_len
+        assert isinstance(col.get_tbl().store_tbl, store.StoreComponentView)
+        self.pos_idx = cast(store.StoreComponentView, col.get_tbl().store_tbl).pos_col_idx
+
+    def sql_expr(self, _: SqlElementCache) -> sql.ColumnElement | None:
         if self.perform_validation:
             return None
         self.col = self.col_handle.get()
@@ -298,20 +286,19 @@ class ColumnRef(Expr):
         if self.base_rowid != data_row.pk[: self.base_rowid_len]:
             row_builder.eval(data_row, self.iter_arg_ctx)
             iterator_args = data_row[self.iter_arg_ctx.target_slot_idxs[0]]
-            self.iterator = self.col.tbl.iterator_cls(**iterator_args)
+            self.iterator = self.col.get_tbl().iterator_cls(**iterator_args)
             self.base_rowid = data_row.pk[: self.base_rowid_len]
         self.iterator.set_pos(data_row.pk[self.pos_idx])
         res = next(self.iterator)
         data_row[self.slot_idx] = res[self.col.name]
 
     def _as_dict(self) -> dict:
-        tbl = self.col.tbl
-        version = tbl.version if tbl.is_snapshot else None
+        tbl_handle = self.col.tbl_handle
         # we omit self.components, even if this is a validating ColumnRef, because init() will recreate the
         # non-validating component ColumnRef
         return {
-            'tbl_id': str(tbl.id),
-            'tbl_version': version,
+            'tbl_id': str(tbl_handle.id),
+            'tbl_version': tbl_handle.effective_version,
             'col_id': self.col.id,
             'reference_tbl': self.reference_tbl.as_dict() if self.reference_tbl is not None else None,
             'perform_validation': self.perform_validation,

pixeltable/exprs/comparison.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any
 
 import sqlalchemy as sql
 
@@ -69,8 +69,8 @@ class Comparison(Expr):
     def _op2(self) -> Expr:
         return self.components[1]
 
-    def sql_expr(self, sql_elements: SqlElementCache) -> Optional[sql.ColumnElement]:
-        from pixeltable import index
+    def sql_expr(self, sql_elements: SqlElementCache) -> sql.ColumnElement | None:
+        import pixeltable.index as index
 
         if str(self._op1.col_type.to_sa_type()) != str(self._op2.col_type.to_sa_type()):
             # Comparing columns of different SQL types (e.g., string vs. json); this can only be done in Python
@@ -81,9 +81,9 @@ class Comparison(Expr):
         if self.is_search_arg_comparison:
             # reference the index value column if there is an index and this is not a snapshot
             # (indices don't apply to snapshots)
-            tbl = self._op1.col.tbl
+            tbl = self._op1.col.get_tbl()
             idx_info = [
-                info for info in self._op1.col.get_idx_info().values() if isinstance(info.idx, index.BtreeIndex)
+                info for info in tbl.idxs_by_col.get(self._op1.col.qid, []) if isinstance(info.idx, index.BtreeIndex)
             ]
             if len(idx_info) > 0 and not tbl.is_snapshot:
                 # there shouldn't be multiple B-tree indices on a column

pixeltable/exprs/compound_predicate.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import operator
-from typing import Any, Callable, Optional
+from typing import Any, Callable
 
 import sqlalchemy as sql
 
@@ -61,14 +61,14 @@ class CompoundPredicate(Expr):
     def _id_attrs(self) -> list[tuple[str, Any]]:
         return [*super()._id_attrs(), ('operator', self.operator.value)]
 
-    def split_conjuncts(self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Optional[Expr]]:
+    def split_conjuncts(self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Expr | None]:
         if self.operator in (LogicalOperator.OR, LogicalOperator.NOT):
             return super().split_conjuncts(condition)
         matches = [op for op in self.components if condition(op)]
         non_matches = [op for op in self.components if not condition(op)]
         return (matches, self.make_conjunction(non_matches))
 
-    def sql_expr(self, sql_elements: SqlElementCache) -> Optional[sql.ColumnElement]:
+    def sql_expr(self, sql_elements: SqlElementCache) -> sql.ColumnElement | None:
         sql_exprs = [sql_elements.get(op) for op in self.components]
         if any(e is None for e in sql_exprs):
             return None

pixeltable/exprs/data_row.py

@@ -6,7 +6,7 @@ import io
 import urllib.parse
 import urllib.request
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 import numpy as np
 import pgvector.sqlalchemy  # type: ignore[import-untyped]
@@ -126,10 +126,10 @@ class DataRow:
     _may_have_exc: bool
 
     # the primary key of a store row is a sequence of ints (the number is different for table vs view)
-    pk: Optional[tuple[int, ...]]
+    pk: tuple[int, ...] | None
     # for nested rows (ie, those produced by JsonMapperDispatcher)
-    parent_row: Optional[DataRow]
-    parent_slot_idx: Optional[int]
+    parent_row: DataRow | None
+    parent_slot_idx: int | None
 
     # state for table output (insert()/update()); key: column id
     cell_vals: dict[int, Any]  # materialized values of output columns, in the format required for the column
@@ -148,8 +148,8 @@ class DataRow:
         media_slot_idxs: list[int],
         array_slot_idxs: list[int],
         json_slot_idxs: list[int],
-        parent_row: Optional[DataRow] = None,
-        parent_slot_idx: Optional[int] = None,
+        parent_row: DataRow | None = None,
+        parent_slot_idx: int | None = None,
     ):
         self.init(size)
         self.parent_row = parent_row
@@ -176,7 +176,7 @@ class DataRow:
         self.parent_row = None
         self.parent_slot_idx = None
 
-    def clear(self, slot_idxs: Optional[np.ndarray] = None) -> None:
+    def clear(self, slot_idxs: np.ndarray | None = None) -> None:
         if slot_idxs is not None:
             self.has_val[slot_idxs] = False
             self.vals[slot_idxs] = None
@@ -209,7 +209,7 @@ class DataRow:
     def set_pk(self, pk: tuple[int, ...]) -> None:
         self.pk = pk
 
-    def has_exc(self, slot_idx: Optional[int] = None) -> bool:
+    def has_exc(self, slot_idx: int | None = None) -> bool:
         """
         Returns True if an exception has been set for the given slot index, or for any slot index if slot_idx is None
         """
@@ -220,12 +220,12 @@ class DataRow:
             return self.excs[slot_idx] is not None
         return (self.excs != None).any()
 
-    def get_exc(self, slot_idx: int) -> Optional[Exception]:
+    def get_exc(self, slot_idx: int) -> Exception | None:
         exc = self.excs[slot_idx]
         assert exc is None or isinstance(exc, Exception)
         return exc
 
-    def get_first_exc(self) -> Optional[Exception]:
+    def get_first_exc(self) -> Exception | None:
         mask = self.excs != None
         if not mask.any():
             return None
@@ -260,7 +260,7 @@ class DataRow:
 
         return self.vals[index]
 
-    def get_stored_val(self, index: int, sa_col_type: Optional[sql.types.TypeEngine] = None) -> Any:
+    def get_stored_val(self, index: int, sa_col_type: sql.types.TypeEngine | None = None) -> Any:
         """Return the value that gets stored in the db"""
         assert self.excs[index] is None
         if not self.has_val[index]:
@@ -328,7 +328,7 @@ class DataRow:
             self.vals[idx] = val
         self.has_val[idx] = True
 
-    def prepare_col_val_for_save(self, index: int, col: Optional[catalog.Column] = None) -> bool:
+    def prepare_col_val_for_save(self, index: int, col: catalog.Column | None = None) -> bool:
         """
         Prepare to save a column's value into the appropriate store. Discard unneeded values.
 

pixeltable/exprs/expr.py

@@ -7,7 +7,7 @@ import inspect
 import json
 import sys
 import typing
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, Optional, TypeVar, overload
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Iterator, TypeVar, overload
 from uuid import UUID
 
 import numpy as np
@@ -29,7 +29,7 @@ class ExprScope:
     parent is None: outermost scope
     """
 
-    def __init__(self, parent: Optional[ExprScope]):
+    def __init__(self, parent: ExprScope | None):
         self.parent = parent
 
     def is_contained_in(self, other: ExprScope) -> bool:
@@ -61,13 +61,13 @@ class Expr(abc.ABC):
     # - set by the subclass's __init__()
     # - produced by _create_id()
     # - not expected to survive a serialize()/deserialize() roundtrip
-    id: Optional[int]
+    id: int | None
 
     # index of the expr's value in the data row:
     # - set for all materialized exprs
     # - None: not executable
     # - not set for subexprs that don't need to be materialized because the parent can be materialized via SQL
-    slot_idx: Optional[int]
+    slot_idx: int | None
 
     T = TypeVar('T', bound='Expr')
 
@@ -103,7 +103,7 @@ class Expr(abc.ABC):
         assert not has_rel_path, self._expr_tree()
         assert not self._has_relative_path(), self._expr_tree()
 
-    def _bind_rel_paths(self, mapper: Optional['exprs.JsonMapperDispatch'] = None) -> None:
+    def _bind_rel_paths(self, mapper: 'exprs.JsonMapperDispatch' | None = None) -> None:
         for c in self.components:
             c._bind_rel_paths(mapper)
 
@@ -118,7 +118,7 @@ class Expr(abc.ABC):
         for c in self.components:
             c._expr_tree_r(indent + 2, buf)
 
-    def default_column_name(self) -> Optional[str]:
+    def default_column_name(self) -> str | None:
         """
         Returns:
             None if this expression lacks a default name,
@@ -127,7 +127,7 @@ class Expr(abc.ABC):
         return None
 
     @property
-    def validation_error(self) -> Optional[str]:
+    def validation_error(self) -> str | None:
         """
         Subclasses can override this to indicate that validation has failed after a catalog load.
 
@@ -205,12 +205,12 @@ class Expr(abc.ABC):
         return result
 
     @classmethod
-    def copy_list(cls, expr_list: Optional[list[Expr]]) -> Optional[list[Expr]]:
+    def copy_list(cls, expr_list: list[Expr] | None) -> list[Expr] | None:
         if expr_list is None:
             return None
         return [e.copy() for e in expr_list]
 
-    def __deepcopy__(self, memo: Optional[dict[int, Any]] = None) -> Expr:
+    def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Expr:
         # we don't need to create an actual deep copy because all state other than execution state is read-only
         if memo is None:
             memo = {}
@@ -241,7 +241,7 @@ class Expr(abc.ABC):
         for i in range(len(expr_list)):
             expr_list[i] = expr_list[i].substitute(spec)
 
-    def resolve_computed_cols(self, resolve_cols: Optional[set[catalog.Column]] = None) -> Expr:
+    def resolve_computed_cols(self, resolve_cols: set[catalog.Column] | None = None) -> Expr:
         """
         Recursively replace ColRefs to unstored computed columns with their value exprs.
         Also replaces references to stored computed columns in resolve_cols.
@@ -309,18 +309,18 @@ class Expr(abc.ABC):
 
     @overload
     def subexprs(
-        self, *, filter: Optional[Callable[[Expr], bool]] = None, traverse_matches: bool = True
+        self, *, filter: Callable[[Expr], bool] | None = None, traverse_matches: bool = True
     ) -> Iterator[Expr]: ...
 
     @overload
     def subexprs(
-        self, expr_class: type[T], filter: Optional[Callable[[Expr], bool]] = None, traverse_matches: bool = True
+        self, expr_class: type[T], filter: Callable[[Expr], bool] | None = None, traverse_matches: bool = True
     ) -> Iterator[T]: ...
 
     def subexprs(
         self,
-        expr_class: Optional[type[T]] = None,
-        filter: Optional[Callable[[Expr], bool]] = None,
+        expr_class: type[T] | None = None,
+        filter: Callable[[Expr], bool] | None = None,
         traverse_matches: bool = True,
     ) -> Iterator[T]:
         """
@@ -339,11 +339,7 @@ class Expr(abc.ABC):
     @overload
     @classmethod
     def list_subexprs(
-        cls,
-        expr_list: Iterable[Expr],
-        *,
-        filter: Optional[Callable[[Expr], bool]] = None,
-        traverse_matches: bool = True,
+        cls, expr_list: Iterable[Expr], *, filter: Callable[[Expr], bool] | None = None, traverse_matches: bool = True
     ) -> Iterator[Expr]: ...
 
     @overload
@@ -352,7 +348,7 @@ class Expr(abc.ABC):
         cls,
         expr_list: Iterable[Expr],
         expr_class: type[T],
-        filter: Optional[Callable[[Expr], bool]] = None,
+        filter: Callable[[Expr], bool] | None = None,
         traverse_matches: bool = True,
     ) -> Iterator[T]: ...
 
@@ -360,8 +356,8 @@ class Expr(abc.ABC):
     def list_subexprs(
         cls,
         expr_list: Iterable[Expr],
-        expr_class: Optional[type[T]] = None,
-        filter: Optional[Callable[[Expr], bool]] = None,
+        expr_class: type[T] | None = None,
+        filter: Callable[[Expr], bool] | None = None,
         traverse_matches: bool = True,
     ) -> Iterator[T]:
         """Produce subexprs for all exprs in list. Can contain duplicates."""
@@ -377,7 +373,7 @@ class Expr(abc.ABC):
     ) -> bool:
         return any(e._contains(expr_class, filter) for e in expr_list)
 
-    def _contains(self, cls: Optional[type[Expr]] = None, filter: Optional[Callable[[Expr], bool]] = None) -> bool:
+    def _contains(self, cls: type[Expr] | None = None, filter: Callable[[Expr], bool] | None = None) -> bool:
         """
         Returns True if any subexpr is an instance of cls and/or matches filter.
         """
@@ -396,7 +392,9 @@ class Expr(abc.ABC):
         from .column_ref import ColumnRef
         from .rowid_ref import RowidRef
 
-        return {ref.col.tbl.id for ref in self.subexprs(ColumnRef)} | {ref.tbl.id for ref in self.subexprs(RowidRef)}
+        return {ref.col.get_tbl().id for ref in self.subexprs(ColumnRef)} | {
+            ref.tbl.id for ref in self.subexprs(RowidRef)
+        }
 
     @classmethod
     def all_tbl_ids(cls, exprs_: Iterable[Expr]) -> set[UUID]:
@@ -416,14 +414,14 @@ class Expr(abc.ABC):
                 result.update(cls.get_refd_column_ids(component_dict))
         return result
 
-    def as_literal(self) -> Optional[Expr]:
+    def as_literal(self) -> Expr | None:
         """
         Return a Literal expression if this expression can be evaluated to a constant value, otherwise return None.
         """
         return None
 
     @classmethod
-    def from_array(cls, elements: Iterable) -> Optional[Expr]:
+    def from_array(cls, elements: Iterable) -> Expr | None:
         from .inline_expr import InlineArray
         from .literal import Literal
 
@@ -446,7 +444,7 @@ class Expr(abc.ABC):
             return self
 
     @classmethod
-    def from_object(cls, o: object) -> Optional[Expr]:
+    def from_object(cls, o: object) -> Expr | None:
         """
         Try to turn a literal object into an Expr.
         """
@@ -476,7 +474,7 @@ class Expr(abc.ABC):
                 return Literal(o, col_type=obj_type)
         return None
 
-    def sql_expr(self, sql_elements: 'exprs.SqlElementCache') -> Optional[sql.ColumnElement]:
+    def sql_expr(self, sql_elements: 'exprs.SqlElementCache') -> sql.ColumnElement | None:
         """
         If this expr can be materialized directly in SQL:
         - returns a ColumnElement
@@ -495,6 +493,18 @@ class Expr(abc.ABC):
         """
         pass
 
+    def prepare(self) -> None:
+        """
+        Create execution state. This is called before the first eval() call.
+        """
+        for c in self.components:
+            c.prepare()
+
+    @classmethod
+    def prepare_list(cls, expr_list: Iterable[Expr]) -> None:
+        for e in expr_list:
+            e.prepare()
+
     def release(self) -> None:
         """
         Allow Expr class to tear down execution state. This is called after the last eval() call.
@@ -503,7 +513,7 @@ class Expr(abc.ABC):
             c.release()
 
     @classmethod
-    def release_list(cls, expr_list: list[Expr]) -> None:
+    def release_list(cls, expr_list: Iterable[Expr]) -> None:
         for e in expr_list:
             e.release()
 
@@ -791,7 +801,7 @@ class Expr(abc.ABC):
 
         return CompoundPredicate(LogicalOperator.NOT, [self])
 
-    def split_conjuncts(self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Optional[Expr]]:
+    def split_conjuncts(self, condition: Callable[[Expr], bool]) -> tuple[list[Expr], Expr | None]:
         """
         Returns clauses of a conjunction that meet condition in the first element.
         The second element contains remaining clauses, rolled into a conjunction.
@@ -802,7 +812,7 @@ class Expr(abc.ABC):
         else:
             return [], self
 
-    def _make_applicator_function(self, fn: Callable, col_type: Optional[ts.ColumnType]) -> 'func.Function':
+    def _make_applicator_function(self, fn: Callable, col_type: ts.ColumnType | None) -> 'func.Function':
         """
         Creates a unary pixeltable `Function` that encapsulates a python `Callable`. The result type of
         the new `Function` is given by `col_type`, and its parameter type will be `self.col_type`.

pixeltable/exprs/expr_dict.py

@@ -1,4 +1,4 @@
-from typing import Generic, Iterable, Iterator, Optional, TypeVar
+from typing import Generic, Iterable, Iterator, TypeVar
 
 from .expr import Expr
 
@@ -14,7 +14,7 @@ class ExprDict(Generic[T]):
 
     _data: dict[int, tuple[Expr, T]]
 
-    def __init__(self, iterable: Optional[Iterable[tuple[Expr, T]]] = None):
+    def __init__(self, iterable: Iterable[tuple[Expr, T]] | None = None):
         self._data = {}
 
         if iterable is not None:
@@ -39,7 +39,7 @@ class ExprDict(Generic[T]):
     def __contains__(self, key: Expr) -> bool:
         return key.id in self._data
 
-    def get(self, key: Expr, default: Optional[T] = None) -> Optional[T]:
+    def get(self, key: Expr, default: T | None = None) -> T | None:
         item = self._data.get(key.id)
         return item[1] if item is not None else default