1224 Make Cast more flexible (#1225)

* wip

* revert some changes

* add type annotation back for table

* improve docstring and types

* remove `table` param docs

Author: dantownsend

piccolo/custom_types.py

@@ -1,8 +1,13 @@
 from __future__ import annotations
 
+import datetime
+import decimal
+import uuid
 from collections.abc import Iterable
 from typing import TYPE_CHECKING, Any, TypeVar, Union
 
+from typing_extensions import TypeAlias
+
 if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns.combination import And, Or, Where, WhereRaw  # noqa
     from piccolo.table import Table
@@ -16,6 +21,22 @@
 QueryResponseType = TypeVar("QueryResponseType", bound=Any)
 
 
+# These are types we can reasonably expect to send to the database.
+BasicTypes: TypeAlias = Union[
+    bytes,
+    datetime.date,
+    datetime.datetime,
+    datetime.time,
+    datetime.timedelta,
+    decimal.Decimal,
+    dict,
+    float,
+    int,
+    list,
+    str,
+    uuid.UUID,
+]
+
 ###############################################################################
 # For backwards compatibility:
 

piccolo/query/functions/type_conversion.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 from typing import Optional, Union
 
 from piccolo.columns.base import Column
+from piccolo.custom_types import BasicTypes
 from piccolo.querystring import QueryString
 
 
 class Cast(QueryString):
     def __init__(
         self,
-        identifier: Union[Column, QueryString],
+        identifier: Union[Column, QueryString, BasicTypes],
         as_type: Column,
         alias: Optional[str] = None,
     ):
@@ -17,25 +20,36 @@ def __init__(
             >>> from piccolo.query.functions import Cast
 
             >>> await Concert.select(
-            ...     Cast(Concert.starts, Time(), "start_time")
+            ...     Cast(Concert.starts, Time(), alias="start_time")
             ... )
             [{"start_time": datetime.time(19, 0)}]
 
+        You may also need ``Cast`` to explicitly tell the database which type
+        you're sending in the query (though this is an edge case). Here is a
+        contrived example::
+
+            >>> from piccolo.query.functions.math import Count
+
+            # This fails with asyncpg:
+            >>> await Band.select(Count([1,2,3]))
+
+        If we explicitly specify the type of the array, then it works::
+
+            >>> await Band.select(
+            ...     Count(
+            ...         Cast(
+            ...             [1,2,3],
+            ...             Array(Integer())
+            ...         ),
+            ...     )
+            ... )
+
         :param identifier:
-            Identifies what is being converted (e.g. a column).
+            Identifies what is being converted (e.g. a column, or a raw value).
         :param as_type:
             The type to be converted to.
 
         """
-        # Make sure the identifier is a supported type.
-
-        if not isinstance(identifier, (Column, QueryString)):
-            raise ValueError(
-                "The identifier is an unsupported type - only Column and "
-                "QueryString instances are allowed."
-            )
-
-        #######################################################################
         # Convert `as_type` to a string which can be used in the query.
 
         if not isinstance(as_type, Column):
@@ -44,6 +58,7 @@ def __init__(
         # We need to give the column a reference to a table, and hence
         # the database engine, as the column type is sometimes dependent
         # on which database is being used.
+
         from piccolo.table import Table, create_table_class
 
         table: Optional[type[Table]] = None