1411 Replace SelectRaw, GroupByRaw and OrderByRaw with QueryString (#1412)

* replace SelectRaw, GroupByRaw and OrderByRaw with QueryString

* fix typo in docstring

Author: dantownsend

docs/src/piccolo/query_clauses/group_by.rst

@@ -42,22 +42,23 @@ These work the same as ``Count``. See :ref:`aggregate functions <AggregateFuncti
 
 -------------------------------------------------------------------------------
 
-``GroupByRaw``
---------------
+Advanced
+--------
 
-For more complex cases, use ``GroupByRaw`` to group by a raw SQL expression or
-an alias created by ``SelectRaw``. For example:
+For more complex cases, use :class:`QueryString <piccolo.querystring.QueryString>`
+to group by a raw SQL expression or an alias created in a select query. For
+example:
 
 .. code-block:: python
 
-    from piccolo.query import GroupByRaw, SelectRaw
     from piccolo.query.functions.aggregate import Count
+    from piccolo.querystring import QueryString
 
     await Band.select(
-        SelectRaw("DATE(created_at) AS created_date"),
+        QueryString("DATE(created_at) AS created_date"),
         Count(),
     ).group_by(
-        GroupByRaw("created_date")
+        QueryString("created_date")
     )
 
 As with other raw query helpers, only use trusted SQL strings.

docs/src/piccolo/query_clauses/order_by.rst

@@ -63,25 +63,29 @@ descending, then you can do so using multiple ``order_by`` statements:
         ascending=False
     )
 
-``OrderByRaw``
-~~~~~~~~~~~~~~
+Advanced
+~~~~~~~~
 
 SQL's ``ORDER BY`` clause is surprisingly rich in functionality, and there may
 be situations where you want to specify the ``ORDER BY`` explicitly using SQL.
-To do this use ``OrderByRaw``.
+To do this use :class:`QueryString <piccolo.querystring.QueryString>`.
 
 In the example below, we are ordering the results randomly:
 
 .. code-block:: python
 
-    from piccolo.query import OrderByRaw
+    from piccolo.querystring import QueryString
 
     await Band.select(Band.name).order_by(
-        OrderByRaw('random()'),
+        QueryString('random()'),
     )
 
 The above is equivalent to the following SQL:
 
 .. code-block:: sql
 
     SELECT "band"."name" FROM band ORDER BY random() ASC
+
+.. note::
+    We used to use ``OrderByRaw`` for this (which still works for
+    backwards compatibility).

docs/src/piccolo/query_types/select.rst

@@ -293,8 +293,8 @@ And can use aliases for aggregate functions like this:
 
 -------------------------------------------------------------------------------
 
-SelectRaw
----------
+Advanced
+--------
 
 In certain situations you may want to have raw SQL in your select query.
 
@@ -303,16 +303,21 @@ isn't supported by Piccolo:
 
 .. code-block:: python
 
-    from piccolo.query import SelectRaw
+    from piccolo.querystring import QueryString
 
     >>> await Band.select(
     ...     Band.name,
-    ...     SelectRaw("log(popularity) AS log_popularity")
+    ...     QueryString("log(popularity) AS log_popularity")
     ... )
     [{'name': 'Pythonistas', 'log_popularity': 3.0}]
 
 .. warning:: Only use SQL that you trust.
 
+.. note::
+    We used to use ``SelectRaw`` for this, which still works, but you can just
+    pass :class:`QueryString <piccolo.querystring.QueryString>` in directly
+    now.
+
 -------------------------------------------------------------------------------
 
 Query clauses

piccolo/query/__init__.py

@@ -17,8 +17,8 @@
     TableExists,
     Update,
 )
-from .methods.select import SelectRaw
-from .mixins import GroupByRaw, OrderByRaw
+from .methods.select import SelectRaw  # for backwards compatibility
+from .mixins import OrderByRaw  # for backwards compatibility
 
 __all__ = [
     "Alter",
@@ -29,7 +29,6 @@
     "Delete",
     "DropIndex",
     "Exists",
-    "GroupByRaw",
     "Insert",
     "Max",
     "Min",

piccolo/query/methods/objects.py

@@ -27,7 +27,6 @@
     LockStrength,
     OffsetDelegate,
     OrderByDelegate,
-    OrderByRaw,
     OutputDelegate,
     PrefetchDelegate,
     WhereDelegate,
@@ -375,9 +374,9 @@ def offset(self: Self, number: int) -> Self:
         return self
 
     def order_by(
-        self: Self, *columns: Union[Column, str, OrderByRaw], ascending=True
+        self: Self, *columns: Union[Column, str, QueryString], ascending=True
     ) -> Self:
-        _columns: list[Union[Column, OrderByRaw]] = []
+        _columns: list[Union[Column, QueryString]] = []
         for column in columns:
             if isinstance(column, str):
                 _columns.append(self.table._meta.get_column_by_name(column))

piccolo/query/methods/select.py

@@ -27,13 +27,11 @@
     ColumnsDelegate,
     DistinctDelegate,
     GroupByDelegate,
-    GroupByRaw,
     LimitDelegate,
     LockRowsDelegate,
     LockStrength,
     OffsetDelegate,
     OrderByDelegate,
-    OrderByRaw,
     OutputDelegate,
     WhereDelegate,
 )
@@ -57,26 +55,24 @@
 )
 
 
-class SelectRaw(Selectable):
-    def __init__(self, sql: str, *args: Any) -> None:
-        """
-        Execute raw SQL in your select query.
+class SelectRaw(QueryString):
+    """
+    Here for backwards compatibility - just use
+    :class:`piccolo.querystring.QueryString` directly.
 
-        .. code-block:: python
+    Execute raw SQL in your select query.
 
-            >>> await Band.select(
-            ...     Band.name,
-            ...     SelectRaw("log(popularity) AS log_popularity")
-            ... )
-            [{'name': 'Pythonistas', 'log_popularity': 3.0}]
+    .. code-block:: python
 
-        """
-        self.querystring = QueryString(sql, *args)
+        >>> await Band.select(
+        ...     Band.name,
+        ...     SelectRaw("log(popularity) AS log_popularity")
+        ... )
+        [{'name': 'Pythonistas', 'log_popularity': 3.0}]
 
-    def get_select_string(
-        self, engine_type: str, with_alias: bool = True
-    ) -> QueryString:
-        return self.querystring
+    """
+
+    pass
 
 
 OptionalDict = Optional[dict[str, Any]]
@@ -205,14 +201,17 @@ def distinct(self: Self, *, on: Optional[Sequence[Column]] = None) -> Self:
         self.distinct_delegate.distinct(enabled=True, on=on)
         return self
 
-    def group_by(self: Self, *columns: Union[Column, str, GroupByRaw]) -> Self:
+    def group_by(
+        self: Self, *columns: Union[Column, str, QueryString]
+    ) -> Self:
         """
         :param columns:
             Either a :class:`piccolo.columns.base.Column` instance, a string
-            representing a column name, or :class:`piccolo.query.GroupByRaw`
-            for grouping by a raw SQL expression or select alias.
+            representing a column name, or
+            :class:`piccolo.querystring.QueryString` for grouping by a raw SQL
+            expression or select alias.
         """
-        _columns: list[Union[Column, GroupByRaw]] = []
+        _columns: list[Union[Column, QueryString]] = []
         for column in columns:
             if isinstance(column, str):
                 _columns.append(self.table._meta.get_column_by_name(column))
@@ -413,16 +412,16 @@ async def response_handler(self, response):
             return response
 
     def order_by(
-        self: Self, *columns: Union[Column, str, OrderByRaw], ascending=True
+        self: Self, *columns: Union[Column, str, QueryString], ascending=True
     ) -> Self:
         """
         :param columns:
             Either a :class:`piccolo.columns.base.Column` instance, a string
-            representing a column name, or :class:`piccolo.query.OrderByRaw`
-            which allows you for complex use cases like
-            ``OrderByRaw('random()')``.
+            representing a column name, or
+            :class:`piccolo.querystring.QueryString` which allows you for
+            complex use cases like ``QueryString('random()')``.
         """
-        _columns: list[Union[Column, OrderByRaw]] = []
+        _columns: list[Union[Column, QueryString]] = []
         for column in columns:
             if isinstance(column, str):
                 _columns.append(self.table._meta.get_column_by_name(column))

piccolo/query/mixins.py

@@ -142,18 +142,20 @@ def __str__(self) -> str:
         return self.querystring.__str__()
 
 
-@dataclass
-class OrderByRaw:
-    __slots__ = ("sql",)
+class OrderByRaw(QueryString):
+    """
+    Here for backwards compatibility - just use
+    :class:`piccolo.querystring.QueryString` directly.
+    """
 
-    sql: str
+    pass
 
 
 @dataclass
 class OrderByItem:
     __slots__ = ("columns", "ascending")
 
-    columns: Sequence[Union[Column, OrderByRaw]]
+    columns: Sequence[Union[Column, QueryString]]
     ascending: bool
 
 
@@ -164,19 +166,24 @@ class OrderBy:
     @property
     def querystring(self) -> QueryString:
         order_by_strings: list[str] = []
+        querystring_args = []
         for order_by_item in self.order_by_items:
             order = "ASC" if order_by_item.ascending else "DESC"
             for column in order_by_item.columns:
                 if isinstance(column, Column):
                     expression = column._meta.get_full_name(with_alias=False)
-                elif isinstance(column, OrderByRaw):
-                    expression = column.sql
+                elif isinstance(column, QueryString):
+                    expression = "{}"
+                    querystring_args.append(column)
                 else:
                     raise ValueError("Unrecognised order_by")
 
                 order_by_strings.append(f"{expression} {order}")
 
-        return QueryString(f" ORDER BY {', '.join(order_by_strings)}")
+        return QueryString(
+            f" ORDER BY {', '.join(order_by_strings)}",
+            *querystring_args,
+        )
 
     def __str__(self):
         return self.querystring.__str__()
@@ -291,7 +298,7 @@ def get_order_by_columns(self) -> list[Column]:
             if isinstance(i, Column)
         ]
 
-    def order_by(self, *columns: Union[Column, OrderByRaw], ascending=True):
+    def order_by(self, *columns: Union[Column, QueryString], ascending=True):
         if len(columns) < 1:
             raise ValueError("At least one column must be passed to order_by.")
 
@@ -592,33 +599,31 @@ def offset(self, number: int = 0):
         self._offset = Offset(number)
 
 
-@dataclass
-class GroupByRaw:
-    __slots__ = ("sql",)
-
-    sql: str
-
-
 @dataclass
 class GroupBy:
     __slots__ = ("columns",)
 
-    columns: Sequence[Union[Column, GroupByRaw]]
+    columns: Sequence[Union[Column, QueryString]]
 
     @property
     def querystring(self) -> QueryString:
         column_names: list[str] = []
+        querystring_args = []
         for column in self.columns:
             if isinstance(column, Column):
                 column_names.append(
                     column._meta.get_full_name(with_alias=False)
                 )
-            elif isinstance(column, GroupByRaw):
-                column_names.append(column.sql)
+            elif isinstance(column, QueryString):
+                column_names.append("{}")
+                querystring_args.append(column)
             else:  # pragma: no cover
                 raise ValueError("Unrecognised group_by")
 
-        return QueryString(f" GROUP BY {', '.join(column_names)}")
+        return QueryString(
+            f" GROUP BY {', '.join(column_names)}",
+            *querystring_args,
+        )
 
     def __str__(self):
         return self.querystring.__str__()
@@ -635,7 +640,7 @@ class GroupByDelegate:
 
     _group_by: Optional[GroupBy] = None
 
-    def group_by(self, *columns: Union[Column, GroupByRaw]):
+    def group_by(self, *columns: Union[Column, QueryString]):
         self._group_by = GroupBy(columns=columns)