singlestoredb 1.15.0__cp38-abi3-win_amd64.whl → 1.15.2__cp38-abi3-win_amd64.whl

singlestoredb/functions/signature.py

@@ -16,7 +16,6 @@ from typing import List
 from typing import Optional
 from typing import Sequence
 from typing import Tuple
-from typing import Type
 from typing import TypeVar
 from typing import Union
 
@@ -188,6 +187,27 @@ sql_to_type_map = {
 }
 
 
+@dataclasses.dataclass
+class ParamSpec:
+    # Normalized data type of the parameter
+    dtype: Any
+
+    # Name of the parameter, if applicable
+    name: str = ''
+
+    # SQL type of the parameter
+    sql_type: str = ''
+
+    # Default value of the parameter, if applicable
+    default: Any = NO_DEFAULT
+
+    # Transformer function to apply to the parameter
+    transformer: Optional[Callable[..., Any]] = None
+
+    # Whether the parameter is optional (e.g., Union[T, None] or Optional[T])
+    is_optional: bool = False
+
+
 class Collection:
     """Base class for collection data types."""
 
@@ -519,10 +539,7 @@ def collapse_dtypes(dtypes: Union[str, List[str]], include_null: bool = False) -
     return dtypes[0] + ('?' if is_nullable else '')
 
 
-def get_dataclass_schema(
-    obj: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[str, Any], Tuple[str, Any, Any]]]:
+def get_dataclass_schema(obj: Any) -> List[ParamSpec]:
     """
     Get the schema of a dataclass.
 
@@ -533,25 +550,21 @@ def get_dataclass_schema(
 
     Returns
     -------
-    List[Tuple[str, Any]] | List[Tuple[str, Any, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the dataclass fields
 
     """
-    if include_default:
-        return [
-            (
-                f.name, f.type,
-                NO_DEFAULT if f.default is dataclasses.MISSING else f.default,
-            )
-            for f in dataclasses.fields(obj)
-        ]
-    return [(f.name, f.type) for f in dataclasses.fields(obj)]
+    return [
+        ParamSpec(
+            name=f.name,
+            dtype=f.type,
+            default=NO_DEFAULT if f.default is dataclasses.MISSING else f.default,
+        )
+        for f in dataclasses.fields(obj)
+    ]
 
 
-def get_typeddict_schema(
-    obj: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[str, Any], Tuple[str, Any, Any]]]:
+def get_typeddict_schema(obj: Any) -> List[ParamSpec]:
     """
     Get the schema of a TypedDict.
 
@@ -559,27 +572,24 @@ def get_typeddict_schema(
     ----------
     obj : TypedDict
         The TypedDict to get the schema of
-    include_default : bool, optional
-        Whether to include the default value in the column specification
 
     Returns
     -------
-    List[Tuple[str, Any]] | List[Tuple[str, Any, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the TypedDict fields
 
     """
-    if include_default:
-        return [
-            (k, v, getattr(obj, k, NO_DEFAULT))
-            for k, v in utils.get_annotations(obj).items()
-        ]
-    return list(utils.get_annotations(obj).items())
+    return [
+        ParamSpec(
+            name=k,
+            dtype=v,
+            default=getattr(obj, k, NO_DEFAULT),
+        )
+        for k, v in utils.get_annotations(obj).items()
+    ]
 
 
-def get_pydantic_schema(
-    obj: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[str, Any], Tuple[str, Any, Any]]]:
+def get_pydantic_schema(obj: Any) -> List[ParamSpec]:
     """
     Get the schema of a pydantic model.
 
@@ -587,31 +597,26 @@ def get_pydantic_schema(
     ----------
     obj : pydantic.BaseModel
         The pydantic model to get the schema of
-    include_default : bool, optional
-        Whether to include the default value in the column specification
 
     Returns
     -------
-    List[Tuple[str, Any]] | List[Tuple[str, Any, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the pydantic model fields
 
     """
     import pydantic_core
-    if include_default:
-        return [
-            (
-                k, v.annotation,
-                NO_DEFAULT if v.default is pydantic_core.PydanticUndefined else v.default,
-            )
-            for k, v in obj.model_fields.items()
-        ]
-    return [(k, v.annotation) for k, v in obj.model_fields.items()]
+    return [
+        ParamSpec(
+            name=k,
+            dtype=v.annotation,
+            default=NO_DEFAULT
+            if v.default is pydantic_core.PydanticUndefined else v.default,
+        )
+        for k, v in obj.model_fields.items()
+    ]
 
 
-def get_namedtuple_schema(
-    obj: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[Any, str], Tuple[Any, str, Any]]]:
+def get_namedtuple_schema(obj: Any) -> List[ParamSpec]:
     """
     Get the schema of a named tuple.
 
@@ -619,30 +624,26 @@ def get_namedtuple_schema(
     ----------
     obj : NamedTuple
         The named tuple to get the schema of
-    include_default : bool, optional
-        Whether to include the default value in the column specification
 
     Returns
     -------
-    List[Tuple[Any, str]] | List[Tuple[Any, str, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the named tuple fields
 
     """
-    if include_default:
-        return [
-            (
-                k, v,
-                obj._field_defaults.get(k, NO_DEFAULT),
+    return [
+        (
+            ParamSpec(
+                name=k,
+                dtype=v,
+                default=obj._field_defaults.get(k, NO_DEFAULT),
             )
-            for k, v in utils.get_annotations(obj).items()
-        ]
-    return list(utils.get_annotations(obj).items())
+        )
+        for k, v in utils.get_annotations(obj).items()
+    ]
 
 
-def get_table_schema(
-    obj: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[Any, str], Tuple[Any, str, Any]]]:
+def get_table_schema(obj: Any) -> List[ParamSpec]:
     """
     Get the schema of a Table.
 
@@ -650,90 +651,66 @@ def get_table_schema(
     ----------
     obj : Table
         The Table to get the schema of
-    include_default : bool, optional
-        Whether to include the default value in the column specification
 
     Returns
     -------
-    List[Tuple[Any, str]] | List[Tuple[Any, str, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the Table fields
 
     """
-    if include_default:
-        return [
-            (k, v, getattr(obj, k, NO_DEFAULT))
-            for k, v in utils.get_annotations(obj).items()
-        ]
-    return list(utils.get_annotations(obj).items())
+    return [
+        ParamSpec(
+            name=k,
+            dtype=v,
+            default=getattr(obj, k, NO_DEFAULT),
+        )
+        for k, v in utils.get_annotations(obj).items()
+    ]
 
 
-def get_colspec(
-    overrides: Any,
-    include_default: bool = False,
-) -> List[Union[Tuple[str, Any], Tuple[str, Any, Any]]]:
+def get_colspec(overrides: List[Any]) -> List[ParamSpec]:
     """
     Get the column specification from the overrides.
 
     Parameters
     ----------
-    overrides : Any
+    overrides : List[Any]
         The overrides to get the column specification from
-    include_default : bool, optional
-        Whether to include the default value in the column specification
 
     Returns
     -------
-    List[Tuple[str, Any]] | List[Tuple[str, Any, Any]]
-        A list of tuples containing the field names and field types
+    List[ParamSpec]
+        A list of parameter specifications for the column fields
 
     """
-    overrides_colspec = []
+    if len(overrides) == 1:
 
-    if overrides:
+        override = overrides[0]
 
         # Dataclass
-        if utils.is_dataclass(overrides):
-            overrides_colspec = get_dataclass_schema(
-                overrides, include_default=include_default,
-            )
+        if utils.is_dataclass(override):
+            return get_dataclass_schema(override)
 
         # TypedDict
-        elif utils.is_typeddict(overrides):
-            overrides_colspec = get_typeddict_schema(
-                overrides, include_default=include_default,
-            )
+        elif utils.is_typeddict(override):
+            return get_typeddict_schema(override)
 
         # Named tuple
-        elif utils.is_namedtuple(overrides):
-            overrides_colspec = get_namedtuple_schema(
-                overrides, include_default=include_default,
-            )
+        elif utils.is_namedtuple(override):
+            return get_namedtuple_schema(override)
 
         # Pydantic model
-        elif utils.is_pydantic(overrides):
-            overrides_colspec = get_pydantic_schema(
-                overrides, include_default=include_default,
-            )
-
-        # List of types
-        elif isinstance(overrides, list):
-            if include_default:
-                overrides_colspec = [
-                    (getattr(x, 'name', ''), x, NO_DEFAULT) for x in overrides
-                ]
-            else:
-                overrides_colspec = [(getattr(x, 'name', ''), x) for x in overrides]
-
-        # Other
-        else:
-            if include_default:
-                overrides_colspec = [
-                    (getattr(overrides, 'name', ''), overrides, NO_DEFAULT),
-                ]
-            else:
-                overrides_colspec = [(getattr(overrides, 'name', ''), overrides)]
+        elif utils.is_pydantic(override):
+            return get_pydantic_schema(override)
 
-    return overrides_colspec
+    # List of types
+    return [
+        ParamSpec(
+            name=getattr(x, 'name', ''),
+            dtype=sql_to_dtype(x) if isinstance(x, str) else x,
+            sql_type=x if isinstance(x, str) else '',
+        ) for x in overrides
+    ]
 
 
 def unpack_masked_type(obj: Any) -> Any:
@@ -756,11 +733,121 @@ def unpack_masked_type(obj: Any) -> Any:
     return obj
 
 
+def unwrap_optional(annotation: Any) -> Tuple[Any, bool]:
+    """
+    Unwrap Optional[T] and Union[T, None] annotations to get the underlying type.
+    Also indicates whether the type was optional.
+
+    Examples:
+        Optional[int] -> (int, True)
+        Union[str, None] -> (str, True)
+        Union[int, str, None] -> (Union[int, str], True)
+        Union[int, str] -> (Union[int, str], False)
+        int -> (int, False)
+
+    Parameters
+    ----------
+    annotation : Any
+        The type annotation to unwrap
+
+    Returns
+    -------
+    Tuple[Any, bool]
+        A tuple containing:
+        - The unwrapped type annotation
+        - A boolean indicating if the original type was optional (contained None)
+
+    """
+    origin = typing.get_origin(annotation)
+    is_optional = False
+
+    # Handle Union types (which includes Optional)
+    if origin is Union:
+        args = typing.get_args(annotation)
+        # Check if None is in the union
+        is_optional = type(None) in args
+
+        # Filter out None/NoneType
+        non_none_args = [arg for arg in args if arg is not type(None)]
+
+        if not non_none_args:
+            # If only None was in the Union
+            from typing import Any
+            return Any, is_optional
+        elif len(non_none_args) == 1:
+            # If there's only one type left, return it directly
+            return non_none_args[0], is_optional
+        else:
+            # Recreate the Union with the remaining types
+            return Union[tuple(non_none_args)], is_optional
+
+    return annotation, is_optional
+
+
+def is_composite_type(spec: Any) -> bool:
+    """
+    Check if the object is a composite type (e.g., dataclass, TypedDict, etc.).
+
+    Parameters
+    ----------
+    spec : Any
+        The object to check
+
+    Returns
+    -------
+    bool
+        True if the object is a composite type, False otherwise
+
+    """
+    return inspect.isclass(spec) and \
+        (
+            utils.is_dataframe(spec)
+            or utils.is_dataclass(spec)
+            or utils.is_typeddict(spec)
+            or utils.is_pydantic(spec)
+            or utils.is_namedtuple(spec)
+        )
+
+
+def check_composite_type(colspec: List[ParamSpec], mode: str, type_name: str) -> bool:
+    """
+    Check if the column specification is a composite type.
+
+    Parameters
+    ----------
+    colspec : List[ParamSpec]
+        The column specification to check
+    mode : str
+        The mode of the function, either 'parameter' or 'return'
+    type_name : str
+        The name of the parent type
+
+    Returns
+    -------
+    bool
+        Verify the composite type is valid for the given mode
+
+    """
+    if mode == 'parameter':
+        if is_composite_type(colspec[0].dtype):
+            raise TypeError(
+                'composite types are not allowed in a '
+                f'{type_name}: {colspec[0].dtype.__name__}',
+            )
+    elif mode == 'return':
+        if is_composite_type(colspec[0].dtype):
+            raise TypeError(
+                'composite types are not allowed in a '
+                f'{type_name}: {colspec[0].dtype.__name__}',
+            )
+    return False
+
+
 def get_schema(
     spec: Any,
-    overrides: Optional[Union[List[str], Type[Any]]] = None,
+    overrides: Optional[List[ParamSpec]] = None,
     mode: str = 'parameter',
-) -> Tuple[List[Tuple[str, Any, Optional[str]]], str, str]:
+) -> Tuple[List[ParamSpec], str, str]:
     """
     Expand a return type annotation into a list of types and field names.
 
@@ -768,23 +855,24 @@ def get_schema(
     ----------
     spec : Any
         The return type specification
-    overrides : List[str], optional
+    overrides : List[ParamSpec], optional
         List of SQL type specifications for the return type
     mode : str
         The mode of the function, either 'parameter' or 'return'
 
     Returns
     -------
-    Tuple[List[Tuple[str, Any, Optional[str]]], str, str]
-        A list of tuples containing the field names and field types,
-        the normalized data format, optionally the SQL
-        definition of the type, and the data format of the type
+    Tuple[List[ParamSpec], str, str]
+        A list of parameter specifications for the function,
+        the normalized data format, and the SQL definition of the type
 
     """
     colspec = []
     data_format = ''
     function_type = 'udf'
+    udf_parameter = '`returns=`' if mode == 'return' else '`args=`'
 
+    spec, is_optional = unwrap_optional(spec)
     origin = typing.get_origin(spec)
     args = typing.get_args(spec)
     args_origins = [typing.get_origin(x) if x is not None else None for x in args]
@@ -833,113 +921,104 @@ def get_schema(
                 )
 
         # Short circuit check for common valid types
-        elif utils.is_vector(spec) or spec in [str, float, int, bytes]:
+        elif utils.is_vector(spec) or spec in {str, float, int, bytes}:
             pass
 
         # Try to catch some common mistakes
-        elif origin in [tuple, dict] or tuple in args_origins or \
-                (
-                    inspect.isclass(spec) and
-                    (
-                        utils.is_dataframe(spec)
-                        or utils.is_dataclass(spec)
-                        or utils.is_typeddict(spec)
-                        or utils.is_pydantic(spec)
-                        or utils.is_namedtuple(spec)
-                    )
-                ):
+        elif origin in [tuple, dict] or tuple in args_origins or is_composite_type(spec):
             raise TypeError(
-                'invalid return type for a UDF; '
-                f'expecting a scalar or vector, but got {spec}',
+                'invalid return type for a UDF; expecting a scalar or vector, '
+                f'but got {getattr(spec, "__name__", spec)}',
             )
 
     # Short circuit check for common valid types
-    elif utils.is_vector(spec) or spec in [str, float, int, bytes]:
+    elif utils.is_vector(spec) or spec in {str, float, int, bytes}:
         pass
 
     # Error out for incorrect parameter types
-    elif origin in [tuple, dict] or tuple in args_origins or \
-            (
-                inspect.isclass(spec) and
-                (
-                    utils.is_dataframe(spec)
-                    or utils.is_dataclass(spec)
-                    or utils.is_typeddict(spec)
-                    or utils.is_pydantic(spec)
-                    or utils.is_namedtuple(spec)
-                )
-            ):
-        raise TypeError(f'parameter types must be scalar or vector, got {spec}')
+    elif origin in [tuple, dict] or tuple in args_origins or is_composite_type(spec):
+        raise TypeError(
+            'parameter types must be scalar or vector, '
+            f'got {getattr(spec, "__name__", spec)}',
+        )
 
     #
     # Process each parameter / return type into a colspec
     #
 
-    # Compute overrides colspec from various formats
-    overrides_colspec = get_colspec(overrides)
-
     # Dataframe type
     if utils.is_dataframe(spec):
-        colspec = overrides_colspec
+        if not overrides:
+            raise TypeError(
+                'column types must be specified in the '
+                f'{udf_parameter} parameter of the @udf decorator for a DataFrame',
+            )
+        # colspec = get_colspec(overrides[0].dtype)
+        colspec = overrides
 
     # Numpy array types
     elif utils.is_numpy(spec):
         data_format = 'numpy'
         if overrides:
-            colspec = overrides_colspec
+            colspec = overrides
         elif len(typing.get_args(spec)) < 2:
             raise TypeError(
-                'numpy array must have a data type specified '
-                'in the @udf decorator or with an NDArray type annotation',
+                'numpy array must have an element data type specified '
+                f'in the {udf_parameter} parameter of the @udf decorator '
+                'or with an NDArray type annotation',
             )
         else:
-            colspec = [('', typing.get_args(spec)[1])]
+            colspec = [ParamSpec(dtype=typing.get_args(spec)[1])]
+        check_composite_type(colspec, mode, 'numpy array')
 
     # Pandas Series
     elif utils.is_pandas_series(spec):
         data_format = 'pandas'
         if not overrides:
             raise TypeError(
-                'pandas Series must have a data type specified '
-                'in the @udf decorator',
+                'pandas Series must have an element data type specified '
+                f'in the {udf_parameter} parameter of the @udf decorator',
             )
-        colspec = overrides_colspec
+        colspec = overrides
+        check_composite_type(colspec, mode, 'pandas Series')
 
     # Polars Series
     elif utils.is_polars_series(spec):
         data_format = 'polars'
         if not overrides:
             raise TypeError(
-                'polars Series must have a data type specified '
-                'in the @udf decorator',
+                'polars Series must have an element data type specified '
+                f'in the {udf_parameter} parameter of the @udf decorator',
             )
-        colspec = overrides_colspec
+        colspec = overrides
+        check_composite_type(colspec, mode, 'polars Series')
 
     # PyArrow Array
     elif utils.is_pyarrow_array(spec):
         data_format = 'arrow'
         if not overrides:
             raise TypeError(
-                'pyarrow Arrays must have a data type specified '
-                'in the @udf decorator',
+                'pyarrow Arrays must have an element data type specified '
+                f'in the {udf_parameter} parameter of the @udf decorator',
             )
-        colspec = overrides_colspec
+        colspec = overrides
+        check_composite_type(colspec, mode, 'pyarrow Array')
 
     # Return type is specified by a dataclass definition
     elif utils.is_dataclass(spec):
-        colspec = overrides_colspec or get_dataclass_schema(spec)
+        colspec = overrides or get_dataclass_schema(spec)
 
     # Return type is specified by a TypedDict definition
     elif utils.is_typeddict(spec):
-        colspec = overrides_colspec or get_typeddict_schema(spec)
+        colspec = overrides or get_typeddict_schema(spec)
 
     # Return type is specified by a pydantic model
     elif utils.is_pydantic(spec):
-        colspec = overrides_colspec or get_pydantic_schema(spec)
+        colspec = overrides or get_pydantic_schema(spec)
 
     # Return type is specified by a named tuple
     elif utils.is_namedtuple(spec):
-        colspec = overrides_colspec or get_namedtuple_schema(spec)
+        colspec = overrides or get_namedtuple_schema(spec)
 
     # Unrecognized return type
     elif spec is not None:
@@ -947,30 +1026,20 @@ def get_schema(
         # Return type is specified by a SQL string
         if isinstance(spec, str):
             data_format = 'scalar'
-            colspec = [(getattr(spec, 'name', ''), spec)]
+            colspec = [ParamSpec(dtype=spec, is_optional=is_optional)]
 
         # Plain list vector
         elif typing.get_origin(spec) is list:
             data_format = 'list'
-            colspec = [('', typing.get_args(spec)[0])]
+            colspec = [ParamSpec(dtype=typing.get_args(spec)[0], is_optional=is_optional)]
 
         # Multiple return values
         elif inspect.isclass(typing.get_origin(spec)) \
                 and issubclass(typing.get_origin(spec), tuple):  # type: ignore[arg-type]
 
-            out_names, out_overrides = [], []
-
-            # Get the colspec for the overrides
-            if overrides:
-                out_colspec = [
-                    x for x in get_colspec(overrides, include_default=True)
-                ]
-                out_names = [x[0] for x in out_colspec]
-                out_overrides = [x[1] for x in out_colspec]
-
             # Make sure that the number of overrides matches the number of
             # return types or parameter types
-            if out_overrides and len(typing.get_args(spec)) != len(out_overrides):
+            if overrides and len(typing.get_args(spec)) != len(overrides):
                 raise ValueError(
                     f'number of {mode} types does not match the number of '
                     'overrides specified',
@@ -981,20 +1050,21 @@ def get_schema(
 
             # Get the colspec for each item in the tuple
             for i, x in enumerate(typing.get_args(spec)):
-                out_item, out_data_format, _ = get_schema(
+                params, out_data_format, _ = get_schema(
                     unpack_masked_type(x),
-                    overrides=out_overrides[i] if out_overrides else [],
+                    overrides=[overrides[i]] if overrides else [],
                     # Always pass UDF mode for individual items
                     mode=mode,
                 )
 
                 # Use the name from the overrides if specified
-                if out_names and out_names[i] and not out_item[0][0]:
-                    out_item = [(out_names[i], *out_item[0][1:])]
-                elif not out_item[0][0]:
-                    out_item = [(f'{string.ascii_letters[i]}', *out_item[0][1:])]
+                if overrides:
+                    if overrides[i] and not params[0].name:
+                        params[0].name = overrides[i].name
+                    elif not overrides[i].name:
+                        params[0].name = f'{string.ascii_letters[i]}'
 
-                colspec += out_item
+                colspec.append(params[0])
                 out_data_formats.append(out_data_format)
 
             # Make sure that all the data formats are the same
@@ -1015,25 +1085,35 @@ def get_schema(
         elif overrides:
             if not data_format:
                 data_format = get_data_format(spec)
-            colspec = overrides_colspec
+            colspec = overrides
 
         # Single value, no override
         else:
             if not data_format:
                 data_format = 'scalar'
-            colspec = [('', spec)]
+            colspec = [ParamSpec(dtype=spec, is_optional=is_optional)]
 
     out = []
 
     # Normalize colspec data types
-    for k, v, *_ in colspec:
-        out.append((
-            k,
-            collapse_dtypes(
-                [normalize_dtype(x) for x in simplify_dtype(v)],
-            ),
-            v if isinstance(v, str) else None,
-        ))
+    for c in colspec:
+
+        if isinstance(c.dtype, str):
+            dtype = c.dtype
+        else:
+            dtype = collapse_dtypes(
+                [normalize_dtype(x) for x in simplify_dtype(c.dtype)],
+                include_null=c.is_optional,
+            )
+
+        p = ParamSpec(
+            name=c.name,
+            dtype=dtype,
+            sql_type=c.sql_type if isinstance(c.sql_type, str) else None,
+            is_optional=c.is_optional,
+        )
+
+        out.append(p)
 
     return out, data_format, function_type
 
@@ -1149,14 +1229,12 @@ def get_signature(
     # TODO: Use typing.get_type_hints() for parameters / return values?
 
     # Generate the parameter type and the corresponding SQL code for that parameter
-    args_schema = []
+    args_schema: List[ParamSpec] = []
     args_data_formats = []
-    args_colspec = [x for x in get_colspec(attrs.get('args', []), include_default=True)]
-    args_overrides = [x[1] for x in args_colspec]
-    args_defaults = [x[2] for x in args_colspec]  # type: ignore
+    args_colspec = [x for x in get_colspec(attrs.get('args', []))]
     args_masks, ret_masks = get_masks(func)
 
-    if args_overrides and len(args_overrides) != len(signature.parameters):
+    if args_colspec and len(args_colspec) != len(signature.parameters):
         raise ValueError(
             'number of args in the decorator does not match '
             'the number of parameters in the function signature',
@@ -1168,33 +1246,49 @@ def get_signature(
     for i, param in enumerate(params):
         arg_schema, args_data_format, _ = get_schema(
             unpack_masked_type(param.annotation),
-            overrides=args_overrides[i] if args_overrides else [],
+            overrides=[args_colspec[i]] if args_colspec else [],
             mode='parameter',
         )
         args_data_formats.append(args_data_format)
 
+        if len(arg_schema) > 1:
+            raise TypeError(
+                'only one parameter type is supported; '
+                f'got {len(arg_schema)} types for parameter {param.name}',
+            )
+
         # Insert parameter names as needed
-        if not arg_schema[0][0]:
-            args_schema.append((param.name, *arg_schema[0][1:]))
+        if not arg_schema[0].name:
+            arg_schema[0].name = param.name
 
-    for i, (name, atype, sql) in enumerate(args_schema):
+        args_schema.append(arg_schema[0])
+
+    for i, pspec in enumerate(args_schema):
         default_option = {}
 
         # Insert default values as needed
-        if args_defaults:
-            if args_defaults[i] is not NO_DEFAULT:
-                default_option['default'] = args_defaults[i]
-        else:
-            if params[i].default is not param.empty:
-                default_option['default'] = params[i].default
+        if args_colspec and args_colspec[i].default is not NO_DEFAULT:
+            default_option['default'] = args_colspec[i].default
+        elif params and params[i].default is not param.empty:
+            default_option['default'] = params[i].default
 
         # Generate SQL code for the parameter
-        sql = sql or dtype_to_sql(
-            atype, force_nullable=args_masks[i], **default_option,
+        sql = pspec.sql_type or dtype_to_sql(
+            pspec.dtype,
+            force_nullable=args_masks[i] or pspec.is_optional,
+            **default_option,
         )
 
         # Add parameter to args definitions
-        args.append(dict(name=name, dtype=atype, sql=sql, **default_option))
+        args.append(
+            dict(
+                name=pspec.name,
+                dtype=pspec.dtype,
+                sql=sql,
+                **default_option,
+                transformer=pspec.transformer,
+            ),
+        )
 
     # Check that all the data formats are all the same
     if len(set(args_data_formats)) > 1:
@@ -1203,37 +1297,73 @@ def get_signature(
             f'{", ".join(args_data_formats)}',
         )
 
-    out['args_data_format'] = args_data_formats[0] if args_data_formats else 'scalar'
+    adf = out['args_data_format'] = args_data_formats[0] \
+        if args_data_formats else 'scalar'
+
+    returns_colspec = get_colspec(attrs.get('returns', []))
 
     # Generate the return types and the corresponding SQL code for those values
     ret_schema, out['returns_data_format'], function_type = get_schema(
         unpack_masked_type(signature.return_annotation),
-        overrides=attrs.get('returns', None),
+        overrides=returns_colspec if returns_colspec else None,
         mode='return',
     )
 
-    out['returns_data_format'] = out['returns_data_format'] or 'scalar'
+    rdf = out['returns_data_format'] = out['returns_data_format'] or 'scalar'
     out['function_type'] = function_type
 
+    # Reality check the input and output data formats
+    if function_type == 'udf':
+        if (adf == 'scalar' and rdf != 'scalar') or \
+           (adf != 'scalar' and rdf == 'scalar'):
+            raise TypeError(
+                'Function can not have scalar arguments and a vector return type, '
+                'or vice versa. Parameters and return values must all be either ',
+                'scalar or vector types.',
+            )
+
     # All functions have to return a value, so if none was specified try to
     # insert a reasonable default that includes NULLs.
     if not ret_schema:
-        ret_schema = [('', 'int8?', 'TINYINT NULL')]
+        ret_schema = [
+            ParamSpec(
+                dtype='int8?', sql_type='TINYINT NULL', default=None, is_optional=True,
+            ),
+        ]
+
+    if function_type == 'udf' and len(ret_schema) > 1:
+        raise ValueError(
+            'UDFs can only return a single value; '
+            f'got {len(ret_schema)} return values',
+        )
 
     # Generate field names for the return values
     if function_type == 'tvf' or len(ret_schema) > 1:
-        for i, (name, rtype, sql) in enumerate(ret_schema):
-            if not name:
-                ret_schema[i] = (string.ascii_letters[i], rtype, sql)
+        for i, rspec in enumerate(ret_schema):
+            if not rspec.name:
+                ret_schema[i] = ParamSpec(
+                    name=string.ascii_letters[i],
+                    dtype=rspec.dtype,
+                    sql_type=rspec.sql_type,
+                    transformer=rspec.transformer,
+                )
 
     # Generate SQL code for the return values
-    for i, (name, rtype, sql) in enumerate(ret_schema):
-        sql = sql or dtype_to_sql(
-            rtype,
-            force_nullable=ret_masks[i] if ret_masks else False,
+    for i, rspec in enumerate(ret_schema):
+        sql = rspec.sql_type or dtype_to_sql(
+            rspec.dtype,
+            force_nullable=(ret_masks[i] or rspec.is_optional)
+            if ret_masks else rspec.is_optional,
             function_type=function_type,
         )
-        returns.append(dict(name=name, dtype=rtype, sql=sql))
+        returns.append(
+            dict(
+                name=rspec.name,
+                dtype=rspec.dtype,
+                sql=sql,
+                transformer=rspec.transformer,
+            ),
+        )
 
     # Set the function endpoint
     out['endpoint'] = '/invoke'
@@ -1370,6 +1500,7 @@ def signature_to_sql(
     app_mode: str = 'remote',
     link: Optional[str] = None,
     replace: bool = False,
+    database: Optional[str] = None,
 ) -> str:
     '''
     Convert a dictionary function signature into SQL.
@@ -1424,9 +1555,11 @@ def signature_to_sql(
     elif url is None:
         raise ValueError('url can not be `None`')
 
-    database = ''
+    database_prefix = ''
     if signature.get('database'):
-        database = escape_name(signature['database']) + '.'
+        database_prefix = escape_name(signature['database']) + '.'
+    elif database is not None:
+        database_prefix = escape_name(database) + '.'
 
     or_replace = 'OR REPLACE ' if (bool(signature.get('replace')) or replace) else ''
 
@@ -1438,7 +1571,7 @@ def signature_to_sql(
 
     return (
         f'CREATE {or_replace}EXTERNAL FUNCTION ' +
-        f'{database}{escape_name(signature["name"])}' +
+        f'{database_prefix}{escape_name(signature["name"])}' +
         '(' + ', '.join(args) + ')' + returns +
         f' AS {app_mode.upper()} SERVICE "{url}" FORMAT {data_format.upper()}'
         f'{link_str};'