pixeltable 0.2.28__py3-none-any.whl → 0.2.29__py3-none-any.whl

pixeltable/exprs/function_call.py

@@ -15,6 +15,7 @@ import pixeltable.type_system as ts
 from .data_row import DataRow
 from .expr import Expr
 from .inline_expr import InlineDict, InlineList
+from .literal import Literal
 from .row_builder import RowBuilder
 from .rowid_ref import RowidRef
 from .sql_element_cache import SqlElementCache
@@ -34,6 +35,7 @@ class FunctionCall(Expr):
 
     arg_types: list[ts.ColumnType]
     kwarg_types: dict[str, ts.ColumnType]
+    return_type: ts.ColumnType
     group_by_start_idx: int
     group_by_stop_idx: int
     fn_expr_idx: int
@@ -43,17 +45,25 @@ class FunctionCall(Expr):
     current_partition_vals: Optional[list[Any]]
 
     def __init__(
-            self, fn: func.Function, bound_args: dict[str, Any], order_by_clause: Optional[list[Any]] = None,
-            group_by_clause: Optional[list[Any]] = None, is_method_call: bool = False):
+        self,
+        fn: func.Function,
+        bound_args: dict[str, Any],
+        return_type: ts.ColumnType,
+        order_by_clause: Optional[list[Any]] = None,
+        group_by_clause: Optional[list[Any]] = None,
+        is_method_call: bool = False
+    ):
         if order_by_clause is None:
             order_by_clause = []
         if group_by_clause is None:
             group_by_clause = []
-        signature = fn.signature
-        return_type = fn.call_return_type(bound_args)
+
+        assert not fn.is_polymorphic
+
         self.fn = fn
         self.is_method_call = is_method_call
-        self.normalize_args(fn.name, signature, bound_args)
+
+        signature = fn.signature
 
         # If `return_type` is non-nullable, but the function call has a nullable input to any of its non-nullable
         # parameters, then we need to make it nullable. This is because Pixeltable defaults a function output to
@@ -67,6 +77,8 @@ class FunctionCall(Expr):
                 return_type = return_type.copy(nullable=True)
                 break
 
+        self.return_type = return_type
+
         super().__init__(return_type)
 
         self.agg_init_args = {}
@@ -74,9 +86,9 @@ class FunctionCall(Expr):
             # we separate out the init args for the aggregator
             assert isinstance(fn, func.AggregateFunction)
             self.agg_init_args = {
-                arg_name: arg for arg_name, arg in bound_args.items() if arg_name in fn.init_param_names
+                arg_name: arg for arg_name, arg in bound_args.items() if arg_name in fn.init_param_names[0]
             }
-            bound_args = {arg_name: arg for arg_name, arg in bound_args.items() if arg_name not in fn.init_param_names}
+            bound_args = {arg_name: arg for arg_name, arg in bound_args.items() if arg_name not in fn.init_param_names[0]}
 
         # construct components, args, kwargs
         self.args = []
@@ -88,7 +100,7 @@ class FunctionCall(Expr):
 
         # the prefix of parameters that are bound can be passed by position
         processed_args: set[str] = set()
-        for py_param in fn.signature.py_signature.parameters.values():
+        for py_param in signature.py_signature.parameters.values():
             if py_param.name not in bound_args or py_param.kind == inspect.Parameter.KEYWORD_ONLY:
                 break
             arg = bound_args[py_param.name]
@@ -110,7 +122,7 @@ class FunctionCall(Expr):
                     self.components.append(arg.copy())
                 else:
                     self.kwargs[param_name] = (None, arg)
-                if fn.signature.py_signature.parameters[param_name].kind != inspect.Parameter.VAR_KEYWORD:
+                if signature.py_signature.parameters[param_name].kind != inspect.Parameter.VAR_KEYWORD:
                     self.kwarg_types[param_name] = signature.parameters[param_name].col_type
 
         # window function state:
@@ -129,7 +141,7 @@ class FunctionCall(Expr):
 
         if isinstance(self.fn, func.ExprTemplateFunction):
             # we instantiate the template to create an Expr that can be evaluated and record that as a component
-            fn_expr = self.fn.instantiate(**bound_args)
+            fn_expr = self.fn.instantiate([], bound_args)
             self.components.append(fn_expr)
             self.fn_expr_idx = len(self.components) - 1
         else:
@@ -360,7 +372,7 @@ class FunctionCall(Expr):
         """
         assert self.is_agg_fn_call
         assert isinstance(self.fn, func.AggregateFunction)
-        self.aggregator = self.fn.agg_cls(**self.agg_init_args)
+        self.aggregator = self.fn.agg_class(**self.agg_init_args)
 
     def update(self, data_row: DataRow) -> None:
         """
@@ -432,27 +444,32 @@ class FunctionCall(Expr):
             data_row[self.slot_idx] = self.fn.py_fn(*args, **kwargs)
         elif self.is_window_fn_call:
             assert isinstance(self.fn, func.AggregateFunction)
+            agg_cls = self.fn.agg_class
             if self.has_group_by():
                 if self.current_partition_vals is None:
                     self.current_partition_vals = [None] * len(self.group_by)
                 partition_vals = [data_row[e.slot_idx] for e in self.group_by]
                 if partition_vals != self.current_partition_vals:
                     # new partition
-                    self.aggregator = self.fn.agg_cls(**self.agg_init_args)
+                    self.aggregator = agg_cls(**self.agg_init_args)
                     self.current_partition_vals = partition_vals
             elif self.aggregator is None:
-                self.aggregator = self.fn.agg_cls(**self.agg_init_args)
+                self.aggregator = agg_cls(**self.agg_init_args)
             self.aggregator.update(*args)
             data_row[self.slot_idx] = self.aggregator.value()
         else:
-            data_row[self.slot_idx] = self.fn.exec(*args, **kwargs)
+            data_row[self.slot_idx] = self.fn.exec(args, kwargs)
 
     def _as_dict(self) -> dict:
         result = {
-            'fn': self.fn.as_dict(), 'args': self.args, 'kwargs': self.kwargs,
-            'group_by_start_idx': self.group_by_start_idx, 'group_by_stop_idx': self.group_by_stop_idx,
+            'fn': self.fn.as_dict(),
+            'args': self.args,
+            'kwargs': self.kwargs,
+            'return_type': self.return_type.as_dict(),
+            'group_by_start_idx': self.group_by_start_idx,
+            'group_by_stop_idx': self.group_by_stop_idx,
             'order_by_start_idx': self.order_by_start_idx,
-            **super()._as_dict()
+            **super()._as_dict(),
         }
         return result
 
@@ -461,15 +478,108 @@ class FunctionCall(Expr):
         assert 'fn' in d
         assert 'args' in d
         assert 'kwargs' in d
-        # reassemble bound args
+
         fn = func.Function.from_dict(d['fn'])
-        param_names = list(fn.signature.parameters.keys())
-        bound_args = {param_names[i]: arg if idx is None else components[idx] for i, (idx, arg) in enumerate(d['args'])}
-        bound_args.update(
-            {param_name: val if idx is None else components[idx] for param_name, (idx, val) in d['kwargs'].items()})
+        assert not fn.is_polymorphic
+        return_type = ts.ColumnType.from_dict(d['return_type']) if 'return_type' in d else None
         group_by_exprs = components[d['group_by_start_idx']:d['group_by_stop_idx']]
         order_by_exprs = components[d['order_by_start_idx']:]
+
+        args = [
+            expr if idx is None else components[idx]
+            for idx, expr in d['args']
+        ]
+        kwargs = {
+            param_name: (expr if idx is None else components[idx])
+            for param_name, (idx, expr) in d['kwargs'].items()
+        }
+
+        # `Function.from_dict()` does signature matching, so it is safe to assume that `args` and `kwargs` are
+        # consistent with its signature.
+
+        # Reassemble bound_args. Note that args and kwargs represent "already bound arguments": they are not bindable
+        # in the Python sense, because variable args (such as *args and **kwargs) have already been condensed.
+        param_names = list(fn.signature.parameters.keys())
+        bound_args = {param_names[i]: arg for i, arg in enumerate(args)}
+        bound_args.update(kwargs.items())
+
+        # TODO: In order to properly invoke call_return_type, we need to ensure that any InlineLists or InlineDicts
+        # in bound_args are unpacked into Python lists/dicts. There is an open task to ensure this is true in general;
+        # for now, as a hack, we do the unpacking here for the specific case of an InlineList of Literals (the only
+        # case where this is necessary to support existing conditional_return_type implementations). Once the general
+        # pattern is implemented, we can remove this hack.
+        unpacked_bound_args = {
+            param_name: cls.__unpack_bound_arg(arg) for param_name, arg in bound_args.items()
+        }
+
+        # Evaluate the call_return_type as defined in the current codebase.
+        call_return_type = fn.call_return_type([], unpacked_bound_args)
+
+        if return_type is None:
+            # Schema versions prior to 25 did not store the return_type in metadata, and there is no obvious way to
+            # infer it during DB migration, so we might encounter a stored return_type of None. In that case, we use
+            # the call_return_type that we just inferred (which matches the deserialization behavior prior to
+            # version 25).
+            return_type = call_return_type
+        else:
+            # There is a return_type stored in metadata (schema version >= 25).
+            # Check that the stored return_type of the UDF call matches the column type of the FunctionCall, and
+            # fail-fast if it doesn't (otherwise we risk getting downstream database errors).
+            # TODO: Handle this more gracefully (instead of failing the DB load, allow the DB load to succeed, but
+            #       mark this FunctionCall as unusable). It's the same issue as dealing with a renamed UDF or Function
+            #       signature mismatch.
+            if not return_type.is_supertype_of(call_return_type, ignore_nullable=True):
+                raise excs.Error(
+                    f'The return type stored in the database for a UDF call to `{fn.self_path}` no longer matches the '
+                    f'return type of the UDF as currently defined in the code.\nThis probably means that the code for '
+                    f'`{fn.self_path}` has changed in a backward-incompatible way.\n'
+                    f'Return type in database: `{return_type}`\n'
+                    f'Return type as currently defined: `{call_return_type}`'
+                )
+
         fn_call = cls(
-            func.Function.from_dict(d['fn']), bound_args, group_by_clause=group_by_exprs,
-            order_by_clause=order_by_exprs)
+            fn,
+            bound_args,
+            return_type,
+            group_by_clause=group_by_exprs,
+            order_by_clause=order_by_exprs
+        )
         return fn_call
+
+    @classmethod
+    def __find_matching_signature(cls, fn: func.Function, args: list[Any], kwargs: dict[str, Any]) -> Optional[int]:
+        for idx, sig in enumerate(fn.signatures):
+            if cls.__signature_matches(sig, args, kwargs):
+                return idx
+        return None
+
+    @classmethod
+    def __signature_matches(cls, sig: func.Signature, args: list[Any], kwargs: dict[str, Any]) -> bool:
+        unbound_parameters = set(sig.parameters.keys())
+        for i, arg in enumerate(args):
+            if i >= len(sig.parameters_by_pos):
+                return False
+            param = sig.parameters_by_pos[i]
+            arg_type = arg.col_type if isinstance(arg, Expr) else ts.ColumnType.infer_literal_type(arg)
+            if param.col_type is not None and not param.col_type.is_supertype_of(arg_type, ignore_nullable=True):
+                return False
+            unbound_parameters.remove(param.name)
+        for param_name, arg in kwargs.items():
+            if param_name not in unbound_parameters:
+                return False
+            param = sig.parameters[param_name]
+            arg_type = arg.col_type if isinstance(arg, Expr) else ts.ColumnType.infer_literal_type(arg)
+            if param.col_type is not None and not param.col_type.is_supertype_of(arg_type, ignore_nullable=True):
+                return False
+            unbound_parameters.remove(param_name)
+        for param_name in unbound_parameters:
+            param = sig.parameters[param_name]
+            if not param.has_default:
+                return False
+        return True
+
+    @classmethod
+    def __unpack_bound_arg(cls, arg: Any) -> Any:
+        if isinstance(arg, InlineList) and all(isinstance(el, Literal) for el in arg.components):
+            return [el.val for el in arg.components]
+        return arg

pixeltable/exprs/inline_expr.py

@@ -101,7 +101,13 @@ class InlineList(Expr):
             else:
                 exprs.append(Literal(el))
 
-        super().__init__(ts.JsonType())
+        json_schema = {
+            'type': 'array',
+            'prefixItems': [expr.col_type.to_json_schema() for expr in exprs],
+            'items': False  # No additional items (fixed length)
+        }
+
+        super().__init__(ts.JsonType(json_schema))
         self.components.extend(exprs)
         self.id = self._create_id()
 
@@ -149,7 +155,21 @@ class InlineDict(Expr):
             else:
                 exprs.append(Literal(val))
 
-        super().__init__(ts.JsonType())
+        json_schema: Optional[dict[str, Any]]
+        try:
+            json_schema = {
+                'type': 'object',
+                'properties': {
+                    key: expr.col_type.to_json_schema()
+                    for key, expr in zip(self.keys, exprs)
+                },
+            }
+        except excs.Error:
+            # InlineDicts are used to store iterator arguments, which are not required to be valid JSON types,
+            # so we can't always construct a valid schema.
+            json_schema = None
+
+        super().__init__(ts.JsonType(json_schema))
         self.components.extend(exprs)
         self.id = self._create_id()
 

pixeltable/exprs/row_builder.py

@@ -368,7 +368,7 @@ class RowBuilder:
                 if not ignore_errors:
                     input_vals = [data_row[d.slot_idx] for d in expr.dependencies()]
                     raise excs.ExprEvalError(
-                        expr, f'expression {expr}', data_row.get_exc(expr.slot_idx), exc_tb, input_vals, 0)
+                        expr, f'expression {expr}', data_row.get_exc(expr.slot_idx), exc_tb, input_vals, 0) from exc
 
     def create_table_row(self, data_row: DataRow, exc_col_ids: set[int]) -> tuple[dict[str, Any], int]:
         """Create a table row from the slots that have an output column assigned

pixeltable/exprs/similarity_expr.py

@@ -23,7 +23,6 @@ class SimilarityExpr(Expr):
         assert item_expr.col_type.is_string_type() or item_expr.col_type.is_image_type()
 
         self.components = [col_ref, item_expr]
-        self.id = self._create_id()
 
         # determine index to use
         idx_info = col_ref.col.get_idx_info()
@@ -54,10 +53,14 @@ class SimilarityExpr(Expr):
             raise excs.Error(
                 f'Embedding index {self.idx_info.name!r} on column {self.idx_info.col.name!r} was created without the '
                 f"'image_embed' parameter and does not support image queries")
+        self.id = self._create_id()
 
     def __repr__(self) -> str:
         return f'{self.components[0]}.similarity({self.components[1]})'
 
+    def _id_attrs(self):
+        return super()._id_attrs() + [('idx_name', self.idx_info.name)]
+
     def default_column_name(self) -> str:
         return 'similarity'
 
@@ -81,8 +84,12 @@ class SimilarityExpr(Expr):
         # this should never get called
         assert False
 
+    def _as_dict(self) -> dict:
+        return {'idx_name': self.idx_info.name, **super()._as_dict()}
+
     @classmethod
     def _from_dict(cls, d: dict, components: list[Expr]) -> 'SimilarityExpr':
+        iname = d['idx_name'] if 'idx_name' in d else None
         assert len(components) == 2
         assert isinstance(components[0], ColumnRef)
-        return cls(components[0], components[1])
+        return cls(components[0], components[1], idx_name=iname)

pixeltable/func/aggregate_function.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import abc
 import inspect
-from typing import TYPE_CHECKING, Any, Callable, Optional
+from typing import TYPE_CHECKING, Any, Callable, Optional, Sequence, overload
 
 import pixeltable.exceptions as excs
 import pixeltable.type_system as ts
@@ -35,26 +35,73 @@ class AggregateFunction(Function):
     GROUP_BY_PARAM = 'group_by'
     RESERVED_PARAMS = {ORDER_BY_PARAM, GROUP_BY_PARAM}
 
+    agg_classes: list[type[Aggregator]]  # classes for each signature, in signature order
+    init_param_names: list[list[str]]  # names of the __init__ parameters for each signature
+
     def __init__(
-            self, aggregator_class: type[Aggregator], self_path: str,
-            init_types: list[ts.ColumnType], update_types: list[ts.ColumnType], value_type: ts.ColumnType,
-            requires_order_by: bool, allows_std_agg: bool, allows_window: bool):
-        self.agg_cls = aggregator_class
+        self,
+        agg_class: type[Aggregator],
+        type_substitutions: Optional[Sequence[dict]],
+        self_path: str,
+        requires_order_by: bool,
+        allows_std_agg: bool,
+        allows_window: bool
+    ) -> None:
+        if type_substitutions is None:
+            type_substitutions = [None]  # single signature with no substitutions
+            self.agg_classes = [agg_class]
+        else:
+            self.agg_classes = [agg_class] * len(type_substitutions)
+        self.init_param_names = []
         self.requires_order_by = requires_order_by
         self.allows_std_agg = allows_std_agg
         self.allows_window = allows_window
-        self.__doc__ = aggregator_class.__doc__
+        self.__doc__ = agg_class.__doc__
+
+        signatures: list[Signature] = []
+
+        # If no type_substitutions were provided, construct a single signature for the class.
+        # Otherwise, construct one signature for each type substitution instance.
+        for subst in type_substitutions:
+            signature, init_param_names = self.__cls_to_signature(agg_class, subst)
+            signatures.append(signature)
+            self.init_param_names.append(init_param_names)
+
+        super().__init__(signatures, self_path=self_path)
+
+    def _update_as_overload_resolution(self, signature_idx: int) -> None:
+        self.agg_classes = [self.agg_classes[signature_idx]]
+        self.init_param_names = [self.init_param_names[signature_idx]]
+
+    def __cls_to_signature(
+        self, cls: type[Aggregator], type_substitutions: Optional[dict] = None
+    ) -> tuple[Signature, list[str]]:
+        """Inspects the Aggregator class to infer the corresponding function signature. Returns the
+        inferred signature along with the list of init_param_names (for downstream error handling).
+        """
+        # infer type parameters; set return_type=InvalidType() because it has no meaning here
+        init_sig = Signature.create(py_fn=cls.__init__, return_type=ts.InvalidType(), is_cls_method=True, type_substitutions=type_substitutions)
+        update_sig = Signature.create(py_fn=cls.update, return_type=ts.InvalidType(), is_cls_method=True, type_substitutions=type_substitutions)
+        value_sig = Signature.create(py_fn=cls.value, is_cls_method=True, type_substitutions=type_substitutions)
+
+        init_types = [p.col_type for p in init_sig.parameters.values()]
+        update_types = [p.col_type for p in update_sig.parameters.values()]
+        value_type = value_sig.return_type
+        assert value_type is not None
+
+        if len(update_types) == 0:
+            raise excs.Error('update() must have at least one parameter')
 
         # our signature is the signature of 'update', but without self,
         # plus the parameters of 'init' as keyword-only parameters
-        py_update_params = list(inspect.signature(self.agg_cls.update).parameters.values())[1:]  # leave out self
+        py_update_params = list(inspect.signature(cls.update).parameters.values())[1:]  # leave out self
         assert len(py_update_params) == len(update_types)
         update_params = [
             Parameter(p.name, col_type=update_types[i], kind=p.kind, default=p.default)
             for i, p in enumerate(py_update_params)
         ]
         # starting at 1: leave out self
-        py_init_params = list(inspect.signature(self.agg_cls.__init__).parameters.values())[1:]
+        py_init_params = list(inspect.signature(cls.__init__).parameters.values())[1:]
         assert len(py_init_params) == len(init_types)
         init_params = [
             Parameter(p.name, col_type=init_types[i], kind=inspect.Parameter.KEYWORD_ONLY, default=p.default)
@@ -67,23 +114,36 @@ class AggregateFunction(Function):
                 f'{", ".join(duplicate_params)}'
             )
         params = update_params + init_params  # init_params are keyword-only and come last
+        init_param_names = [p.name for p in init_params]
 
-        signature = Signature(value_type, params)
-        super().__init__(signature, self_path=self_path)
-        self.init_param_names = [p.name for p in init_params]
+        return Signature(value_type, params), init_param_names
 
-        # make sure the signature doesn't contain reserved parameter names;
-        # do this after super().__init__(), otherwise self.name is invalid
-        for param in signature.parameters:
-            if param.lower() in self.RESERVED_PARAMS:
-                raise excs.Error(f'{self.name}(): parameter name {param} is reserved')
+    @property
+    def agg_class(self) -> type[Aggregator]:
+        assert not self.is_polymorphic
+        return self.agg_classes[0]
 
-    def exec(self, *args: Any, **kwargs: Any) -> Any:
+    def exec(self, args: Sequence[Any], kwargs: dict[str, Any]) -> Any:
         raise NotImplementedError
 
+    def overload(self, cls: type[Aggregator]) -> AggregateFunction:
+        if not isinstance(cls, type) or not issubclass(cls, Aggregator):
+            raise excs.Error(f'Invalid argument to @overload decorator: {cls}')
+        if self._has_resolved_fns:
+            raise excs.Error('New `overload` not allowed after the UDF has already been called')
+        if self._conditional_return_type is not None:
+            raise excs.Error('New `overload` not allowed after a conditional return type has been specified')
+        sig, init_param_names = self.__cls_to_signature(cls)
+        self.signatures.append(sig)
+        self.agg_classes.append(cls)
+        self.init_param_names.append(init_param_names)
+        return self
+
     def help_str(self) -> str:
         res = super().help_str()
-        res += '\n\n' + inspect.getdoc(self.agg_cls.update)
+        # We need to reference agg_classes[0] rather than agg_class here, because we want this to work even if the
+        # aggregator is polymorphic (in which case we use the docstring of the originally decorated UDA).
+        res += '\n\n' + inspect.getdoc(self.agg_classes[0].update)
         return res
 
     def __call__(self, *args: object, **kwargs: object) -> 'pixeltable.exprs.FunctionCall':
@@ -121,18 +181,24 @@ class AggregateFunction(Function):
                     f'{self.display_name}(): group_by invalid with an aggregate function that does not allow windows')
             group_by_clause = kwargs.pop(self.GROUP_BY_PARAM)
 
-        bound_args = self.signature.py_signature.bind(*args, **kwargs)
-        self.validate_call(bound_args.arguments)
+        resolved_fn, bound_args = self._bind_to_matching_signature(args, kwargs)
+        return_type = resolved_fn.call_return_type(args, kwargs)
         return exprs.FunctionCall(
-            self, bound_args.arguments,
+            resolved_fn,
+            bound_args,
+            return_type,
             order_by_clause=[order_by_clause] if order_by_clause is not None else [],
-            group_by_clause=[group_by_clause] if group_by_clause is not None else [])
+            group_by_clause=[group_by_clause] if group_by_clause is not None else []
+        )
 
     def validate_call(self, bound_args: dict[str, Any]) -> None:
         # check that init parameters are not Exprs
         # TODO: do this in the planner (check that init parameters are either constants or only refer to grouping exprs)
-        import pixeltable.exprs as exprs
-        for param_name in self.init_param_names:
+        from pixeltable import exprs
+
+        assert not self.is_polymorphic
+
+        for param_name in self.init_param_names[0]:
             if param_name in bound_args and isinstance(bound_args[param_name], exprs.Expr):
                 raise excs.Error(
                     f'{self.display_name}(): init() parameter {param_name} needs to be a constant, not a Pixeltable '
@@ -143,13 +209,23 @@ class AggregateFunction(Function):
         return f'<Pixeltable Aggregator {self.name}>'
 
 
+# Decorator invoked without parentheses: @pxt.uda
+@overload
+def uda(decorated_fn: Callable) -> AggregateFunction: ...
+
+
+# Decorator schema invoked with parentheses: @pxt.uda(**kwargs)
+@overload
 def uda(
-        *,
-        value_type: ts.ColumnType,
-        update_types: list[ts.ColumnType],
-        init_types: Optional[list[ts.ColumnType]] = None,
-        requires_order_by: bool = False, allows_std_agg: bool = True, allows_window: bool = False,
-) -> Callable[[type[Aggregator]], AggregateFunction]:
+    *,
+    requires_order_by: bool = False,
+    allows_std_agg: bool = True,
+    allows_window: bool = False,
+    type_substitutions: Optional[Sequence[dict]] = None
+) -> Callable[[type[Aggregator]], AggregateFunction]: ...
+
+
+def uda(*args, **kwargs):
     """Decorator for user-defined aggregate functions.
 
     The decorated class must inherit from Aggregator and implement the following methods:
@@ -161,46 +237,50 @@ def uda(
     to the module where the class is defined.
 
     Parameters:
-    - init_types: list of types for the __init__() parameters; must match the number of parameters
-    - update_types: list of types for the update() parameters; must match the number of parameters
-    - value_type: return type of the aggregator
     - requires_order_by: if True, the first parameter to the function is the order-by expression
     - allows_std_agg: if True, the function can be used as a standard aggregate function w/o a window
     - allows_window: if True, the function can be used with a window
     """
-    if init_types is None:
-        init_types = []
-
-    def decorator(cls: type[Aggregator]) -> AggregateFunction:
-        # validate type parameters
-        num_init_params = len(inspect.signature(cls.__init__).parameters) - 1
-        if num_init_params > 0:
-            if len(init_types) != num_init_params:
-                raise excs.Error(
-                    f'init_types must be a list of {num_init_params} types, one for each parameter of __init__()')
-        num_update_params = len(inspect.signature(cls.update).parameters) - 1
-        if num_update_params == 0:
-            raise excs.Error('update() must have at least one parameter')
-        if len(update_types) != num_update_params:
-            raise excs.Error(
-                f'update_types must be a list of {num_update_params} types, one for each parameter of update()')
-        assert value_type is not None
-
-        # the AggregateFunction instance resides in the same module as cls
-        class_path = f'{cls.__module__}.{cls.__qualname__}'
-        # nonlocal name
-        # name = name or cls.__name__
-        # instance_path_elements = class_path.split('.')[:-1] + [name]
-        # instance_path = '.'.join(instance_path_elements)
-
-        # create the corresponding AggregateFunction instance
-        instance = AggregateFunction(
-            cls, class_path, init_types, update_types, value_type, requires_order_by, allows_std_agg, allows_window)
-        # do the path validation at the very end, in order to be able to write tests for the other failure cases
-        validate_symbol_path(class_path)
-        #module = importlib.import_module(cls.__module__)
-        #setattr(module, name, instance)
-
-        return instance
+    if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):
+
+        # Decorator invoked without parentheses: @pxt.uda
+        # Simply call make_aggregator with defaults.
+        return make_aggregator(cls=args[0])
+
+    else:
+
+        # Decorator schema invoked with parentheses: @pxt.uda(**kwargs)
+        # Create a decorator for the specified schema.
+        requires_order_by = kwargs.pop('requires_order_by', False)
+        allows_std_agg = kwargs.pop('allows_std_agg', True)
+        allows_window = kwargs.pop('allows_window', False)
+        type_substitutions = kwargs.pop('type_substitutions', None)
+        if len(kwargs) > 0:
+            raise excs.Error(f'Invalid @uda decorator kwargs: {", ".join(kwargs.keys())}')
+        if len(args) > 0:
+            raise excs.Error('Unexpected @uda decorator arguments.')
+
+        def decorator(cls: type[Aggregator]) -> AggregateFunction:
+            return make_aggregator(
+                cls,
+                requires_order_by=requires_order_by,
+                allows_std_agg=allows_std_agg,
+                allows_window=allows_window,
+                type_substitutions=type_substitutions
+            )
 
-    return decorator
+        return decorator
+
+
+def make_aggregator(
+    cls: type[Aggregator],
+    requires_order_by: bool = False,
+    allows_std_agg: bool = True,
+    allows_window: bool = False,
+    type_substitutions: Optional[Sequence[dict]] = None
+) -> AggregateFunction:
+    class_path = f'{cls.__module__}.{cls.__qualname__}'
+    instance = AggregateFunction(cls, type_substitutions, class_path, requires_order_by, allows_std_agg, allows_window)
+    # do the path validation at the very end, in order to be able to write tests for the other failure cases
+    validate_symbol_path(class_path)
+    return instance