piccolo 1.10.0__tar.gz → 1.11.0__tar.gz

{piccolo-1.10.0 → piccolo-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piccolo
-Version: 1.10.0
+Version: 1.11.0
 Summary: A fast, user friendly ORM and query builder which supports asyncio.
 Home-page: https://github.com/piccolo-orm/piccolo
 Author: Daniel Townsend

piccolo-1.11.0/piccolo/__init__.py

@@ -0,0 +1 @@
+__VERSION__ = "1.11.0"

{piccolo-1.10.0 → piccolo-1.11.0}/piccolo/columns/column_types.py

@@ -86,47 +86,38 @@ class ConcatDelegate:
 
     def get_querystring(
         self,
-        column_name: str,
-        value: t.Union[str, Varchar, Text],
+        column: Column,
+        value: t.Union[str, Column, QueryString],
         reverse: bool = False,
     ) -> QueryString:
-        if isinstance(value, (Varchar, Text)):
-            column: Column = value
+        """
+        :param reverse:
+            By default the value is appended to the column's value. If
+            ``reverse=True`` then the value is prepended to the column's
+            value instead.
+
+        """
+        if isinstance(value, Column):
             if len(column._meta.call_chain) > 0:
                 raise ValueError(
                     "Adding values across joins isn't currently supported."
                 )
-            other_column_name = column._meta.db_column_name
-            if reverse:
-                return QueryString(
-                    Concat.template.format(
-                        value_1=other_column_name, value_2=column_name
-                    )
-                )
-            else:
-                return QueryString(
-                    Concat.template.format(
-                        value_1=column_name, value_2=other_column_name
-                    )
-                )
         elif isinstance(value, str):
-            if reverse:
-                value_1 = QueryString("CAST({} AS text)", value)
-                return QueryString(
-                    Concat.template.format(value_1="{}", value_2=column_name),
-                    value_1,
-                )
-            else:
-                value_2 = QueryString("CAST({} AS text)", value)
-                return QueryString(
-                    Concat.template.format(value_1=column_name, value_2="{}"),
-                    value_2,
-                )
-        else:
+            value = QueryString("CAST({} AS TEXT)", value)
+        elif not isinstance(value, QueryString):
             raise ValueError(
-                "Only str, Varchar columns, and Text columns can be added."
+                "Only str, Column and QueryString values can be added."
             )
 
+        args = [value, column] if reverse else [column, value]
+
+        # We use the concat operator instead of the concat function, because
+        # this is what we historically used, and they treat null values
+        # differently.
+        return QueryString(
+            Concat.template.format(value_1="{}", value_2="{}"), *args
+        )
+
 
 class MathDelegate:
     """
@@ -340,12 +331,13 @@ class Varchar(Column):
 
     def __add__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
-            column_name=self._meta.db_column_name, value=value
+            column=self,
+            value=value,
         )
 
     def __radd__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
-            column_name=self._meta.db_column_name,
+            column=self,
             value=value,
             reverse=True,
         )
@@ -442,12 +434,13 @@ class Text(Column):
 
     def __add__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
-            column_name=self._meta.db_column_name, value=value
+            column=self,
+            value=value,
         )
 
     def __radd__(self, value: t.Union[str, Varchar, Text]) -> QueryString:
         return self.concat_delegate.get_querystring(
-            column_name=self._meta.db_column_name,
+            column=self,
             value=value,
             reverse=True,
         )

{piccolo-1.10.0 → piccolo-1.11.0}/piccolo/query/functions/__init__.py

@@ -1,6 +1,7 @@
 from .aggregate import Avg, Count, Max, Min, Sum
+from .datetime import Day, Extract, Hour, Month, Second, Strftime, Year
 from .math import Abs, Ceil, Floor, Round
-from .string import Length, Lower, Ltrim, Reverse, Rtrim, Upper
+from .string import Concat, Length, Lower, Ltrim, Reverse, Rtrim, Upper
 from .type_conversion import Cast
 
 __all__ = (
@@ -8,16 +9,25 @@ __all__ = (
     "Avg",
     "Cast",
     "Ceil",
+    "Concat",
     "Count",
+    "Day",
+    "Extract",
+    "Extract",
     "Floor",
+    "Hour",
     "Length",
     "Lower",
     "Ltrim",
     "Max",
     "Min",
+    "Month",
     "Reverse",
     "Round",
     "Rtrim",
+    "Second",
+    "Strftime",
     "Sum",
     "Upper",
+    "Year",
 )

piccolo-1.11.0/piccolo/query/functions/datetime.py

@@ -0,0 +1,260 @@
+import typing as t
+
+from piccolo.columns.base import Column
+from piccolo.columns.column_types import (
+    Date,
+    Integer,
+    Time,
+    Timestamp,
+    Timestamptz,
+)
+from piccolo.querystring import QueryString
+
+from .type_conversion import Cast
+
+###############################################################################
+# Postgres / Cockroach
+
+ExtractComponent = t.Literal[
+    "century",
+    "day",
+    "decade",
+    "dow",
+    "doy",
+    "epoch",
+    "hour",
+    "isodow",
+    "isoyear",
+    "julian",
+    "microseconds",
+    "millennium",
+    "milliseconds",
+    "minute",
+    "month",
+    "quarter",
+    "second",
+    "timezone",
+    "timezone_hour",
+    "timezone_minute",
+    "week",
+    "year",
+]
+
+
+class Extract(QueryString):
+    def __init__(
+        self,
+        identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+        datetime_component: ExtractComponent,
+        alias: t.Optional[str] = None,
+    ):
+        """
+        .. note:: This is for Postgres / Cockroach only.
+
+        Extract a date or time component from a ``Date`` / ``Time`` /
+        ``Timestamp`` / ``Timestamptz`` column. For example, getting the month
+        from a timestamp:
+
+        .. code-block:: python
+
+            >>> from piccolo.query.functions import Extract
+            >>> await Concert.select(
+            ...     Extract(Concert.starts, "month", alias="start_month")
+            ... )
+            [{"start_month": 12}]
+
+        :param identifier:
+            Identifies the column.
+        :param datetime_component:
+            The date or time component to extract from the column.
+
+        """
+        if datetime_component.lower() not in t.get_args(ExtractComponent):
+            raise ValueError("The date time component isn't recognised.")
+
+        super().__init__(
+            f"EXTRACT({datetime_component} FROM {{}})",
+            identifier,
+            alias=alias,
+        )
+
+
+###############################################################################
+# SQLite
+
+
+class Strftime(QueryString):
+    def __init__(
+        self,
+        identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+        datetime_format: str,
+        alias: t.Optional[str] = None,
+    ):
+        """
+        .. note:: This is for SQLite only.
+
+        Format a datetime value. For example:
+
+        .. code-block:: python
+
+            >>> from piccolo.query.functions import Strftime
+            >>> await Concert.select(
+            ...     Strftime(Concert.starts, "%Y", alias="start_year")
+            ... )
+            [{"start_month": "2024"}]
+
+        :param identifier:
+            Identifies the column.
+        :param datetime_format:
+            A string describing the output format (see SQLite's
+            `documentation <https://www.sqlite.org/lang_datefunc.html>`_
+            for more info).
+
+        """
+        super().__init__(
+            f"strftime('{datetime_format}', {{}})",
+            identifier,
+            alias=alias,
+        )
+
+
+###############################################################################
+# Database agnostic
+
+
+def _get_engine_type(identifier: t.Union[Column, QueryString]) -> str:
+    if isinstance(identifier, Column):
+        return identifier._meta.engine_type
+    elif isinstance(identifier, QueryString) and (
+        columns := identifier.columns
+    ):
+        return columns[0]._meta.engine_type
+    else:
+        raise ValueError("Unable to determine the engine type")
+
+
+def _extract_component(
+    identifier: t.Union[Date, Time, Timestamp, Timestamptz, QueryString],
+    sqlite_format: str,
+    postgres_format: ExtractComponent,
+    alias: t.Optional[str],
+) -> QueryString:
+    engine_type = _get_engine_type(identifier=identifier)
+
+    return Cast(
+        (
+            Strftime(
+                identifier=identifier,
+                datetime_format=sqlite_format,
+            )
+            if engine_type == "sqlite"
+            else Extract(
+                identifier=identifier,
+                datetime_component=postgres_format,
+            )
+        ),
+        Integer(),
+        alias=alias,
+    )
+
+
+def Year(
+    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the year as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%Y",
+        postgres_format="year",
+        alias=alias,
+    )
+
+
+def Month(
+    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the month as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%m",
+        postgres_format="month",
+        alias=alias,
+    )
+
+
+def Day(
+    identifier: t.Union[Date, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the day as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%d",
+        postgres_format="day",
+        alias=alias,
+    )
+
+
+def Hour(
+    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the hour as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%H",
+        postgres_format="hour",
+        alias=alias,
+    )
+
+
+def Minute(
+    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the minute as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%M",
+        postgres_format="minute",
+        alias=alias,
+    )
+
+
+def Second(
+    identifier: t.Union[Time, Timestamp, Timestamptz, QueryString],
+    alias: t.Optional[str] = None,
+) -> QueryString:
+    """
+    Extract the second as an integer.
+    """
+    return _extract_component(
+        identifier=identifier,
+        sqlite_format="%S",
+        postgres_format="second",
+        alias=alias,
+    )
+
+
+__all__ = (
+    "Extract",
+    "Strftime",
+    "Year",
+    "Month",
+    "Day",
+    "Hour",
+    "Minute",
+    "Second",
+)

piccolo-1.11.0/piccolo/query/functions/string.py

@@ -0,0 +1,118 @@
+"""
+These functions mirror their counterparts in the Postgresql docs:
+
+https://www.postgresql.org/docs/current/functions-string.html
+
+"""
+
+import typing as t
+
+from piccolo.columns.base import Column
+from piccolo.columns.column_types import Text, Varchar
+from piccolo.querystring import QueryString
+
+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"
+
+
+class Concat(QueryString):
+    def __init__(
+        self,
+        *args: t.Union[Column, QueryString, str],
+        alias: t.Optional[str] = None,
+    ):
+        """
+        Concatenate multiple values into a single string.
+
+        .. note::
+            Null values are ignored, so ``null + '!!!'`` returns ``!!!``,
+            not ``null``.
+
+        .. warning::
+            For SQLite, this is only available in version 3.44.0 and above.
+
+        """
+        if len(args) < 2:
+            raise ValueError("At least two values must be passed in.")
+
+        placeholders = ", ".join("{}" for _ in args)
+
+        processed_args: t.List[t.Union[QueryString, Column]] = []
+
+        for arg in args:
+            if isinstance(arg, str) or (
+                isinstance(arg, Column)
+                and not isinstance(arg, (Varchar, Text))
+            ):
+                processed_args.append(QueryString("CAST({} AS TEXT)", arg))
+            else:
+                processed_args.append(arg)
+
+        super().__init__(
+            f"CONCAT({placeholders})", *processed_args, alias=alias
+        )
+
+
+__all__ = (
+    "Length",
+    "Lower",
+    "Ltrim",
+    "Reverse",
+    "Rtrim",
+    "Upper",
+    "Concat",
+)

{piccolo-1.10.0 → piccolo-1.11.0}/piccolo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piccolo
-Version: 1.10.0
+Version: 1.11.0
 Summary: A fast, user friendly ORM and query builder which supports asyncio.
 Home-page: https://github.com/piccolo-orm/piccolo
 Author: Daniel Townsend

{piccolo-1.10.0 → piccolo-1.11.0}/piccolo.egg-info/SOURCES.txt

@@ -162,6 +162,7 @@ piccolo/query/proxy.py
 piccolo/query/functions/__init__.py
 piccolo/query/functions/aggregate.py
 piccolo/query/functions/base.py
+piccolo/query/functions/datetime.py
 piccolo/query/functions/math.py
 piccolo/query/functions/string.py
 piccolo/query/functions/type_conversion.py
@@ -315,6 +316,7 @@ tests/query/test_querystring.py
 tests/query/test_slots.py
 tests/query/functions/__init__.py
 tests/query/functions/base.py
+tests/query/functions/test_datetime.py
 tests/query/functions/test_functions.py
 tests/query/functions/test_math.py
 tests/query/functions/test_string.py

piccolo-1.11.0/tests/query/functions/test_datetime.py

@@ -0,0 +1,114 @@
+import datetime
+
+from piccolo.columns import Timestamp
+from piccolo.query.functions.datetime import (
+    Day,
+    Extract,
+    Hour,
+    Minute,
+    Month,
+    Second,
+    Strftime,
+    Year,
+)
+from piccolo.table import Table
+from tests.base import engines_only, sqlite_only
+
+from .base import FunctionTest
+
+
+class Concert(Table):
+    starts = Timestamp()
+
+
+class DatetimeTest(FunctionTest):
+    tables = [Concert]
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.concert = Concert(
+            {
+                Concert.starts: datetime.datetime(
+                    year=2024, month=6, day=14, hour=23, minute=46, second=10
+                )
+            }
+        )
+        self.concert.save().run_sync()
+
+
+@engines_only("postgres", "cockroach")
+class TestExtract(DatetimeTest):
+    def test_extract(self):
+        self.assertEqual(
+            Concert.select(
+                Extract(Concert.starts, "year", alias="starts_year")
+            ).run_sync(),
+            [{"starts_year": self.concert.starts.year}],
+        )
+
+    def test_invalid_format(self):
+        with self.assertRaises(ValueError):
+            Extract(
+                Concert.starts,
+                "abc123",  # type: ignore
+                alias="starts_year",
+            )
+
+
+@sqlite_only
+class TestStrftime(DatetimeTest):
+    def test_strftime(self):
+        self.assertEqual(
+            Concert.select(
+                Strftime(Concert.starts, "%Y", alias="starts_year")
+            ).run_sync(),
+            [{"starts_year": str(self.concert.starts.year)}],
+        )
+
+
+class TestDatabaseAgnostic(DatetimeTest):
+    def test_year(self):
+        self.assertEqual(
+            Concert.select(
+                Year(Concert.starts, alias="starts_year")
+            ).run_sync(),
+            [{"starts_year": self.concert.starts.year}],
+        )
+
+    def test_month(self):
+        self.assertEqual(
+            Concert.select(
+                Month(Concert.starts, alias="starts_month")
+            ).run_sync(),
+            [{"starts_month": self.concert.starts.month}],
+        )
+
+    def test_day(self):
+        self.assertEqual(
+            Concert.select(Day(Concert.starts, alias="starts_day")).run_sync(),
+            [{"starts_day": self.concert.starts.day}],
+        )
+
+    def test_hour(self):
+        self.assertEqual(
+            Concert.select(
+                Hour(Concert.starts, alias="starts_hour")
+            ).run_sync(),
+            [{"starts_hour": self.concert.starts.hour}],
+        )
+
+    def test_minute(self):
+        self.assertEqual(
+            Concert.select(
+                Minute(Concert.starts, alias="starts_minute")
+            ).run_sync(),
+            [{"starts_minute": self.concert.starts.minute}],
+        )
+
+    def test_second(self):
+        self.assertEqual(
+            Concert.select(
+                Second(Concert.starts, alias="starts_second")
+            ).run_sync(),
+            [{"starts_second": self.concert.starts.second}],
+        )