piccolo 1.27.1__py3-none-any.whl → 1.28.0__py3-none-any.whl

piccolo/query/functions/datetime.py

@@ -1,4 +1,4 @@
-import typing as t
+from typing import Literal, Optional, Union, get_args
 
 from piccolo.columns.base import Column
 from piccolo.columns.column_types import (
@@ -15,7 +15,7 @@ from .type_conversion import Cast
 ###############################################################################
 # Postgres / Cockroach
 
-ExtractComponent = t.Literal[
+ExtractComponent = Literal[
     "century",
     "day",
     "decade",
@@ -44,9 +44,9 @@ ExtractComponent = t.Literal[
 class Extract(QueryString):
     def __init__(
         self,
-        identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+        identifier: Union[Date, Time, Timestamp, Timestamptz, QueryString],
         datetime_component: ExtractComponent,
-        alias: t.Optional[str] = None,
+        alias: Optional[str] = None,
     ):
         """
         .. note:: This is for Postgres / Cockroach only.
@@ -69,7 +69,7 @@ class Extract(QueryString):
             The date or time component to extract from the column.
 
         """
-        if datetime_component.lower() not in t.get_args(ExtractComponent):
+        if datetime_component.lower() not in get_args(ExtractComponent):
             raise ValueError("The date time component isn't recognised.")
 
         super().__init__(
@@ -86,9 +86,9 @@ class Extract(QueryString):
 class Strftime(QueryString):
     def __init__(
         self,
-        identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+        identifier: Union[Date, Time, Timestamp, Timestamptz, QueryString],
         datetime_format: str,
-        alias: t.Optional[str] = None,
+        alias: Optional[str] = None,
     ):
         """
         .. note:: This is for SQLite only.
@@ -122,7 +122,7 @@ class Strftime(QueryString):
 # Database agnostic
 
 
-def _get_engine_type(identifier: t.Union[Column, QueryString]) -> str:
+def _get_engine_type(identifier: Union[Column, QueryString]) -> str:
     if isinstance(identifier, Column):
         return identifier._meta.engine_type
     elif isinstance(identifier, QueryString) and (
@@ -134,10 +134,10 @@ def _get_engine_type(identifier: t.Union[Column, QueryString]) -> str:
 
 
 def _extract_component(
-    identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+    identifier: Union[Date, Time, Timestamp, Timestamptz, QueryString],
     sqlite_format: str,
     postgres_format: ExtractComponent,
-    alias: t.Optional[str],
+    alias: Optional[str],
 ) -> QueryString:
     engine_type = _get_engine_type(identifier=identifier)
 
@@ -159,8 +159,8 @@ def _extract_component(
 
 
 def Year(
-    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the year as an integer.
@@ -174,8 +174,8 @@ def Year(
 
 
 def Month(
-    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the month as an integer.
@@ -189,8 +189,8 @@ def Month(
 
 
 def Day(
-    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the day as an integer.
@@ -204,8 +204,8 @@ def Day(
 
 
 def Hour(
-    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the hour as an integer.
@@ -219,8 +219,8 @@ def Hour(
 
 
 def Minute(
-    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the minute as an integer.
@@ -234,8 +234,8 @@ def Minute(
 
 
 def Second(
-    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
-    alias: t.Optional[str] = None,
+    identifier: Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: Optional[str] = None,
 ) -> QueryString:
     """
     Extract the second as an integer.

piccolo/query/functions/string.py

@@ -5,7 +5,7 @@ https://www.postgresql.org/docs/current/functions-string.html
 
 """
 
-import typing as t
+from typing import Optional, Union
 
 from piccolo.columns.base import Column
 from piccolo.columns.column_types import Text, Varchar
@@ -72,8 +72,8 @@ class Upper(Function):
 class Concat(QueryString):
     def __init__(
         self,
-        *args: t.Union[Column, QueryString, str],
-        alias: t.Optional[str] = None,
+        *args: Union[Column, QueryString, str],
+        alias: Optional[str] = None,
     ):
         """
         Concatenate multiple values into a single string.
@@ -91,7 +91,7 @@ class Concat(QueryString):
 
         placeholders = ", ".join("{}" for _ in args)
 
-        processed_args: t.List[t.Union[QueryString, Column]] = []
+        processed_args: list[Union[QueryString, Column]] = []
 
         for arg in args:
             if isinstance(arg, str) or (

piccolo/query/functions/type_conversion.py

@@ -1,15 +1,18 @@
-import typing as t
+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: t.Union[Column, QueryString],
+        identifier: Union[Column, QueryString, BasicTypes],
         as_type: Column,
-        alias: t.Optional[str] = None,
+        alias: Optional[str] = None,
     ):
         """
         Cast a value to a different type. For example::
@@ -17,25 +20,36 @@ class Cast(QueryString):
             >>> 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,9 +58,10 @@ class Cast(QueryString):
         # 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: t.Optional[t.Type[Table]] = None
+        table: Optional[type[Table]] = None
 
         if isinstance(identifier, Column):
             table = identifier._meta.table

piccolo/query/methods/alter.py

@@ -1,15 +1,16 @@
 from __future__ import annotations
 
 import itertools
-import typing as t
+from collections.abc import Sequence
 from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
 
 from piccolo.columns.base import Column
 from piccolo.columns.column_types import ForeignKey, Numeric, Varchar
 from piccolo.query.base import DDL
 from piccolo.utils.warnings import Level, colored_warning
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns.base import OnDelete, OnUpdate
     from piccolo.table import Table
 
@@ -52,7 +53,7 @@ class RenameConstraint(AlterStatement):
 class AlterColumnStatement(AlterStatement):
     __slots__ = ("column",)
 
-    column: t.Union[Column, str]
+    column: Union[Column, str]
 
     @property
     def column_name(self) -> str:
@@ -114,7 +115,7 @@ class SetColumnType(AlterStatement):
 
     old_column: Column
     new_column: Column
-    using_expression: t.Optional[str] = None
+    using_expression: Optional[str] = None
 
     @property
     def ddl(self) -> str:
@@ -135,7 +136,7 @@ class SetDefault(AlterColumnStatement):
     __slots__ = ("value",)
 
     column: Column
-    value: t.Any
+    value: Any
 
     @property
     def ddl(self) -> str:
@@ -215,8 +216,8 @@ class AddForeignKeyConstraint(AlterStatement):
     foreign_key_column_name: str
     referenced_table_name: str
     referenced_column_name: str
-    on_delete: t.Optional[OnDelete]
-    on_update: t.Optional[OnUpdate]
+    on_delete: Optional[OnDelete]
+    on_update: Optional[OnUpdate]
 
     @property
     def ddl(self) -> str:
@@ -236,7 +237,7 @@ class AddForeignKeyConstraint(AlterStatement):
 class SetDigits(AlterColumnStatement):
     __slots__ = ("digits", "column_type")
 
-    digits: t.Optional[t.Tuple[int, int]]
+    digits: Optional[tuple[int, int]]
     column_type: str
 
     @property
@@ -265,7 +266,7 @@ class SetSchema(AlterStatement):
 
 @dataclass
 class DropTable:
-    table: t.Type[Table]
+    table: type[Table]
     cascade: bool
     if_exists: bool
 
@@ -304,24 +305,24 @@ class Alter(DDL):
         "_rename_constraint",
     )
 
-    def __init__(self, table: t.Type[Table], **kwargs):
+    def __init__(self, table: type[Table], **kwargs):
         super().__init__(table, **kwargs)
-        self._add_foreign_key_constraint: t.List[AddForeignKeyConstraint] = []
-        self._add: t.List[AddColumn] = []
-        self._drop_constraint: t.List[DropConstraint] = []
-        self._drop_default: t.List[DropDefault] = []
-        self._drop_table: t.Optional[DropTable] = None
-        self._drop: t.List[DropColumn] = []
-        self._rename_columns: t.List[RenameColumn] = []
-        self._rename_table: t.List[RenameTable] = []
-        self._set_column_type: t.List[SetColumnType] = []
-        self._set_default: t.List[SetDefault] = []
-        self._set_digits: t.List[SetDigits] = []
-        self._set_length: t.List[SetLength] = []
-        self._set_null: t.List[SetNull] = []
-        self._set_schema: t.List[SetSchema] = []
-        self._set_unique: t.List[SetUnique] = []
-        self._rename_constraint: t.List[RenameConstraint] = []
+        self._add_foreign_key_constraint: list[AddForeignKeyConstraint] = []
+        self._add: list[AddColumn] = []
+        self._drop_constraint: list[DropConstraint] = []
+        self._drop_default: list[DropDefault] = []
+        self._drop_table: Optional[DropTable] = None
+        self._drop: list[DropColumn] = []
+        self._rename_columns: list[RenameColumn] = []
+        self._rename_table: list[RenameTable] = []
+        self._set_column_type: list[SetColumnType] = []
+        self._set_default: list[SetDefault] = []
+        self._set_digits: list[SetDigits] = []
+        self._set_length: list[SetLength] = []
+        self._set_null: list[SetNull] = []
+        self._set_schema: list[SetSchema] = []
+        self._set_unique: list[SetUnique] = []
+        self._rename_constraint: list[RenameConstraint] = []
 
     def add_column(self: Self, name: str, column: Column) -> Self:
         """
@@ -340,7 +341,7 @@ class Alter(DDL):
         self._add.append(AddColumn(column, name))
         return self
 
-    def drop_column(self, column: t.Union[str, Column]) -> Alter:
+    def drop_column(self, column: Union[str, Column]) -> Alter:
         """
         Drop a column from the table::
 
@@ -350,7 +351,7 @@ class Alter(DDL):
         self._drop.append(DropColumn(column))
         return self
 
-    def drop_default(self, column: t.Union[str, Column]) -> Alter:
+    def drop_default(self, column: Union[str, Column]) -> Alter:
         """
         Drop the default from a column::
 
@@ -406,7 +407,7 @@ class Alter(DDL):
         return self
 
     def rename_column(
-        self, column: t.Union[str, Column], new_name: str
+        self, column: Union[str, Column], new_name: str
     ) -> Alter:
         """
         Rename a column on the table::
@@ -425,7 +426,7 @@ class Alter(DDL):
         self,
         old_column: Column,
         new_column: Column,
-        using_expression: t.Optional[str] = None,
+        using_expression: Optional[str] = None,
     ) -> Alter:
         """
         Change the type of a column::
@@ -448,7 +449,7 @@ class Alter(DDL):
         )
         return self
 
-    def set_default(self, column: Column, value: t.Any) -> Alter:
+    def set_default(self, column: Column, value: Any) -> Alter:
         """
         Set the default for a column::
 
@@ -459,7 +460,7 @@ class Alter(DDL):
         return self
 
     def set_null(
-        self, column: t.Union[str, Column], boolean: bool = True
+        self, column: Union[str, Column], boolean: bool = True
     ) -> Alter:
         """
         Change a column to be nullable or not::
@@ -475,7 +476,7 @@ class Alter(DDL):
         return self
 
     def set_unique(
-        self, column: t.Union[str, Column], boolean: bool = True
+        self, column: Union[str, Column], boolean: bool = True
     ) -> Alter:
         """
         Make a column unique or not::
@@ -490,7 +491,7 @@ class Alter(DDL):
         self._set_unique.append(SetUnique(column, boolean))
         return self
 
-    def set_length(self, column: t.Union[str, Varchar], length: int) -> Alter:
+    def set_length(self, column: Union[str, Varchar], length: int) -> Alter:
         """
         Change the max length of a varchar column. Unfortunately, this isn't
         supported by SQLite, but SQLite also doesn't enforce any length limits
@@ -518,7 +519,7 @@ class Alter(DDL):
         self._set_length.append(SetLength(column, length))
         return self
 
-    def _get_constraint_name(self, column: t.Union[str, ForeignKey]) -> str:
+    def _get_constraint_name(self, column: Union[str, ForeignKey]) -> str:
         column_name = AlterColumnStatement(column=column).column_name
         tablename = self.table._meta.tablename
         return f"{tablename}_{column_name}_fkey"
@@ -530,7 +531,7 @@ class Alter(DDL):
         return self
 
     def drop_foreign_key_constraint(
-        self, column: t.Union[str, ForeignKey]
+        self, column: Union[str, ForeignKey]
     ) -> Alter:
         constraint_name = self._get_constraint_name(column=column)
         self._drop_constraint.append(
@@ -540,12 +541,12 @@ class Alter(DDL):
 
     def add_foreign_key_constraint(
         self,
-        column: t.Union[str, ForeignKey],
-        referenced_table_name: t.Optional[str] = None,
-        referenced_column_name: t.Optional[str] = None,
-        constraint_name: t.Optional[str] = None,
-        on_delete: t.Optional[OnDelete] = None,
-        on_update: t.Optional[OnUpdate] = None,
+        column: Union[str, ForeignKey],
+        referenced_table_name: Optional[str] = None,
+        referenced_column_name: Optional[str] = None,
+        constraint_name: Optional[str] = None,
+        on_delete: Optional[OnDelete] = None,
+        on_update: Optional[OnUpdate] = None,
     ) -> Alter:
         """
         Add a new foreign key constraint::
@@ -591,8 +592,8 @@ class Alter(DDL):
 
     def set_digits(
         self,
-        column: t.Union[str, Numeric],
-        digits: t.Optional[t.Tuple[int, int]],
+        column: Union[str, Numeric],
+        digits: Optional[tuple[int, int]],
     ) -> Alter:
         """
         Alter the precision and scale for a ``Numeric`` column.
@@ -623,7 +624,7 @@ class Alter(DDL):
         return self
 
     @property
-    def default_ddl(self) -> t.Sequence[str]:
+    def default_ddl(self) -> Sequence[str]:
         if self._drop_table is not None:
             return [self._drop_table.ddl]
 
@@ -660,4 +661,4 @@ class Alter(DDL):
         return [query]
 
 
-Self = t.TypeVar("Self", bound=Alter)
+Self = TypeVar("Self", bound=Alter)

piccolo/query/methods/count.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-import typing as t
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Optional, TypeVar, Union
 
 from piccolo.custom_types import Combinable
 from piccolo.query.base import Query
@@ -8,7 +9,7 @@ from piccolo.query.functions.aggregate import Count as CountFunction
 from piccolo.query.mixins import WhereDelegate
 from piccolo.querystring import QueryString
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns import Column
     from piccolo.table import Table
 
@@ -19,9 +20,9 @@ class Count(Query):
 
     def __init__(
         self,
-        table: t.Type[Table],
-        column: t.Optional[Column] = None,
-        distinct: t.Optional[t.Sequence[Column]] = None,
+        table: type[Table],
+        column: Optional[Column] = None,
+        distinct: Optional[Sequence[Column]] = None,
         **kwargs,
     ):
         super().__init__(table, **kwargs)
@@ -32,11 +33,11 @@ class Count(Query):
     ###########################################################################
     # Clauses
 
-    def where(self: Self, *where: t.Union[Combinable, QueryString]) -> Self:
+    def where(self: Self, *where: Union[Combinable, QueryString]) -> Self:
         self.where_delegate.where(*where)
         return self
 
-    def distinct(self: Self, columns: t.Optional[t.Sequence[Column]]) -> Self:
+    def distinct(self: Self, columns: Optional[Sequence[Column]]) -> Self:
         self._distinct = columns
         return self
 
@@ -46,8 +47,8 @@ class Count(Query):
         return response[0]["count"]
 
     @property
-    def default_querystrings(self) -> t.Sequence[QueryString]:
-        table: t.Type[Table] = self.table
+    def default_querystrings(self) -> Sequence[QueryString]:
+        table: type[Table] = self.table
 
         query = table.select(
             CountFunction(column=self.column, distinct=self._distinct)
@@ -58,4 +59,4 @@ class Count(Query):
         return query.querystrings
 
 
-Self = t.TypeVar("Self", bound=Count)
+Self = TypeVar("Self", bound=Count)

piccolo/query/methods/create.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-import typing as t
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
 
 from piccolo.query.base import DDL
 from piccolo.query.methods.create_index import CreateIndex
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.table import Table
 
 
@@ -18,7 +19,7 @@ class Create(DDL):
 
     def __init__(
         self,
-        table: t.Type[Table],
+        table: type[Table],
         if_not_exists: bool = False,
         only_default_columns: bool = False,
         auto_create_schema: bool = True,
@@ -43,8 +44,8 @@ class Create(DDL):
         self.auto_create_schema = auto_create_schema
 
     @property
-    def default_ddl(self) -> t.Sequence[str]:
-        ddl: t.List[str] = []
+    def default_ddl(self) -> Sequence[str]:
+        ddl: list[str] = []
 
         schema_name = self.table._meta.schema
         if (

piccolo/query/methods/create_index.py

@@ -1,20 +1,21 @@
 from __future__ import annotations
 
-import typing as t
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Union
 
 from piccolo.columns import Column
 from piccolo.columns.indexes import IndexMethod
 from piccolo.query.base import DDL
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.table import Table
 
 
 class CreateIndex(DDL):
     def __init__(
         self,
-        table: t.Type[Table],
-        columns: t.Union[t.List[Column], t.List[str]],
+        table: type[Table],
+        columns: Union[list[Column], list[str]],
         method: IndexMethod = IndexMethod.btree,
         if_not_exists: bool = False,
         **kwargs,
@@ -25,7 +26,7 @@ class CreateIndex(DDL):
         super().__init__(table, **kwargs)
 
     @property
-    def column_names(self) -> t.List[str]:
+    def column_names(self) -> list[str]:
         return [
             i._meta.db_column_name if isinstance(i, Column) else i
             for i in self.columns
@@ -39,7 +40,7 @@ class CreateIndex(DDL):
         return prefix
 
     @property
-    def postgres_ddl(self) -> t.Sequence[str]:
+    def postgres_ddl(self) -> Sequence[str]:
         column_names = self.column_names
         index_name = self.table._get_index_name(column_names)
         tablename = self.table._meta.get_formatted_tablename()
@@ -53,11 +54,11 @@ class CreateIndex(DDL):
         ]
 
     @property
-    def cockroach_ddl(self) -> t.Sequence[str]:
+    def cockroach_ddl(self) -> Sequence[str]:
         return self.postgres_ddl
 
     @property
-    def sqlite_ddl(self) -> t.Sequence[str]:
+    def sqlite_ddl(self) -> Sequence[str]:
         column_names = self.column_names
         index_name = self.table._get_index_name(column_names)
         tablename = self.table._meta.get_formatted_tablename()

piccolo/query/methods/delete.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-import typing as t
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, TypeVar, Union
 
 from piccolo.custom_types import Combinable
 from piccolo.query.base import Query
 from piccolo.query.mixins import ReturningDelegate, WhereDelegate
 from piccolo.querystring import QueryString
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns import Column
     from piccolo.table import Table
 
@@ -24,13 +25,13 @@ class Delete(Query):
         "where_delegate",
     )
 
-    def __init__(self, table: t.Type[Table], force: bool = False, **kwargs):
+    def __init__(self, table: type[Table], force: bool = False, **kwargs):
         super().__init__(table, **kwargs)
         self.force = force
         self.returning_delegate = ReturningDelegate()
         self.where_delegate = WhereDelegate()
 
-    def where(self: Self, *where: t.Union[Combinable, QueryString]) -> Self:
+    def where(self: Self, *where: Union[Combinable, QueryString]) -> Self:
         self.where_delegate.where(*where)
         return self
 
@@ -52,7 +53,7 @@ class Delete(Query):
             )
 
     @property
-    def default_querystrings(self) -> t.Sequence[QueryString]:
+    def default_querystrings(self) -> Sequence[QueryString]:
         query = f"DELETE FROM {self.table._meta.get_formatted_tablename()}"
 
         querystring = QueryString(query)
@@ -74,4 +75,4 @@ class Delete(Query):
         return [querystring]
 
 
-Self = t.TypeVar("Self", bound=Delete)
+Self = TypeVar("Self", bound=Delete)