TypeDAL 3.17.0__tar.gz → 3.17.2__tar.gz

{typedal-3.17.0 → typedal-3.17.2}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!--next-version-placeholder-->
 
+## v3.17.2 (2025-09-24)
+
+### Fix
+
+* Support .orderby as alias for .select(orderby= ([`be561c5`](https://github.com/trialandsuccess/TypeDAL/commit/be561c500c573a3a45b22f250fe1d2b473b56cc3))
+
+## v3.17.1 (2025-09-20)
+
+### Fix
+
+* Smarter adapt so Fields and Tables can also be safely inserted in `sql_expression` ([`d5cad6a`](https://github.com/trialandsuccess/TypeDAL/commit/d5cad6a13ddf50ec6e5762075fbeae1e44067da6))
+
 ## v3.17.0 (2025-09-20)
 
 ### Feature

{typedal-3.17.0 → typedal-3.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypeDAL
-Version: 3.17.0
+Version: 3.17.2
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues

{typedal-3.17.0 → typedal-3.17.2}/src/typedal/__about__.py

@@ -5,4 +5,4 @@ This file contains the Version info for this package.
 # SPDX-FileCopyrightText: 2023-present Robin van der Noord <robinvandernoord@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "3.17.0"
+__version__ = "3.17.2"

{typedal-3.17.0 → typedal-3.17.2}/src/typedal/core.py

@@ -60,6 +60,7 @@ from .types import (
     FieldSettings,
     Metadata,
     OpRow,
+    OrderBy,
     PaginateDict,
     Pagination,
     Query,
@@ -835,10 +836,10 @@ class TypeDAL(pydal.DAL):  # type: ignore
     def sql_expression(
         self,
         sql_fragment: str,
-        *raw_args: str,
+        *raw_args: Any,
         output_type: str | None = None,
-        **raw_kwargs: str,
-    ) -> str:
+        **raw_kwargs: Any,
+    ) -> Expression:
         """
         Creates a pydal Expression object representing a raw SQL fragment.
 
@@ -1146,6 +1147,12 @@ class TableMeta(type):
         """
         return QueryBuilder(self).where(*a, **kw)
 
+    def orderby(self: Type[T_MetaInstance], *fields: OrderBy) -> "QueryBuilder[T_MetaInstance]":
+        """
+        See QueryBuilder.orderby!
+        """
+        return QueryBuilder(self).orderby(*fields)
+
     def cache(self: Type[T_MetaInstance], *deps: Any, **kwargs: Any) -> "QueryBuilder[T_MetaInstance]":
         """
         See QueryBuilder.cache!
@@ -2678,6 +2685,22 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         """
         return self._extend(select_args=list(fields), select_kwargs=options)
 
+    def orderby(self, *fields: OrderBy) -> "QueryBuilder[T_MetaInstance]":
+        """
+        Order the query results by specified fields.
+
+        Args:
+            fields: field(s) to order by. Supported:
+                table.name - sort by name, ascending
+                ~table.name - sort by name, descending
+                <random> - sort randomly
+                table.name|table.id - sort by two fields (first name, then id)
+
+        Returns:
+            QueryBuilder: A new QueryBuilder instance with the ordering applied.
+        """
+        return self.select(orderby=fields)
+
     def where(
         self,
         *queries_or_lambdas: Query | typing.Callable[[Type[T_MetaInstance]], Query] | dict[str, Any],

{typedal-3.17.0 → typedal-3.17.2}/src/typedal/helpers.py

@@ -337,6 +337,26 @@ class classproperty:
         return self.fget(owner)
 
 
+def smarter_adapt(db: TypeDAL, placeholder: Any) -> str:
+    """
+    Smarter adaptation of placeholder to quote if needed.
+
+    Args:
+        db: Database object.
+        placeholder: Placeholder object.
+
+    Returns:
+        Quoted placeholder if needed, except for numbers (smart_adapt logic)
+            or fields/tables (use already quoted rname).
+    """
+    return typing.cast(
+        str,
+        getattr(placeholder, "sql_shortref", None)  # for tables
+        or getattr(placeholder, "sqlsafe", None)  # for fields
+        or db._adapter.smart_adapt(placeholder),  # for others
+    )
+
+
 def sql_escape(db: TypeDAL, sql_fragment: str, *raw_args: Any, **raw_kwargs: Any) -> str:
     """
     Generates escaped SQL fragments with placeholders.
@@ -358,18 +378,18 @@ def sql_escape(db: TypeDAL, sql_fragment: str, *raw_args: Any, **raw_kwargs: Any
 
     elif raw_args:
         # list
-        return sql_fragment % tuple(db._adapter.adapt(placeholder) for placeholder in raw_args)
+        return sql_fragment % tuple(smarter_adapt(db, placeholder) for placeholder in raw_args)
     else:
         # dict
-        return sql_fragment % {key: db._adapter.adapt(placeholder) for key, placeholder in raw_kwargs.items()}
+        return sql_fragment % {key: smarter_adapt(db, placeholder) for key, placeholder in raw_kwargs.items()}
 
 
 def sql_expression(
     db: TypeDAL,
     sql_fragment: str,
-    *raw_args: str,
+    *raw_args: Any,
     output_type: str | None = None,
-    **raw_kwargs: str,
+    **raw_kwargs: Any,
 ) -> Expression:
     """
     Creates a pydal Expression object representing a raw SQL fragment.

{typedal-3.17.0 → typedal-3.17.2}/src/typedal/types.py

@@ -218,6 +218,8 @@ class CacheFn(typing.Protocol):
 CacheModel = typing.Callable[[str, CacheFn, int], Rows]
 CacheTuple = tuple[CacheModel, int]
 
+OrderBy: typing.TypeAlias = Expression | str
+
 
 class SelectKwargs(TypedDict, total=False):
     """
@@ -226,7 +228,7 @@ class SelectKwargs(TypedDict, total=False):
 
     join: Optional[list[Expression]]
     left: Optional[list[Expression]]
-    orderby: Optional[Expression | str | Table]
+    orderby: OrderBy | typing.Iterable[OrderBy] | None
     limitby: Optional[tuple[int, int]]
     distinct: bool | Field | Expression
     orderby_on_limitby: bool

{typedal-3.17.0 → typedal-3.17.2}/tests/test_helpers.py

@@ -223,7 +223,7 @@ def test_sql_expression():
     expr1 = sql_expression(database, "date('now') > %s", "2025-01-01")
     expr2 = database.sql_expression("date('now') > %(value)s", value="2025-01-01")
 
-    assert expr1 == expr2
+    assert str(expr1) == str(expr2)
     assert str(expr1) == "date('now') > '2025-01-01'"
     # past -> should yield result
     result = database(expr1).select(TestSqlExpression.value, expr2)[0]
@@ -240,3 +240,7 @@ def test_sql_expression():
     # far future -> should not yield result
     result3 = database(expr3).select(TestSqlExpression.value, expr3).as_list()
     assert not result3
+
+    # test quoting fields and tables:
+    assert str(database.sql_expression("LOWER(%s)", TestSqlExpression.value)) == 'LOWER("test_sql_expression"."value")'
+    assert str(database.sql_expression("LOWER(%s.value)", TestSqlExpression)) == 'LOWER("test_sql_expression".value)'

{typedal-3.17.0 → typedal-3.17.2}/tests/test_query_builder.py

@@ -447,7 +447,7 @@ def test_orderby():
 
     assert base_qt.count() == 5
 
-    rows1 = base_qt.select(orderby=TestQueryTable.id).paginate(limit=3, page=1)
+    rows1 = base_qt.orderby(TestQueryTable.id).paginate(limit=3, page=1)
     rows2 = base_qt.select(orderby=TestQueryTable.id, limitby=(0, 3)).collect()
     assert [_.id for _ in rows1] == [_.id for _ in rows2] == [1, 2, 3]
 
@@ -467,10 +467,12 @@ def test_orderby():
     rows2 = joined_qt.select(orderby=TestQueryTable.id, limitby=(0, 3)).collect()
     assert [_.id for _ in rows1] == [_.id for _ in rows2] == [1, 2, 3]
 
-    rows1 = joined_qt.select(orderby=TestQueryTable.number).paginate(limit=3, page=1)
-    rows2 = joined_qt.select(orderby=TestQueryTable.number, limitby=(0, 3)).collect()
+    rows1 = joined_qt.orderby(TestQueryTable.number, TestQueryTable.other).paginate(limit=3, page=1)
+    rows2 = joined_qt.select(orderby=TestQueryTable.number | TestQueryTable.other, limitby=(0, 3)).collect()
     assert [_.number for _ in rows1] == [_.number for _ in rows2] == [0, 1, 2]
 
+    assert rows1.metadata["sql"] == rows2.metadata["sql"]
+
     rows1 = joined_qt.select(orderby=~TestQueryTable.number).paginate(limit=3, page=1)
     rows2 = joined_qt.select(orderby=~TestQueryTable.number, limitby=(0, 3)).collect()
     assert [_.number for _ in rows1] == [_.number for _ in rows2] == [4, 3, 2]
@@ -479,6 +481,11 @@ def test_orderby():
     rows2 = joined_qt.select(orderby=~TestQueryTable.number, limitby=(0, 100)).collect()
     assert [_.number for _ in rows1] == [_.number for _ in rows2] == [4, 3, 2, 1, 0]
 
+    assert (
+        TestQueryTable.orderby(TestQueryTable.yet_another, TestQueryTable.number).to_sql()
+        == TestQueryTable.select(orderby=TestQueryTable.yet_another | TestQueryTable.number).to_sql()
+    )
+
 
 def test_execute():
     _setup_data()