Merge branch 'master' into pr/1364

Author: dantownsend

docs/src/piccolo/api_reference/index.rst

@@ -145,3 +145,15 @@ QueryString
 .. currentmodule:: piccolo.querystring
 
 .. autoclass:: QueryString
+
+-------------------------------------------------------------------------------
+
+Custom Types
+------------
+
+BasicTypes
+~~~~~~~~~~
+
+.. currentmodule:: piccolo.custom_types
+
+.. autoclass:: BasicTypes

docs/src/piccolo/functions/conditional.rst

@@ -0,0 +1,9 @@
+Conditional functions
+=====================
+
+.. currentmodule:: piccolo.query.functions.conditional
+
+Coalesce
+--------
+
+.. autoclass:: Coalesce

docs/src/piccolo/functions/index.rst

@@ -13,6 +13,7 @@ Functions can be used to modify how queries are run, and what is returned.
     ./basic_usage
     ./aggregate
     ./array
+    ./conditional
     ./datetime
     ./math
     ./string

piccolo/apps/playground/commands/run.py

@@ -153,7 +153,7 @@ class Album(Table):
     id: Serial
     name = Varchar()
     band = ForeignKey(Band)
-    release_date = Date()
+    release_date = Date(null=True, default=None)
     recorded_at = ForeignKey(RecordingStudio)
     awards = Array(Varchar())
 
@@ -323,6 +323,15 @@ def populate():
                 Album.awards: ["Mercury Prize 2022"],
             }
         ),
+        Album(
+            {
+                Album.name: "Awesome album 4",
+                Album.recorded_at: recording_studio_2,
+                Album.band: rustaceans,
+                Album.release_date: None,
+                Album.awards: [],
+            }
+        ),
     ).run_sync()
 
     genres = Genre.insert(

piccolo/columns/base.py

@@ -46,6 +46,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     from piccolo.columns.column_types import ForeignKey
+    from piccolo.query.functions.conditional import Coalesce
     from piccolo.query.methods.select import Select
     from piccolo.table import Table
 
@@ -676,6 +677,11 @@ def ilike(self, value: str) -> Where:
     def not_like(self, value: str) -> Where:
         return Where(column=self, value=value, operator=NotLike)
 
+    def __or__(self, value) -> Coalesce:
+        from piccolo.query.functions.conditional import Coalesce
+
+        return Coalesce(self, value)
+
     def __lt__(self, value) -> Where:
         return Where(column=self, value=value, operator=LessThan)
 

piccolo/query/functions/__init__.py

@@ -6,6 +6,7 @@
     ArrayRemove,
     ArrayReplace,
 )
+from .conditional import Coalesce
 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
@@ -16,6 +17,7 @@
     "Avg",
     "Cast",
     "Ceil",
+    "Coalesce",
     "Concat",
     "Count",
     "Day",

piccolo/query/functions/conditional.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Union
+
+from piccolo.custom_types import BasicTypes
+from piccolo.querystring import QueryString
+
+if TYPE_CHECKING:
+    from piccolo.columns import Column
+
+
+class Coalesce(QueryString):
+    def __init__(
+        self,
+        *args: Union[Column, QueryString, BasicTypes],
+        alias: Optional[str] = None,
+    ):
+        """
+        Returns the first non-null value.
+
+        Here's an example to try in the playground::
+
+            >>> await Album.select(Album.release_date)
+            [
+                {'release_date': datetime.date(2021, 1, 1)},
+                {'release_date': datetime.date(2025, 1, 1)},
+                {'release_date': datetime.date(2022, 2, 2)},
+                {'release_date': None}
+            ]
+
+        One of the values is null - we can specify a fallback value::
+
+            >>> from piccolo.functions.conditional import Coalesce
+            >>> await Album.select(
+            ...     Coalesce(Album.release_date, datetime.date(2050, 1, 1))
+            ... )
+            [
+                {'release_date': datetime.date(2021, 1, 1)},
+                {'release_date': datetime.date(2025, 1, 1)},
+                {'release_date': datetime.date(2022, 2, 2)},
+                {'release_date': datetime.date(2050, 1, 1)}
+            ]
+
+        Or us this abbreviated syntax::
+
+            >>> await Album.select(
+            ...     Album.release_date | datetime.date(2050, 1, 1)
+            ... )
+            [
+                {'release_date': datetime.date(2021, 1, 1)},
+                {'release_date': datetime.date(2025, 1, 1)},
+                {'release_date': datetime.date(2022, 2, 2)},
+                {'release_date': datetime.date(2050, 1, 1)}
+            ]
+
+        """
+        if len(args) < 2:
+            raise ValueError("At least two values must be passed in.")
+
+        #######################################################################
+        # Preserve the original alias from the column.
+
+        from piccolo.columns import Column
+
+        first_arg = args[0]
+
+        if isinstance(first_arg, Column):
+            alias = (
+                alias
+                or first_arg._alias
+                or first_arg._meta.get_default_alias()
+            )
+        elif isinstance(first_arg, QueryString):
+            alias = alias or first_arg._alias
+
+        #######################################################################
+
+        placeholders = ", ".join("{}" for _ in args)
+
+        super().__init__(f"COALESCE({placeholders})", *args, alias=alias)

piccolo/querystring.py

@@ -275,6 +275,11 @@ def eq(self, value) -> QueryString:
     def ne(self, value) -> QueryString:
         return self.__ne__(value)
 
+    def __or__(self, value) -> QueryString:
+        from piccolo.query.functions.conditional import Coalesce
+
+        return Coalesce(self, value, alias=self._alias)
+
     def __add__(self, value) -> QueryString:
         return QueryString("{} + {}", self, value)
 

tests/query/functions/test_conditional.py

@@ -0,0 +1,25 @@
+from piccolo.columns import Integer
+from piccolo.query.functions.conditional import Coalesce
+from piccolo.table import Table
+from piccolo.testing.test_case import AsyncTableTest
+
+
+class Band(Table):
+    popularity = Integer(null=True, default=None)
+
+
+class TestCoalesce(AsyncTableTest):
+
+    tables = [Band]
+
+    async def asyncSetUp(self):
+        await super().asyncSetUp()
+        await Band({Band.popularity: None}).save()
+
+    async def test_coalesce(self):
+        response = await Band.select(Coalesce(Band.popularity, 10))
+        self.assertListEqual(response, [{"popularity": 10}])
+
+    async def test_coalesce_pipe_syntax(self):
+        response = await Band.select(Band.popularity | 10)
+        self.assertListEqual(response, [{"popularity": 10}])