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

piccolo/engine/sqlite.py

@@ -5,11 +5,12 @@ import datetime
 import enum
 import os
 import sqlite3
-import typing as t
 import uuid
+from collections.abc import Callable
 from dataclasses import dataclass
 from decimal import Decimal
 from functools import partial, wraps
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 from typing_extensions import Self
 
@@ -30,7 +31,7 @@ from piccolo.utils.sync import run_sync
 aiosqlite = LazyLoader("aiosqlite", globals(), "aiosqlite")
 
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from aiosqlite import Connection, Cursor  # type: ignore
 
     from piccolo.table import Table
@@ -125,7 +126,7 @@ def convert_array_in(value: list) -> str:
 
 # Register adapters
 
-ADAPTERS: t.Dict[t.Type, t.Callable[[t.Any], t.Any]] = {
+ADAPTERS: dict[type, Callable[[Any], Any]] = {
     Decimal: convert_numeric_in,
     uuid.UUID: convert_uuid_in,
     datetime.time: convert_time_in,
@@ -143,7 +144,7 @@ for value_type, adapter in ADAPTERS.items():
 # Out
 
 
-def decode_to_string(converter: t.Callable[[str], t.Any]):
+def decode_to_string(converter: Callable[[str], Any]):
     """
     This means we can use our converters with string and bytes. They are
     passed bytes when used directly via SQLite, and are passed strings when
@@ -151,7 +152,7 @@ def decode_to_string(converter: t.Callable[[str], t.Any]):
     """
 
     @wraps(converter)
-    def wrapper(value: t.Union[str, bytes]) -> t.Any:
+    def wrapper(value: Union[str, bytes]) -> Any:
         if isinstance(value, bytes):
             return converter(value.decode("utf8"))
         elif isinstance(value, str):
@@ -247,7 +248,7 @@ def convert_timestamptz_out(value: str) -> datetime.datetime:
 
 
 @decode_to_string
-def convert_array_out(value: str) -> t.List:
+def convert_array_out(value: str) -> list:
     """
     If the value if from an array column, deserialise the string back into a
     list.
@@ -255,7 +256,7 @@ def convert_array_out(value: str) -> t.List:
     return load_json(value)
 
 
-def convert_complex_array_out(value: bytes, converter: t.Callable):
+def convert_complex_array_out(value: bytes, converter: Callable):
     """
     This is used to handle arrays of things like timestamps, which we can't
     just load from JSON without doing additional work to convert the elements
@@ -263,7 +264,7 @@ def convert_complex_array_out(value: bytes, converter: t.Callable):
     """
     parsed = load_json(value.decode("utf8"))
 
-    def convert_list(list_value: t.List):
+    def convert_list(list_value: list):
         output = []
 
         for value in list_value:
@@ -284,7 +285,7 @@ def convert_complex_array_out(value: bytes, converter: t.Callable):
 
 
 @decode_to_string
-def convert_M2M_out(value: str) -> t.List:
+def convert_M2M_out(value: str) -> list:
     return value.split(",")
 
 
@@ -335,7 +336,7 @@ class AsyncBatch(BaseBatch):
     batch_size: int
 
     # Set internally
-    _cursor: t.Optional[Cursor] = None
+    _cursor: Optional[Cursor] = None
 
     @property
     def cursor(self) -> Cursor:
@@ -343,14 +344,14 @@ class AsyncBatch(BaseBatch):
             raise ValueError("_cursor not set")
         return self._cursor
 
-    async def next(self) -> t.List[t.Dict]:
+    async def next(self) -> list[dict]:
         data = await self.cursor.fetchmany(self.batch_size)
         return await self.query._process_results(data)
 
     def __aiter__(self: Self) -> Self:
         return self
 
-    async def __anext__(self) -> t.List[t.Dict]:
+    async def __anext__(self) -> list[dict]:
         response = await self.next()
         if response == []:
             raise StopAsyncIteration()
@@ -404,9 +405,9 @@ class Atomic(BaseAtomic):
     ):
         self.engine = engine
         self.transaction_type = transaction_type
-        self.queries: t.List[t.Union[Query, DDL]] = []
+        self.queries: list[Union[Query, DDL]] = []
 
-    def add(self, *query: t.Union[Query, DDL]):
+    def add(self, *query: Union[Query, DDL]):
         self.queries += list(query)
 
     async def run(self):
@@ -546,7 +547,7 @@ class SQLiteTransaction(BaseTransaction):
         self._savepoint_id += 1
         return self._savepoint_id
 
-    async def savepoint(self, name: t.Optional[str] = None) -> Savepoint:
+    async def savepoint(self, name: Optional[str] = None) -> Savepoint:
         name = name or f"savepoint_{self.get_savepoint_id()}"
         validate_savepoint_name(name)
         await self.connection.execute(f"SAVEPOINT {name}")
@@ -576,7 +577,7 @@ class SQLiteTransaction(BaseTransaction):
 ###############################################################################
 
 
-def dict_factory(cursor, row) -> t.Dict:
+def dict_factory(cursor, row) -> dict:
     return {col[0]: row[idx] for idx, col in enumerate(cursor.description)}
 
 
@@ -672,7 +673,7 @@ class SQLiteEngine(Engine[SQLiteTransaction]):
     ###########################################################################
 
     async def batch(
-        self, query: Query, batch_size: int = 100, node: t.Optional[str] = None
+        self, query: Query, batch_size: int = 100, node: Optional[str] = None
     ) -> AsyncBatch:
         """
         :param query:
@@ -698,7 +699,7 @@ class SQLiteEngine(Engine[SQLiteTransaction]):
 
     ###########################################################################
 
-    async def _get_inserted_pk(self, cursor, table: t.Type[Table]) -> t.Any:
+    async def _get_inserted_pk(self, cursor, table: type[Table]) -> Any:
         """
         If the `pk` column is a non-integer then `ROWID` and `pk` will return
         different types. Need to query by `lastrowid` to get `pk`s in SQLite
@@ -714,9 +715,9 @@ class SQLiteEngine(Engine[SQLiteTransaction]):
     async def _run_in_new_connection(
         self,
         query: str,
-        args: t.Optional[t.List[t.Any]] = None,
+        args: Optional[list[Any]] = None,
         query_type: str = "generic",
-        table: t.Optional[t.Type[Table]] = None,
+        table: Optional[type[Table]] = None,
     ):
         if args is None:
             args = []
@@ -740,9 +741,9 @@ class SQLiteEngine(Engine[SQLiteTransaction]):
         self,
         connection,
         query: str,
-        args: t.Optional[t.List[t.Any]] = None,
+        args: Optional[list[Any]] = None,
         query_type: str = "generic",
-        table: t.Optional[t.Type[Table]] = None,
+        table: Optional[type[Table]] = None,
     ):
         """
         This is used when a transaction is currently active.

piccolo/query/base.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-import typing as t
+from collections.abc import Generator, Sequence
 from time import time
+from typing import TYPE_CHECKING, Any, Generic, Optional, Union, cast
 
 from piccolo.columns.column_types import JSON, JSONB
 from piccolo.custom_types import QueryResponseType, TableInstance
@@ -12,7 +13,7 @@ from piccolo.utils.encoding import load_json
 from piccolo.utils.objects import make_nested_object
 from piccolo.utils.sync import run_sync
 
-if t.TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:  # pragma: no cover
     from piccolo.query.mixins import OutputDelegate
     from piccolo.table import Table  # noqa
 
@@ -26,13 +27,13 @@ class Timer:
         print(f"Duration: {self.end - self.start}s")
 
 
-class Query(t.Generic[TableInstance, QueryResponseType]):
+class Query(Generic[TableInstance, QueryResponseType]):
     __slots__ = ("table", "_frozen_querystrings")
 
     def __init__(
         self,
-        table: t.Type[TableInstance],
-        frozen_querystrings: t.Optional[t.Sequence[QueryString]] = None,
+        table: type[TableInstance],
+        frozen_querystrings: Optional[Sequence[QueryString]] = None,
     ):
         self.table = table
         self._frozen_querystrings = frozen_querystrings
@@ -55,21 +56,21 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
         if hasattr(self, "_raw_response_callback"):
             self._raw_response_callback(raw)
 
-        output: t.Optional[OutputDelegate] = getattr(
+        output: Optional[OutputDelegate] = getattr(
             self, "output_delegate", None
         )
 
         #######################################################################
 
         if output and output._output.load_json:
-            columns_delegate: t.Optional[ColumnsDelegate] = getattr(
+            columns_delegate: Optional[ColumnsDelegate] = getattr(
                 self, "columns_delegate", None
             )
 
-            json_column_names: t.List[str] = []
+            json_column_names: list[str] = []
 
             if columns_delegate is not None:
-                json_columns: t.List[t.Union[JSON, JSONB]] = []
+                json_columns: list[Union[JSON, JSONB]] = []
 
                 for column in columns_delegate.selected_columns:
                     if isinstance(column, (JSON, JSONB)):
@@ -107,12 +108,12 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
         if output:
             if output._output.as_objects:
                 if output._output.nested:
-                    return t.cast(
+                    return cast(
                         QueryResponseType,
                         [make_nested_object(row, self.table) for row in raw],
                     )
                 else:
-                    return t.cast(
+                    return cast(
                         QueryResponseType,
                         [
                             self.table(**columns, _exists_in_db=True)
@@ -120,7 +121,7 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
                         ],
                     )
 
-        return t.cast(QueryResponseType, raw)
+        return cast(QueryResponseType, raw)
 
     def _validate(self):
         """
@@ -130,7 +131,7 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
         """
         pass
 
-    def __await__(self) -> t.Generator[None, None, QueryResponseType]:
+    def __await__(self) -> Generator[None, None, QueryResponseType]:
         """
         If the user doesn't explicity call .run(), proxy to it as a
         convenience.
@@ -138,7 +139,7 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
         return self.run().__await__()
 
     async def _run(
-        self, node: t.Optional[str] = None, in_pool: bool = True
+        self, node: Optional[str] = None, in_pool: bool = True
     ) -> QueryResponseType:
         """
         Run the query on the database.
@@ -184,16 +185,16 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
                 processed_results = await self._process_results(results)
 
                 responses.append(processed_results)
-            return t.cast(QueryResponseType, responses)
+            return cast(QueryResponseType, responses)
 
     async def run(
-        self, node: t.Optional[str] = None, in_pool: bool = True
+        self, node: Optional[str] = None, in_pool: bool = True
     ) -> QueryResponseType:
         return await self._run(node=node, in_pool=in_pool)
 
     def run_sync(
         self,
-        node: t.Optional[str] = None,
+        node: Optional[str] = None,
         timed: bool = False,
         in_pool: bool = False,
     ) -> QueryResponseType:
@@ -217,7 +218,7 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
         with Timer():
             return run_sync(coroutine)
 
-    async def response_handler(self, response: t.List) -> t.Any:
+    async def response_handler(self, response: list) -> Any:
         """
         Subclasses can override this to modify the raw response returned by
         the database driver.
@@ -227,23 +228,23 @@ class Query(t.Generic[TableInstance, QueryResponseType]):
     ###########################################################################
 
     @property
-    def sqlite_querystrings(self) -> t.Sequence[QueryString]:
+    def sqlite_querystrings(self) -> Sequence[QueryString]:
         raise NotImplementedError
 
     @property
-    def postgres_querystrings(self) -> t.Sequence[QueryString]:
+    def postgres_querystrings(self) -> Sequence[QueryString]:
         raise NotImplementedError
 
     @property
-    def cockroach_querystrings(self) -> t.Sequence[QueryString]:
+    def cockroach_querystrings(self) -> Sequence[QueryString]:
         raise NotImplementedError
 
     @property
-    def default_querystrings(self) -> t.Sequence[QueryString]:
+    def default_querystrings(self) -> Sequence[QueryString]:
         raise NotImplementedError
 
     @property
-    def querystrings(self) -> t.Sequence[QueryString]:
+    def querystrings(self) -> Sequence[QueryString]:
         """
         Calls the correct underlying method, depending on the current engine.
         """
@@ -367,7 +368,7 @@ class FrozenQuery:
 class DDL:
     __slots__ = ("table",)
 
-    def __init__(self, table: t.Type[Table], **kwargs):
+    def __init__(self, table: type[Table], **kwargs):
         self.table = table
 
     @property
@@ -379,23 +380,23 @@ class DDL:
             raise ValueError("Engine isn't defined.")
 
     @property
-    def sqlite_ddl(self) -> t.Sequence[str]:
+    def sqlite_ddl(self) -> Sequence[str]:
         raise NotImplementedError
 
     @property
-    def postgres_ddl(self) -> t.Sequence[str]:
+    def postgres_ddl(self) -> Sequence[str]:
         raise NotImplementedError
 
     @property
-    def cockroach_ddl(self) -> t.Sequence[str]:
+    def cockroach_ddl(self) -> Sequence[str]:
         raise NotImplementedError
 
     @property
-    def default_ddl(self) -> t.Sequence[str]:
+    def default_ddl(self) -> Sequence[str]:
         raise NotImplementedError
 
     @property
-    def ddl(self) -> t.Sequence[str]:
+    def ddl(self) -> Sequence[str]:
         """
         Calls the correct underlying method, depending on the current engine.
         """

piccolo/query/functions/__init__.py

@@ -1,4 +1,11 @@
 from .aggregate import Avg, Count, Max, Min, Sum
+from .array import (
+    ArrayAppend,
+    ArrayCat,
+    ArrayPrepend,
+    ArrayRemove,
+    ArrayReplace,
+)
 from .datetime import Day, Extract, Hour, Month, Second, Strftime, Year
 from .math import Abs, Ceil, Floor, Round
 from .string import Concat, Length, Lower, Ltrim, Reverse, Rtrim, Upper
@@ -30,4 +37,9 @@ __all__ = (
     "Sum",
     "Upper",
     "Year",
+    "ArrayAppend",
+    "ArrayCat",
+    "ArrayPrepend",
+    "ArrayRemove",
+    "ArrayReplace",
 )

piccolo/query/functions/aggregate.py

@@ -1,4 +1,5 @@
-import typing as t
+from collections.abc import Sequence
+from typing import Optional
 
 from piccolo.columns.base import Column
 from piccolo.querystring import QueryString
@@ -51,8 +52,8 @@ class Count(QueryString):
 
     def __init__(
         self,
-        column: t.Optional[Column] = None,
-        distinct: t.Optional[t.Sequence[Column]] = None,
+        column: Optional[Column] = None,
+        distinct: Optional[Sequence[Column]] = None,
         alias: str = "count",
     ):
         """

piccolo/query/functions/array.py

@@ -0,0 +1,151 @@
+from typing import Union
+
+from typing_extensions import TypeAlias
+
+from piccolo.columns.base import Column
+from piccolo.querystring import QueryString
+
+ArrayType: TypeAlias = Union[Column, QueryString, list[object]]
+ArrayItemType: TypeAlias = Union[Column, QueryString, object]
+
+
+class ArrayQueryString(QueryString):
+    def __add__(self, array: ArrayType):
+        """
+        QueryString will use the ``+`` operator by default for addition, but
+        for arrays we want to concatenate them instead.
+        """
+        return ArrayCat(array_1=self, array_2=array)
+
+    def __radd__(self, array: ArrayType):
+        return ArrayCat(array_1=array, array_2=self)
+
+
+class ArrayCat(ArrayQueryString):
+    def __init__(
+        self,
+        array_1: ArrayType,
+        array_2: ArrayType,
+    ):
+        """
+        Concatenate two arrays.
+
+        :param array_1:
+            These values will be at the start of the new array.
+        :param array_2:
+            These values will be at the end of the new array.
+
+        """
+        for value in (array_1, array_2):
+            if isinstance(value, Column):
+                engine_type = value._meta.engine_type
+                if engine_type not in ("postgres", "cockroach"):
+                    raise ValueError(
+                        "Only Postgres and Cockroach support array "
+                        "concatenation."
+                    )
+
+        super().__init__("array_cat({}, {})", array_1, array_2)
+
+
+class ArrayAppend(ArrayQueryString):
+    def __init__(self, array: ArrayType, value: ArrayItemType):
+        """
+        Append an element to the end of an array.
+
+        :param column:
+            Identifies the column.
+        :param value:
+            The value to append.
+
+        """
+        if isinstance(array, Column):
+            engine_type = array._meta.engine_type
+            if engine_type not in ("postgres", "cockroach"):
+                raise ValueError(
+                    "Only Postgres and Cockroach support array appending."
+                )
+
+        super().__init__("array_append({}, {})", array, value)
+
+
+class ArrayPrepend(ArrayQueryString):
+    def __init__(self, array: ArrayType, value: ArrayItemType):
+        """
+        Append an element to the beginning of an array.
+
+        :param value:
+            The value to prepend.
+        :param column:
+            Identifies the column.
+
+        """
+        if isinstance(array, Column):
+            engine_type = array._meta.engine_type
+            if engine_type not in ("postgres", "cockroach"):
+                raise ValueError(
+                    "Only Postgres and Cockroach support array prepending."
+                )
+
+        super().__init__("array_prepend({}, {})", value, array)
+
+
+class ArrayReplace(ArrayQueryString):
+    def __init__(
+        self,
+        array: ArrayType,
+        old_value: ArrayItemType,
+        new_value: ArrayItemType,
+    ):
+        """
+        Replace each array element equal to the given value with a new value.
+
+        :param column:
+            Identifies the column.
+        :param old_value:
+            The old value to be replaced.
+        :param new_value:
+            The new value we are replacing with.
+
+        """
+        if isinstance(array, Column):
+            engine_type = array._meta.engine_type
+            if engine_type not in ("postgres", "cockroach"):
+                raise ValueError(
+                    "Only Postgres and Cockroach support array substitution."
+                )
+
+        super().__init__(
+            "array_replace({}, {}, {})", array, old_value, new_value
+        )
+
+
+class ArrayRemove(ArrayQueryString):
+    def __init__(self, array: ArrayType, value: ArrayItemType):
+        """
+        Remove all elements equal to the given value
+        from the array (array must be one-dimensional).
+
+        :param column:
+            Identifies the column.
+        :param value:
+            The value to remove.
+
+        """
+        if isinstance(array, Column):
+            engine_type = array._meta.engine_type
+            if engine_type not in ("postgres", "cockroach"):
+                raise ValueError(
+                    "Only Postgres and Cockroach support array removing."
+                )
+
+        super().__init__("array_remove({}, {})", array, value)
+
+
+__all__ = (
+    "ArrayCat",
+    "ArrayAppend",
+    "ArrayPrepend",
+    "ArrayReplace",
+    "ArrayRemove",
+)

piccolo/query/functions/base.py

@@ -1,4 +1,4 @@
-import typing as t
+from typing import Optional, Union
 
 from piccolo.columns.base import Column
 from piccolo.querystring import QueryString
@@ -9,8 +9,8 @@ class Function(QueryString):
 
     def __init__(
         self,
-        identifier: t.Union[Column, QueryString, str],
-        alias: t.Optional[str] = None,
+        identifier: Union[Column, QueryString, str],
+        alias: Optional[str] = None,
     ):
         alias = alias or self.__class__.__name__.lower()