TypeDAL 3.16.5__tar.gz → 3.17.1__tar.gz

{typedal-3.16.5 → typedal-3.17.1}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!--next-version-placeholder-->
 
+## 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
+
+* Improved Expression support via `db.sql_expression` for more flexibility ([`2892aa4`](https://github.com/trialandsuccess/TypeDAL/commit/2892aa452a0b9563ff742a2a7a00927b89b440b9))
+
 ## v3.16.5 (2025-09-08)
 
 ### Fix

{typedal-3.16.5 → typedal-3.17.1}/PKG-INFO

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

{typedal-3.16.5 → typedal-3.17.1}/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.16.5"
+__version__ = "3.17.1"

typedal-3.17.1/src/typedal/__init__.py

@@ -0,0 +1,30 @@
+"""
+TypeDAL Library.
+"""
+
+from . import fields
+from .core import (
+    Relationship,
+    TypeDAL,
+    TypedField,
+    TypedRows,
+    TypedTable,
+    relationship,
+)
+from .helpers import sql_expression
+
+try:
+    from .for_py4web import DAL as P4W_DAL
+except ImportError:  # pragma: no cover
+    P4W_DAL = None  # type: ignore
+
+__all__ = [
+    "Relationship",
+    "TypeDAL",
+    "TypedField",
+    "TypedRows",
+    "TypedTable",
+    "fields",
+    "relationship",
+    "sql_expression",
+]

{typedal-3.16.5 → typedal-3.17.1}/src/typedal/cli.py

@@ -392,7 +392,8 @@ def fake_migrations(
 
     previously_migrated = (
         db(
-            db.ewh_implemented_features.name.belongs(to_fake) & (db.ewh_implemented_features.installed == True)  # noqa E712
+            db.ewh_implemented_features.name.belongs(to_fake)
+            & (db.ewh_implemented_features.installed == True)  # noqa E712
         )
         .select(db.ewh_implemented_features.name)
         .column("name")

{typedal-3.16.5 → typedal-3.17.1}/src/typedal/core.py

@@ -25,10 +25,12 @@ from typing import Any, Optional, Type
 
 import pydal
 from pydal._globals import DEFAULT
-from pydal.objects import Field as _Field
-from pydal.objects import Query as _Query
+
+# from pydal.objects import Field as _Field
+# from pydal.objects import Query as _Query
 from pydal.objects import Row
-from pydal.objects import Table as _Table
+
+# from pydal.objects import Table as _Table
 from typing_extensions import Self, Unpack
 
 from .config import TypeDALConfig, load_config
@@ -45,6 +47,7 @@ from .helpers import (
     looks_like,
     mktable,
     origin_is_subclass,
+    sql_expression,
     to_snake,
     unwrap_type,
 )
@@ -71,7 +74,7 @@ from .types import (
 
 # use typing.cast(type, ...) to make mypy happy with unions
 T_annotation = Type[Any] | types.UnionType
-T_Query = typing.Union["Table", Query, bool, None, "TypedTable", Type["TypedTable"]]
+T_Query = typing.Union["Table", Query, bool, None, "TypedTable", Type["TypedTable"], Expression]
 T_Value = typing.TypeVar("T_Value")  # actual type of the Field (via Generic)
 T_MetaInstance = typing.TypeVar("T_MetaInstance", bound="TypedTable")  # bound="TypedTable"; bound="TableMeta"
 T = typing.TypeVar("T")
@@ -132,7 +135,7 @@ class Relationship(typing.Generic[To_Type]):
     Define a relationship to another table.
     """
 
-    _type: To_Type
+    _type: Type[To_Type]
     table: Type["TypedTable"] | type | str
     condition: Condition
     condition_and: Condition
@@ -142,7 +145,7 @@ class Relationship(typing.Generic[To_Type]):
 
     def __init__(
         self,
-        _type: To_Type,
+        _type: Type[To_Type],
         condition: Condition = None,
         join: JOIN_OPTIONS = None,
         on: OnQuery = None,
@@ -165,7 +168,7 @@ class Relationship(typing.Generic[To_Type]):
             self.table = unwrap_type(args[0])
             self.multiple = True
         else:
-            self.table = _type
+            self.table = typing.cast(type[TypedTable], _type)
             self.multiple = False
 
         if isinstance(self.table, str):
@@ -234,7 +237,7 @@ class Relationship(typing.Generic[To_Type]):
 
         return str(table)
 
-    def __get__(self, instance: Any, owner: Any) -> typing.Optional[list[Any]] | "Relationship[To_Type]":
+    def __get__(self, instance: Any, owner: Any) -> "typing.Optional[list[Any]] | Relationship[To_Type]":
         """
         Relationship is a descriptor class, which can be returned from a class but not an instance.
 
@@ -756,7 +759,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
         if mapping := BASIC_MAPPINGS.get(ftype):
             # basi types
             return mapping
-        elif isinstance(ftype, _Table):
+        elif isinstance(ftype, pydal.objects.Table):
             # db.table
             return f"reference {ftype._tablename}"
         elif issubclass(type(ftype), type) and issubclass(ftype, TypedTable):
@@ -829,13 +832,34 @@ class TypeDAL(pydal.DAL):  # type: ignore
         """
         return to_snake(camel)
 
+    def sql_expression(
+        self,
+        sql_fragment: str,
+        *raw_args: Any,
+        output_type: str | None = None,
+        **raw_kwargs: Any,
+    ) -> Expression:
+        """
+        Creates a pydal Expression object representing a raw SQL fragment.
+
+        Args:
+            sql_fragment: The raw SQL fragment.
+            *raw_args: Arguments to be interpolated into the SQL fragment.
+            output_type: The expected output type of the expression.
+            **raw_kwargs: Keyword arguments to be interpolated into the SQL fragment.
+
+        Returns:
+            A pydal Expression object.
+        """
+        return sql_expression(self, sql_fragment, *raw_args, output_type=output_type, **raw_kwargs)
+
 
 def default_representer(field: TypedField[T], value: T, table: Type[TypedTable]) -> str:
     """
     Simply call field.represent on the value.
     """
     if represent := getattr(field, "represent", None):
-        return field.represent(value, table)
+        return str(represent(value, table))
     else:
         return repr(value)
 
@@ -848,7 +872,7 @@ R = typing.TypeVar("R")
 
 def reorder_fields(
     table: pydal.objects.Table,
-    fields: typing.Iterable[str | Field | TypedField],
+    fields: typing.Iterable[str | Field | TypedField[Any]],
     keep_others: bool = True,
 ) -> None:
     """
@@ -1423,7 +1447,7 @@ class TableMeta(type):
         """
         return cls._hook_once(cls._after_delete, fn)
 
-    def reorder_fields(cls, *fields: str | Field | TypedField, keep_others: bool = True):
+    def reorder_fields(cls, *fields: str | Field | TypedField[Any], keep_others: bool = True) -> None:
         """
         Reorder fields of a typedal table.
 
@@ -1433,7 +1457,6 @@ class TableMeta(type):
                 - True (default): keep other fields at the end, in their original order.
                 - False: remove other fields (only keep what's specified).
         """
-
         return reorder_fields(cls._table, fields, keep_others=keep_others)
 
 
@@ -1770,13 +1793,13 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
 
         raise AttributeError(item)
 
-    def keys(self):
+    def keys(self) -> list[str]:
         """
         Return the combination of row + relationship keys.
 
         Used by dict(row).
         """
-        return list(self._row.keys()) + getattr(self, "_with", [])
+        return list(self._row.keys() if self._row else ()) + getattr(self, "_with", [])
 
     def get(self, item: str, default: Any = None) -> Any:
         """
@@ -2037,7 +2060,17 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
 
         return pydal2sql.generate_sql(cls)
 
-    def render(self, fields=None, compact=False) -> Self:
+    def render(self, fields: list[Field] = None, compact: bool = False) -> Self:
+        """
+        Renders a copy of the object with potentially modified values.
+
+        Args:
+            fields: A list of fields to render. Defaults to all representable fields in the table.
+            compact: Whether to return only the value of the first field if there is only one field.
+
+        Returns:
+            A copy of the object with potentially modified values.
+        """
         row = copy.deepcopy(self)
         keys = list(row)
         if not fields:
@@ -2091,7 +2124,7 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
                         )
 
         if compact and len(keys) == 1 and keys[0] != "_extra":  # pragma: no cover
-            return row[keys[0]]
+            return typing.cast(Self, row[keys[0]])
         return row
 
 
@@ -2290,11 +2323,11 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
 
     def as_dict(
         self,
-        key: str | Field = None,
+        key: str | Field | None = None,
         compact: bool = False,
         storage_to_dict: bool = False,
         datetime_to_str: bool = False,
-        custom_types: list[type] = None,
+        custom_types: list[type] | None = None,
     ) -> dict[int, AnyDict]:
         """
         Get the data in a dict of dicts.
@@ -2468,10 +2501,12 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
         self.__dict__.update(state)
         # db etc. set after undill by caching.py
 
-    def render(self, i=None, fields=None) -> typing.Generator[T_MetaInstance, None, None]:
+    def render(
+        self, i: int | None = None, fields: list[Field] | None = None
+    ) -> typing.Generator[T_MetaInstance, None, None]:
         """
-        Takes an index and returns a copy of the indexed row with values
-        transformed via the "represent" attributes of the associated fields.
+        Takes an index and returns a copy of the indexed row with values \
+            transformed via the "represent" attributes of the associated fields.
 
         Args:
             i: index. If not specified, a generator is returned for iteration
@@ -2481,7 +2516,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
         """
         if i is None:
             # difference: uses .keys() instead of index
-            return (self.render(i, fields=fields) for i in self.records.keys())
+            return (self.render(i, fields=fields) for i in self.records)
 
         if not self.db.has_representer("rows_render"):  # pragma: no cover
             raise RuntimeError(
@@ -2503,10 +2538,10 @@ from .caching import (  # noqa: E402
 )
 
 
-def normalize_table_keys(row: Row, pattern: re.Pattern = re.compile(r"^([a-zA-Z_]+)_(\d{5,})$")) -> Row:
+def normalize_table_keys(row: Row, pattern: re.Pattern[str] = re.compile(r"^([a-zA-Z_]+)_(\d{5,})$")) -> Row:
     """
-    Normalize table keys in a PyDAL Row object by stripping numeric hash suffixes
-    from table names, only if the suffix is 5 or more digits.
+    Normalize table keys in a PyDAL Row object by stripping numeric hash suffixes from table names, \
+    only if the suffix is 5 or more digits.
 
     For example:
         Row({'articles_12345': {...}}) -> Row({'articles': {...}})
@@ -2645,7 +2680,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
 
     def where(
         self,
-        *queries_or_lambdas: Query | typing.Callable[[Type[T_MetaInstance]], Query] | dict,
+        *queries_or_lambdas: Query | typing.Callable[[Type[T_MetaInstance]], Query] | dict[str, Any],
         **filters: Any,
     ) -> "QueryBuilder[T_MetaInstance]":
         """
@@ -2669,15 +2704,15 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
             filters,
         )
 
-        subquery: DummyQuery | Query = DummyQuery()
+        subquery = typing.cast(Query, DummyQuery())
         for query_part in queries_or_lambdas:
-            if isinstance(query_part, _Query):
+            if isinstance(query_part, (Field, pydal.objects.Field)) or is_typed_field(query_part):
+                subquery |= typing.cast(Query, query_part != None)
+            elif isinstance(query_part, (pydal.objects.Query, Expression, pydal.objects.Expression)):
                 subquery |= typing.cast(Query, query_part)
             elif callable(query_part):
                 if result := query_part(self.model):
                     subquery |= result
-            elif isinstance(query_part, (Field, _Field)) or is_typed_field(query_part):
-                subquery |= typing.cast(Query, query_part != None)
             elif isinstance(query_part, dict):
                 subsubquery = DummyQuery()
                 for field, value in query_part.items():
@@ -2727,8 +2762,9 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
             if isinstance(condition, pydal.objects.Query):
                 condition = as_lambda(condition)
 
+            to_field = typing.cast(Type[TypedTable], fields[0])
             relationships = {
-                str(fields[0]): Relationship(fields[0], condition=condition, join=method, condition_and=condition_and)
+                str(to_field): Relationship(to_field, condition=condition, join=method, condition_and=condition_and)
             }
         elif on:
             if len(fields) != 1:
@@ -2739,7 +2775,9 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
 
             if isinstance(on, list):
                 on = as_lambda(on)
-            relationships = {str(fields[0]): Relationship(fields[0], on=on, join=method, condition_and=condition_and)}
+
+            to_field = typing.cast(Type[TypedTable], fields[0])
+            relationships = {str(to_field): Relationship(to_field, on=on, join=method, condition_and=condition_and)}
 
         else:
             if fields:

{typedal-3.16.5 → typedal-3.17.1}/src/typedal/fields.py

@@ -256,18 +256,50 @@ def TimestampField(**kw: Unpack[FieldSettings]) -> TypedField[dt.datetime]:
     )
 
 
-def safe_decode_native_point(value: str | None):
+def safe_decode_native_point(value: str | None) -> tuple[float, ...]:
+    """
+    Safely decode a string into a tuple of floats.
+
+    The function attempts to parse the input string using `ast.literal_eval`.
+    If the parsing is successful, the function casts the parsed value to a tuple of floats and returns it.
+    Otherwise, the function returns an empty tuple.
+
+    Args:
+        value: The string to decode.
+
+    Returns:
+        A tuple of floats.
+    """
     if not value:
         return ()
 
     try:
-        return ast.literal_eval(value)
+        parsed = ast.literal_eval(value)
+        return typing.cast(tuple[float, ...], parsed)
     except ValueError:  # pragma: no cover
         # should not happen when inserted with `safe_encode_native_point` but you never know
         return ()
 
 
-def safe_encode_native_point(value: tuple[str, str] | str) -> str:
+def safe_encode_native_point(value: tuple[str, str] | tuple[float, float] | str) -> str:
+    """
+
+    Safe encodes a point value.
+
+    The function takes a point value as input.
+    It can be a string in the format "x,y" or a tuple of two numbers.
+    The function converts the string to a tuple if necessary, validates the tuple,
+    and formats it into the expected string format.
+
+    Args:
+        value: The point value to be encoded.
+
+    Returns:
+        The encoded point value as a string in the format "x,y".
+
+    Raises:
+        ValueError: If the input value is not a valid point.
+    """
     if not value:
         return ""
 
@@ -276,13 +308,15 @@ def safe_encode_native_point(value: tuple[str, str] | str) -> str:
         value = value.strip("() ")
         if not value:
             return ""
-        value = tuple(float(x.strip()) for x in value.split(","))
+        value_tup = tuple(float(x.strip()) for x in value.split(","))
+    else:
+        value_tup = value  # type: ignore
 
     # Validate and format
-    if len(value) != 2:
+    if len(value_tup) != 2:
         raise ValueError("Point must have exactly 2 coordinates")
 
-    x, y = value
+    x, y = value_tup
     return f"({x},{y})"
 
 

{typedal-3.16.5 → typedal-3.17.1}/src/typedal/helpers.py

@@ -2,6 +2,8 @@
 Helpers that work independently of core.
 """
 
+from __future__ import annotations
+
 import datetime as dt
 import fnmatch
 import io
@@ -12,10 +14,10 @@ from typing import Any
 
 from pydal import DAL
 
-from .types import AnyDict, Field, Table
+from .types import AnyDict, Expression, Field, Table
 
 if typing.TYPE_CHECKING:
-    from . import TypeDAL, TypedField, TypedTable  # noqa: F401
+    from . import TypeDAL, TypedField, TypedTable
 
 T = typing.TypeVar("T")
 
@@ -101,12 +103,14 @@ def origin_is_subclass(obj: Any, _type: type) -> bool:
     return bool(
         typing.get_origin(obj)
         and isinstance(typing.get_origin(obj), type)
-        and issubclass(typing.get_origin(obj), _type)
+        and issubclass(typing.get_origin(obj), _type),
     )
 
 
 def mktable(
-    data: dict[Any, Any], header: typing.Optional[typing.Iterable[str] | range] = None, skip_first: bool = True
+    data: dict[Any, Any],
+    header: typing.Optional[typing.Iterable[str] | range] = None,
+    skip_first: bool = True,
 ) -> str:
     """
     Display a table for 'data'.
@@ -331,3 +335,81 @@ class classproperty:
             The value returned by the function.
         """
         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.
+
+    Args:
+        db: Database object.
+        sql_fragment: SQL fragment with placeholders.
+        *raw_args: Positional arguments to be escaped.
+        **raw_kwargs: Keyword arguments to be escaped.
+
+    Returns:
+        Escaped SQL fragment with placeholders replaced with escaped values.
+
+    Raises:
+        ValueError: If both args and kwargs are provided.
+    """
+    if raw_args and raw_kwargs:  # pragma: no cover
+        raise ValueError("Please provide either args or kwargs, not both.")
+
+    elif raw_args:
+        # list
+        return sql_fragment % tuple(smarter_adapt(db, placeholder) for placeholder in raw_args)
+    else:
+        # dict
+        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: Any,
+    output_type: str | None = None,
+    **raw_kwargs: Any,
+) -> Expression:
+    """
+    Creates a pydal Expression object representing a raw SQL fragment.
+
+    Args:
+        db: The TypeDAL object.
+        sql_fragment: The raw SQL fragment.
+        *raw_args: Arguments to be interpolated into the SQL fragment.
+        output_type: The expected output type of the expression.
+        **raw_kwargs: Keyword arguments to be interpolated into the SQL fragment.
+
+    Returns:
+        A pydal Expression object.
+    """
+    safe_sql = sql_escape(db, sql_fragment, *raw_args, **raw_kwargs)
+
+    # create a pydal Expression wrapping a raw SQL fragment + placeholders
+    return Expression(
+        db,
+        db._adapter.dialect.raw,
+        safe_sql,
+        type=output_type,  # optional type hint
+    )

{typedal-3.16.5 → typedal-3.17.1}/src/typedal/mixins.py

@@ -180,7 +180,7 @@ class SlugMixin(Mixin):
         if slug_field is None:
             raise ValueError(
                 "SlugMixin requires a valid slug_field setting: "
-                "e.g. `class MyClass(TypedTable, SlugMixin, slug_field='title'): ...`"
+                "e.g. `class MyClass(TypedTable, SlugMixin, slug_field='title'): ...`",
             )
 
         if slug_suffix:
@@ -197,7 +197,7 @@ class SlugMixin(Mixin):
 
     @classmethod
     def __generate_slug_before_insert(cls, row: OpRow) -> None:
-        if row.get("slug"):
+        if row.get("slug"):  # type: ignore
             # manually set -> skip
             return None
 

{typedal-3.16.5 → typedal-3.17.1}/tests/test_cli.py

@@ -7,7 +7,7 @@ from src.typedal.__about__ import __version__
 from src.typedal.cli import app, get_output_format
 
 # by default, click's cli runner mixes stdout and stderr for some reason...
-runner = CliRunner(mix_stderr=False)
+runner = CliRunner()
 
 
 def test_version():

{typedal-3.16.5 → typedal-3.17.1}/tests/test_helpers.py

@@ -5,6 +5,7 @@ import pydal
 import pytest
 from pydal import DAL
 
+from src.typedal import TypeDAL, TypedTable, sql_expression
 from src.typedal.caching import get_expire
 from src.typedal.helpers import (
     DummyQuery,
@@ -23,8 +24,7 @@ from src.typedal.helpers import (
     to_snake,
     unwrap_type,
 )
-from typedal import TypeDAL, TypedTable
-from typedal.types import Field
+from src.typedal.types import Field
 
 
 def test_is_union():
@@ -207,3 +207,40 @@ def test_get_functions():
     field = get_field(TestGetFunctions.string)
     print(type(field))
     assert isinstance(field, Field)
+
+
+def test_sql_expression():
+    # note: only %s works since .adapt does something like
+    #  -> "'%s'" % obj.replace("'", "''")
+    #  depending on the driver
+
+    @database.define()
+    class TestSqlExpression(TypedTable):
+        value: str
+
+    TestSqlExpression.insert(value="This value may only be accessed after 2024")
+
+    expr1 = sql_expression(database, "date('now') > %s", "2025-01-01")
+    expr2 = database.sql_expression("date('now') > %(value)s", value="2025-01-01")
+
+    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]
+    assert result
+    assert result[TestSqlExpression.value] == "This value may only be accessed after 2024"
+    assert result[expr2] == result[expr1] == 1
+
+    result2 = TestSqlExpression.where(expr1).select(TestSqlExpression.value, expr2).first()
+    assert result2
+    assert result2[TestSqlExpression.value] == "This value may only be accessed after 2024"
+    assert result2[expr2] == result2[expr1] == 1
+
+    expr3 = database.sql_expression("date('now') > %(value)s", value="3000-01-01")
+    # 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.16.5/src/typedal/__init__.py

@@ -1,13 +0,0 @@
-"""
-TypeDAL Library.
-"""
-
-from . import fields
-from .core import Relationship, TypeDAL, TypedField, TypedRows, TypedTable, relationship
-
-try:
-    from .for_py4web import DAL as P4W_DAL
-except ImportError:  # pragma: no cover
-    P4W_DAL = None  # type: ignore
-
-__all__ = ["Relationship", "TypeDAL", "TypedField", "TypedRows", "TypedTable", "fields", "relationship"]