piccolo 1.5.2__py3-none-any.whl → 1.7.0__py3-none-any.whl

piccolo/engine/sqlite.py

@@ -9,6 +9,7 @@ import typing as t
 import uuid
 from dataclasses import dataclass
 from decimal import Decimal
+from functools import partial, wraps
 
 from piccolo.engine.base import Batch, Engine, validate_savepoint_name
 from piccolo.engine.exceptions import TransactionError
@@ -35,14 +36,14 @@ if t.TYPE_CHECKING:  # pragma: no cover
 # In
 
 
-def convert_numeric_in(value):
+def convert_numeric_in(value: Decimal) -> float:
     """
     Convert any Decimal values into floats.
     """
     return float(value)
 
 
-def convert_uuid_in(value) -> str:
+def convert_uuid_in(value: uuid.UUID) -> str:
     """
     Converts the UUID value being passed into sqlite.
     """
@@ -56,7 +57,7 @@ def convert_time_in(value: datetime.time) -> str:
     return value.isoformat()
 
 
-def convert_date_in(value: datetime.date):
+def convert_date_in(value: datetime.date) -> str:
     """
     Converts the date value being passed into sqlite.
     """
@@ -74,122 +75,235 @@ def convert_datetime_in(value: datetime.datetime) -> str:
     return str(value)
 
 
-def convert_timedelta_in(value: datetime.timedelta):
+def convert_timedelta_in(value: datetime.timedelta) -> float:
     """
     Converts the timedelta value being passed into sqlite.
     """
     return value.total_seconds()
 
 
-def convert_array_in(value: list):
+def convert_array_in(value: list) -> str:
     """
-    Converts a list value into a string.
+    Converts a list value into a string (it handles nested lists, and type like
+    dateime/ time / date which aren't usually JSON serialisable.).
+
     """
-    if value and type(value[0]) not in [str, int, float, list]:
-        raise ValueError("Can only serialise str, int, float, and list.")
 
-    return dump_json(value)
+    def serialise(data: list):
+        output = []
+
+        for item in data:
+            if isinstance(item, list):
+                output.append(serialise(item))
+            elif isinstance(
+                item, (datetime.datetime, datetime.time, datetime.date)
+            ):
+                if adapter := ADAPTERS.get(type(item)):
+                    output.append(adapter(item))
+                else:
+                    raise ValueError("The adapter wasn't found.")
+            elif item is None or isinstance(item, (str, int, float, list)):
+                # We can safely JSON serialise these.
+                output.append(item)
+            else:
+                raise ValueError("We can't currently serialise this value.")
+
+        return output
+
+    return dump_json(serialise(value))
+
+
+###############################################################################
+
+# Register adapters
+
+ADAPTERS: t.Dict[t.Type, t.Callable[[t.Any], t.Any]] = {
+    Decimal: convert_numeric_in,
+    uuid.UUID: convert_uuid_in,
+    datetime.time: convert_time_in,
+    datetime.date: convert_date_in,
+    datetime.datetime: convert_datetime_in,
+    datetime.timedelta: convert_timedelta_in,
+    list: convert_array_in,
+}
 
+for value_type, adapter in ADAPTERS.items():
+    sqlite3.register_adapter(value_type, adapter)
+
+###############################################################################
 
 # Out
 
 
-def convert_numeric_out(value: bytes) -> Decimal:
+def decode_to_string(converter: t.Callable[[str], t.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
+    used by the array converters.
+    """
+
+    @wraps(converter)
+    def wrapper(value: t.Union[str, bytes]) -> t.Any:
+        if isinstance(value, bytes):
+            return converter(value.decode("utf8"))
+        elif isinstance(value, str):
+            return converter(value)
+        else:
+            raise ValueError("Unsupported type")
+
+    return wrapper
+
+
+@decode_to_string
+def convert_numeric_out(value: str) -> Decimal:
     """
     Convert float values into Decimals.
     """
-    return Decimal(value.decode("ascii"))
+    return Decimal(value)
 
 
-def convert_int_out(value: bytes) -> int:
+@decode_to_string
+def convert_int_out(value: str) -> int:
     """
     Make sure Integer values are actually of type int.
     """
     return int(float(value))
 
 
-def convert_uuid_out(value: bytes) -> uuid.UUID:
+@decode_to_string
+def convert_uuid_out(value: str) -> uuid.UUID:
     """
     If the value is a uuid, convert it to a UUID instance.
     """
-    return uuid.UUID(value.decode("utf8"))
+    return uuid.UUID(value)
 
 
-def convert_date_out(value: bytes) -> datetime.date:
-    return datetime.date.fromisoformat(value.decode("utf8"))
+@decode_to_string
+def convert_date_out(value: str) -> datetime.date:
+    return datetime.date.fromisoformat(value)
 
 
-def convert_time_out(value: bytes) -> datetime.time:
+@decode_to_string
+def convert_time_out(value: str) -> datetime.time:
     """
     If the value is a time, convert it to a UUID instance.
     """
-    return datetime.time.fromisoformat(value.decode("utf8"))
+    return datetime.time.fromisoformat(value)
 
 
-def convert_seconds_out(value: bytes) -> datetime.timedelta:
+@decode_to_string
+def convert_seconds_out(value: str) -> datetime.timedelta:
     """
     If the value is from a seconds column, convert it to a timedelta instance.
     """
-    return datetime.timedelta(seconds=float(value.decode("utf8")))
+    return datetime.timedelta(seconds=float(value))
 
 
-def convert_boolean_out(value: bytes) -> bool:
+@decode_to_string
+def convert_boolean_out(value: str) -> bool:
     """
     If the value is from a boolean column, convert it to a bool value.
     """
-    _value = value.decode("utf8")
-    return _value == "1"
+    return value == "1"
 
 
-def convert_timestamp_out(value: bytes) -> datetime.datetime:
+@decode_to_string
+def convert_timestamp_out(value: str) -> datetime.datetime:
     """
     If the value is from a timestamp column, convert it to a datetime value.
     """
-    return datetime.datetime.fromisoformat(value.decode("utf8"))
+    return datetime.datetime.fromisoformat(value)
 
 
-def convert_timestamptz_out(value: bytes) -> datetime.datetime:
+@decode_to_string
+def convert_timestamptz_out(value: str) -> datetime.datetime:
     """
     If the value is from a timestamptz column, convert it to a datetime value,
     with a timezone of UTC.
     """
-    _value = datetime.datetime.fromisoformat(value.decode("utf8"))
-    _value = _value.replace(tzinfo=datetime.timezone.utc)
-    return _value
+    return datetime.datetime.fromisoformat(value).replace(
+        tzinfo=datetime.timezone.utc
+    )
 
 
-def convert_array_out(value: bytes) -> t.List:
+@decode_to_string
+def convert_array_out(value: str) -> t.List:
     """
     If the value if from an array column, deserialise the string back into a
     list.
     """
-    return load_json(value.decode("utf8"))
-
-
-def convert_M2M_out(value: bytes) -> t.List:
-    _value = value.decode("utf8")
-    return _value.split(",")
-
-
-sqlite3.register_converter("Numeric", convert_numeric_out)
-sqlite3.register_converter("Integer", convert_int_out)
-sqlite3.register_converter("UUID", convert_uuid_out)
-sqlite3.register_converter("Date", convert_date_out)
-sqlite3.register_converter("Time", convert_time_out)
-sqlite3.register_converter("Seconds", convert_seconds_out)
-sqlite3.register_converter("Boolean", convert_boolean_out)
-sqlite3.register_converter("Timestamp", convert_timestamp_out)
-sqlite3.register_converter("Timestamptz", convert_timestamptz_out)
-sqlite3.register_converter("Array", convert_array_out)
-sqlite3.register_converter("M2M", convert_M2M_out)
-
-sqlite3.register_adapter(Decimal, convert_numeric_in)
-sqlite3.register_adapter(uuid.UUID, convert_uuid_in)
-sqlite3.register_adapter(datetime.time, convert_time_in)
-sqlite3.register_adapter(datetime.date, convert_date_in)
-sqlite3.register_adapter(datetime.datetime, convert_datetime_in)
-sqlite3.register_adapter(datetime.timedelta, convert_timedelta_in)
-sqlite3.register_adapter(list, convert_array_in)
+    return load_json(value)
+
+
+def convert_complex_array_out(value: bytes, converter: t.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
+    back into Python objects.
+    """
+    parsed = load_json(value.decode("utf8"))
+
+    def convert_list(list_value: t.List):
+        output = []
+
+        for value in list_value:
+            if isinstance(value, list):
+                # For nested arrays
+                output.append(convert_list(value))
+            elif isinstance(value, str):
+                output.append(converter(value))
+            else:
+                output.append(value)
+
+        return output
+
+    if isinstance(parsed, list):
+        return convert_list(parsed)
+    else:
+        return parsed
+
+
+@decode_to_string
+def convert_M2M_out(value: str) -> t.List:
+    return value.split(",")
+
+
+###############################################################################
+# Register the basic converters
+
+CONVERTERS = {
+    "NUMERIC": convert_numeric_out,
+    "INTEGER": convert_int_out,
+    "UUID": convert_uuid_out,
+    "DATE": convert_date_out,
+    "TIME": convert_time_out,
+    "SECONDS": convert_seconds_out,
+    "BOOLEAN": convert_boolean_out,
+    "TIMESTAMP": convert_timestamp_out,
+    "TIMESTAMPTZ": convert_timestamptz_out,
+    "M2M": convert_M2M_out,
+}
+
+for column_name, converter in CONVERTERS.items():
+    sqlite3.register_converter(column_name, converter)
+
+###############################################################################
+# Register the array converters
+
+# The ARRAY column type handles values which can be easily serialised to and
+# from JSON.
+sqlite3.register_converter("ARRAY", convert_array_out)
+
+# We have special column types for arrays of timestamps etc, as simply loading
+# the JSON isn't sufficient.
+for column_name in ("TIMESTAMP", "TIMESTAMPTZ", "DATE", "TIME"):
+    sqlite3.register_converter(
+        f"ARRAY_{column_name}",
+        partial(
+            convert_complex_array_out,
+            converter=CONVERTERS[column_name],
+        ),
+    )
 
 ###############################################################################
 

piccolo/query/__init__.py

@@ -1,9 +1,9 @@
 from piccolo.columns.combination import WhereRaw
 
 from .base import Query
+from .functions.aggregate import Avg, Max, Min, Sum
 from .methods import (
     Alter,
-    Avg,
     Count,
     Create,
     CreateIndex,
@@ -11,12 +11,9 @@ from .methods import (
     DropIndex,
     Exists,
     Insert,
-    Max,
-    Min,
     Objects,
     Raw,
     Select,
-    Sum,
     TableExists,
     Update,
 )

piccolo/query/functions/__init__.py

@@ -0,0 +1,16 @@
+from .aggregate import Avg, Count, Max, Min, Sum
+from .string import Length, Lower, Ltrim, Reverse, Rtrim, Upper
+
+__all__ = (
+    "Avg",
+    "Count",
+    "Length",
+    "Lower",
+    "Ltrim",
+    "Max",
+    "Min",
+    "Reverse",
+    "Rtrim",
+    "Sum",
+    "Upper",
+)

piccolo/query/functions/aggregate.py

@@ -0,0 +1,179 @@
+import typing as t
+
+from piccolo.columns.base import Column
+from piccolo.querystring import QueryString
+
+from .base import Function
+
+
+class Avg(Function):
+    """
+    ``AVG()`` SQL function. Column type must be numeric to run the query.
+
+    .. code-block:: python
+
+        await Band.select(Avg(Band.popularity)).run()
+
+        # We can use an alias. These two are equivalent:
+
+        await Band.select(
+            Avg(Band.popularity, alias="popularity_avg")
+        ).run()
+
+        await Band.select(
+            Avg(Band.popularity).as_alias("popularity_avg")
+        ).run()
+
+    """
+
+    function_name = "AVG"
+
+
+class Count(QueryString):
+    """
+    Used in ``Select`` queries, usually in conjunction with the ``group_by``
+    clause::
+
+        >>> await Band.select(
+        ...     Band.manager.name.as_alias('manager_name'),
+        ...     Count(alias='band_count')
+        ... ).group_by(Band.manager)
+        [{'manager_name': 'Guido', 'count': 1}, ...]
+
+    It can also be used without the ``group_by`` clause (though you may prefer
+    to the :meth:`Table.count <piccolo.table.Table.count>` method instead, as
+    it's more convenient)::
+
+        >>> await Band.select(Count())
+        [{'count': 3}]
+
+    """
+
+    def __init__(
+        self,
+        column: t.Optional[Column] = None,
+        distinct: t.Optional[t.Sequence[Column]] = None,
+        alias: str = "count",
+    ):
+        """
+        :param column:
+            If specified, the count is for non-null values in that column.
+        :param distinct:
+            If specified, the count is for distinct values in those columns.
+        :param alias:
+            The name of the value in the response::
+
+                # These two are equivalent:
+
+                await Band.select(
+                    Band.name, Count(alias="total")
+                ).group_by(Band.name)
+
+                await Band.select(
+                    Band.name,
+                    Count().as_alias("total")
+                ).group_by(Band.name)
+
+        """
+        if distinct and column:
+            raise ValueError("Only specify `column` or `distinct`")
+
+        if distinct:
+            engine_type = distinct[0]._meta.engine_type
+            if engine_type == "sqlite":
+                # SQLite doesn't allow us to specify multiple columns, so
+                # instead we concatenate the values.
+                column_names = " || ".join("{}" for _ in distinct)
+            else:
+                column_names = ", ".join("{}" for _ in distinct)
+
+            return super().__init__(
+                f"COUNT(DISTINCT({column_names}))", *distinct, alias=alias
+            )
+        else:
+            if column:
+                return super().__init__("COUNT({})", column, alias=alias)
+            else:
+                return super().__init__("COUNT(*)", alias=alias)
+
+
+class Min(Function):
+    """
+    ``MIN()`` SQL function.
+
+    .. code-block:: python
+
+        await Band.select(Min(Band.popularity)).run()
+
+        # We can use an alias. These two are equivalent:
+
+        await Band.select(
+            Min(Band.popularity, alias="popularity_min")
+        ).run()
+
+        await Band.select(
+            Min(Band.popularity).as_alias("popularity_min")
+        ).run()
+
+    """
+
+    function_name = "MIN"
+
+
+class Max(Function):
+    """
+    ``MAX()`` SQL function.
+
+    .. code-block:: python
+
+        await Band.select(
+            Max(Band.popularity)
+        ).run()
+
+        # We can use an alias. These two are equivalent:
+
+        await Band.select(
+            Max(Band.popularity, alias="popularity_max")
+        ).run()
+
+        await Band.select(
+            Max(Band.popularity).as_alias("popularity_max")
+        ).run()
+
+    """
+
+    function_name = "MAX"
+
+
+class Sum(Function):
+    """
+    ``SUM()`` SQL function. Column type must be numeric to run the query.
+
+    .. code-block:: python
+
+        await Band.select(
+            Sum(Band.popularity)
+        ).run()
+
+        # We can use an alias. These two are equivalent:
+
+        await Band.select(
+            Sum(Band.popularity, alias="popularity_sum")
+        ).run()
+
+        await Band.select(
+            Sum(Band.popularity).as_alias("popularity_sum")
+        ).run()
+
+    """
+
+    function_name = "SUM"
+
+
+__all__ = (
+    "Avg",
+    "Count",
+    "Min",
+    "Max",
+    "Sum",
+)

piccolo/query/functions/base.py

@@ -0,0 +1,21 @@
+import typing as t
+
+from piccolo.columns.base import Column
+from piccolo.querystring import QueryString
+
+
+class Function(QueryString):
+    function_name: str
+
+    def __init__(
+        self,
+        identifier: t.Union[Column, QueryString, str],
+        alias: t.Optional[str] = None,
+    ):
+        alias = alias or self.__class__.__name__.lower()
+
+        super().__init__(
+            f"{self.function_name}({{}})",
+            identifier,
+            alias=alias,
+        )

piccolo/query/functions/string.py

@@ -0,0 +1,73 @@
+"""
+These functions mirror their counterparts in the Postgresql docs:
+
+https://www.postgresql.org/docs/current/functions-string.html
+
+"""
+
+from .base import Function
+
+
+class Length(Function):
+    """
+    Returns the number of characters in the string.
+    """
+
+    function_name = "LENGTH"
+
+
+class Lower(Function):
+    """
+    Converts the string to all lower case, according to the rules of the
+    database's locale.
+    """
+
+    function_name = "LOWER"
+
+
+class Ltrim(Function):
+    """
+    Removes the longest string containing only characters in characters (a
+    space by default) from the start of string.
+    """
+
+    function_name = "LTRIM"
+
+
+class Reverse(Function):
+    """
+    Return reversed string.
+
+    Not supported in SQLite.
+
+    """
+
+    function_name = "REVERSE"
+
+
+class Rtrim(Function):
+    """
+    Removes the longest string containing only characters in characters (a
+    space by default) from the end of string.
+    """
+
+    function_name = "RTRIM"
+
+
+class Upper(Function):
+    """
+    Converts the string to all upper case, according to the rules of the
+    database's locale.
+    """
+
+    function_name = "UPPER"
+
+
+__all__ = (
+    "Length",
+    "Lower",
+    "Ltrim",
+    "Reverse",
+    "Rtrim",
+    "Upper",
+)

piccolo/query/methods/__init__.py

@@ -9,6 +9,23 @@ from .insert import Insert
 from .objects import Objects
 from .raw import Raw
 from .refresh import Refresh
-from .select import Avg, Max, Min, Select, Sum
+from .select import Select
 from .table_exists import TableExists
 from .update import Update
+
+__all__ = (
+    "Alter",
+    "Count",
+    "Create",
+    "CreateIndex",
+    "Delete",
+    "DropIndex",
+    "Exists",
+    "Insert",
+    "Objects",
+    "Raw",
+    "Refresh",
+    "Select",
+    "TableExists",
+    "Update",
+)

piccolo/query/methods/count.py

@@ -4,7 +4,7 @@ import typing as t
 
 from piccolo.custom_types import Combinable
 from piccolo.query.base import Query
-from piccolo.query.methods.select import Count as SelectCount
+from piccolo.query.functions.aggregate import Count as CountFunction
 from piccolo.query.mixins import WhereDelegate
 from piccolo.querystring import QueryString
 
@@ -32,7 +32,7 @@ class Count(Query):
     ###########################################################################
     # Clauses
 
-    def where(self: Self, *where: Combinable) -> Self:
+    def where(self: Self, *where: t.Union[Combinable, QueryString]) -> Self:
         self.where_delegate.where(*where)
         return self
 
@@ -50,7 +50,7 @@ class Count(Query):
         table: t.Type[Table] = self.table
 
         query = table.select(
-            SelectCount(column=self.column, distinct=self._distinct)
+            CountFunction(column=self.column, distinct=self._distinct)
         )
 
         query.where_delegate._where = self.where_delegate._where