TypeDAL 3.2.0__py3-none-any.whl → 3.3.1__py3-none-any.whl

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.2.0"
+__version__ = "3.3.1"

typedal/caching.py

@@ -15,7 +15,7 @@ from pydal.objects import Field, Rows, Set
 from .core import TypedField, TypedRows, TypedTable
 from .types import Query
 
-if typing.TYPE_CHECKING:  # pragma: no cover
+if typing.TYPE_CHECKING:
     from .core import TypeDAL
 
 

typedal/cli.py

@@ -24,7 +24,7 @@ try:
     import tomlkit
     import typer
     from tabulate import tabulate
-except ImportError as e:  # pragma: no cover
+except ImportError as e:
     # ImportWarning is hidden by default
     warnings.warn(
         "`migrations` extra not installed. Please run `pip install typedal[migrations]` to fix this.",

typedal/config.py

@@ -17,7 +17,7 @@ from dotenv import dotenv_values, find_dotenv
 
 from .types import AnyDict
 
-if typing.TYPE_CHECKING:  # pragma: no cover
+if typing.TYPE_CHECKING:
     from edwh_migrate import Config as MigrateConfig
     from pydal2sql.typer_support import Config as P2SConfig
 

typedal/core.py

@@ -15,7 +15,7 @@ from collections import defaultdict
 from copy import copy
 from decimal import Decimal
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, Type
 
 import pydal
 from pydal._globals import DEFAULT
@@ -23,7 +23,7 @@ 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 typing_extensions import Self
+from typing_extensions import Self, Unpack
 
 from .config import TypeDALConfig, load_config
 from .helpers import (
@@ -58,13 +58,15 @@ from .types import (
     Pagination,
     Query,
     Rows,
+    SelectKwargs,
+    Table,
     Validator,
     _Types,
 )
 
 # use typing.cast(type, ...) to make mypy happy with unions
-T_annotation = typing.Type[Any] | types.UnionType
-T_Query = typing.Union["Table", Query, bool, None, "TypedTable", typing.Type["TypedTable"]]
+T_annotation = Type[Any] | types.UnionType
+T_Query = typing.Union["Table", Query, bool, None, "TypedTable", Type["TypedTable"]]
 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")
@@ -100,7 +102,7 @@ JOIN_OPTIONS = typing.Literal["left", "inner", None]
 DEFAULT_JOIN_OPTION: JOIN_OPTIONS = "left"
 
 # table-ish paramter:
-P_Table = typing.Union[typing.Type["TypedTable"], pydal.objects.Table]
+P_Table = typing.Union[Type["TypedTable"], pydal.objects.Table]
 
 Condition: typing.TypeAlias = typing.Optional[
     typing.Callable[
@@ -118,7 +120,7 @@ OnQuery: typing.TypeAlias = typing.Optional[
     ]
 ]
 
-To_Type = typing.TypeVar("To_Type", type[Any], typing.Type[Any], str)
+To_Type = typing.TypeVar("To_Type", type[Any], Type[Any], str)
 
 
 class Relationship(typing.Generic[To_Type]):
@@ -127,7 +129,7 @@ class Relationship(typing.Generic[To_Type]):
     """
 
     _type: To_Type
-    table: typing.Type["TypedTable"] | type | str
+    table: Type["TypedTable"] | type | str
     condition: Condition
     on: OnQuery
     multiple: bool
@@ -186,7 +188,7 @@ class Relationship(typing.Generic[To_Type]):
         join = f":{self.join}" if self.join else ""
         return f"<Relationship{join} {src_code}>"
 
-    def get_table(self, db: "TypeDAL") -> typing.Type["TypedTable"]:
+    def get_table(self, db: "TypeDAL") -> Type["TypedTable"]:
         """
         Get the table this relationship is bound to.
         """
@@ -197,7 +199,7 @@ class Relationship(typing.Generic[To_Type]):
                 return mapped
 
             # boo, fall back to untyped table but pretend it is typed:
-            return typing.cast(typing.Type["TypedTable"], db[table])  # eh close enough!
+            return typing.cast(Type["TypedTable"], db[table])  # eh close enough!
 
         return table
 
@@ -239,9 +241,7 @@ class Relationship(typing.Generic[To_Type]):
             return None
 
 
-def relationship(
-    _type: To_Type, condition: Condition = None, join: JOIN_OPTIONS = None, on: OnQuery = None
-) -> Relationship[To_Type]:
+def relationship(_type: To_Type, condition: Condition = None, join: JOIN_OPTIONS = None, on: OnQuery = None) -> To_Type:
     """
     Define a relationship to another table, when its id is not stored in the current table.
 
@@ -271,11 +271,17 @@ def relationship(
 
     If you'd try to capture this in a single 'condition', pydal would create a cross join which is much less efficient.
     """
-    return Relationship(_type, condition, join, on)
+    return typing.cast(
+        # note: The descriptor `Relationship[To_Type]` is more correct, but pycharm doesn't really get that.
+        # so for ease of use, just cast to the refered type for now!
+        # e.g. x = relationship(Author) -> x: Author
+        To_Type,
+        Relationship(_type, condition, join, on),
+    )
 
 
 def _generate_relationship_condition(
-    _: typing.Type["TypedTable"], key: str, field: typing.Union["TypedField[Any]", "Table", typing.Type["TypedTable"]]
+    _: Type["TypedTable"], key: str, field: typing.Union["TypedField[Any]", "Table", Type["TypedTable"]]
 ) -> Condition:
     origin = typing.get_origin(field)
     # else: generic
@@ -292,9 +298,9 @@ def _generate_relationship_condition(
 
 
 def to_relationship(
-    cls: typing.Type["TypedTable"] | type[Any],
+    cls: Type["TypedTable"] | type[Any],
     key: str,
-    field: typing.Union["TypedField[Any]", "Table", typing.Type["TypedTable"]],
+    field: typing.Union["TypedField[Any]", "Table", Type["TypedTable"]],
 ) -> typing.Optional[Relationship[Any]]:
     """
     Used to automatically create relationship instance for reference fields.
@@ -425,7 +431,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
             self.try_define(_TypedalCache)
             self.try_define(_TypedalCacheDependency)
 
-    def try_define(self, model: typing.Type[T], verbose: bool = False) -> typing.Type[T]:
+    def try_define(self, model: Type[T], verbose: bool = False) -> Type[T]:
         """
         Try to define a model with migrate or fall back to fake migrate.
         """
@@ -449,9 +455,9 @@ class TypeDAL(pydal.DAL):  # type: ignore
     }
 
     # maps table name to typedal class, for resolving future references
-    _class_map: typing.ClassVar[dict[str, typing.Type["TypedTable"]]] = {}
+    _class_map: typing.ClassVar[dict[str, Type["TypedTable"]]] = {}
 
-    def _define(self, cls: typing.Type[T], **kwargs: Any) -> typing.Type[T]:
+    def _define(self, cls: Type[T], **kwargs: Any) -> Type[T]:
         # todo: new relationship item added should also invalidate (previously unrelated) cache result
 
         # todo: option to enable/disable cache dependency behavior:
@@ -553,7 +559,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
         return cls
 
     @typing.overload
-    def define(self, maybe_cls: None = None, **kwargs: Any) -> typing.Callable[[typing.Type[T]], typing.Type[T]]:
+    def define(self, maybe_cls: None = None, **kwargs: Any) -> typing.Callable[[Type[T]], Type[T]]:
         """
         Typing Overload for define without a class.
 
@@ -562,7 +568,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
         """
 
     @typing.overload
-    def define(self, maybe_cls: typing.Type[T], **kwargs: Any) -> typing.Type[T]:
+    def define(self, maybe_cls: Type[T], **kwargs: Any) -> Type[T]:
         """
         Typing Overload for define with a class.
 
@@ -570,9 +576,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
         class MyTable(TypedTable): ...
         """
 
-    def define(
-        self, maybe_cls: typing.Type[T] | None = None, **kwargs: Any
-    ) -> typing.Type[T] | typing.Callable[[typing.Type[T]], typing.Type[T]]:
+    def define(self, maybe_cls: Type[T] | None = None, **kwargs: Any) -> Type[T] | typing.Callable[[Type[T]], Type[T]]:
         """
         Can be used as a decorator on a class that inherits `TypedTable`, \
           or as a regular method if you need to define your classes before you have access to a 'db' instance.
@@ -595,7 +599,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
             the result of pydal.define_table
         """
 
-        def wrapper(cls: typing.Type[T]) -> typing.Type[T]:
+        def wrapper(cls: Type[T]) -> Type[T]:
             return self._define(cls, **kwargs)
 
         if maybe_cls:
@@ -645,7 +649,7 @@ class TypeDAL(pydal.DAL):  # type: ignore
 
             if isinstance(cls, type) and issubclass(type(cls), type) and issubclass(cls, TypedTable):
                 # table defined without @db.define decorator!
-                _cls: typing.Type[TypedTable] = cls
+                _cls: Type[TypedTable] = cls
                 args[0] = _cls.id != None
 
         _set = super().__call__(*args, **kwargs)
@@ -669,11 +673,11 @@ class TypeDAL(pydal.DAL):  # type: ignore
         cls, _ftype: T_annotation, mut_kw: typing.MutableMapping[str, Any]
     ) -> Optional[str]:
         # ftype can be a union or type. typing.cast is sometimes used to tell mypy when it's not a union.
-        ftype = typing.cast(type, _ftype)  # cast from typing.Type to type to make mypy happy)
+        ftype = typing.cast(type, _ftype)  # cast from Type to type to make mypy happy)
 
         if isinstance(ftype, str):
             # extract type from string
-            ftype = typing.get_args(typing.Type[ftype])[0]._evaluate(
+            ftype = typing.get_args(Type[ftype])[0]._evaluate(
                 localns=locals(), globalns=globals(), recursive_guard=frozenset()
             )
 
@@ -753,25 +757,6 @@ class TypeDAL(pydal.DAL):  # type: ignore
         return to_snake(camel)
 
 
-class TableProtocol(typing.Protocol):  # pragma: no cover
-    """
-    Make mypy happy.
-    """
-
-    id: "TypedField[int]"
-
-    def __getitem__(self, item: str) -> Field:
-        """
-        Tell mypy a Table supports dictionary notation for columns.
-        """
-
-
-class Table(_Table, TableProtocol):  # type: ignore
-    """
-    Make mypy happy.
-    """
-
-
 class TableMeta(type):
     """
     This metaclass contains functionality on table classes, that doesn't exist on its instances.
@@ -852,13 +837,13 @@ class TableMeta(type):
         else:
             return f"<unbound table {self.__name__}>"
 
-    def from_row(self: typing.Type[T_MetaInstance], row: pydal.objects.Row) -> T_MetaInstance:
+    def from_row(self: Type[T_MetaInstance], row: pydal.objects.Row) -> T_MetaInstance:
         """
         Create a model instance from a pydal row.
         """
         return self(row)
 
-    def all(self: typing.Type[T_MetaInstance]) -> "TypedRows[T_MetaInstance]":
+    def all(self: Type[T_MetaInstance]) -> "TypedRows[T_MetaInstance]":
         """
         Return all rows for this model.
         """
@@ -874,7 +859,7 @@ class TableMeta(type):
     # TypeDAL Modified Logic #
     ##########################
 
-    def insert(self: typing.Type[T_MetaInstance], **fields: Any) -> T_MetaInstance:
+    def insert(self: Type[T_MetaInstance], **fields: Any) -> T_MetaInstance:
         """
         This is only called when db.define is not used as a decorator.
 
@@ -897,7 +882,7 @@ class TableMeta(type):
 
         return str(table._insert(**fields))
 
-    def bulk_insert(self: typing.Type[T_MetaInstance], items: list[AnyDict]) -> "TypedRows[T_MetaInstance]":
+    def bulk_insert(self: Type[T_MetaInstance], items: list[AnyDict]) -> "TypedRows[T_MetaInstance]":
         """
         Insert multiple rows, returns a TypedRows set of new instances.
         """
@@ -906,7 +891,7 @@ class TableMeta(type):
         return self.where(lambda row: row.id.belongs(result)).collect()
 
     def update_or_insert(
-        self: typing.Type[T_MetaInstance], query: T_Query | AnyDict = DEFAULT, **values: Any
+        self: Type[T_MetaInstance], query: T_Query | AnyDict = DEFAULT, **values: Any
     ) -> T_MetaInstance:
         """
         Update a row if query matches, else insert a new one.
@@ -929,7 +914,7 @@ class TableMeta(type):
         return self(record)
 
     def validate_and_insert(
-        self: typing.Type[T_MetaInstance], **fields: Any
+        self: Type[T_MetaInstance], **fields: Any
     ) -> tuple[Optional[T_MetaInstance], Optional[dict[str, str]]]:
         """
         Validate input data and then insert a row.
@@ -944,7 +929,7 @@ class TableMeta(type):
             return None, result.get("errors")
 
     def validate_and_update(
-        self: typing.Type[T_MetaInstance], query: Query, **fields: Any
+        self: Type[T_MetaInstance], query: Query, **fields: Any
     ) -> tuple[Optional[T_MetaInstance], Optional[dict[str, str]]]:
         """
         Validate input data and then update max 1 row.
@@ -953,10 +938,7 @@ class TableMeta(type):
         """
         table = self._ensure_table_defined()
 
-        try:
-            result = table.validate_and_update(query, **fields)
-        except Exception as e:
-            result = {"errors": {"exception": str(e)}}
+        result = table.validate_and_update(query, **fields)
 
         if errors := result.get("errors"):
             return None, errors
@@ -967,7 +949,7 @@ class TableMeta(type):
             return None, None
 
     def validate_and_update_or_insert(
-        self: typing.Type[T_MetaInstance], query: Query, **fields: Any
+        self: Type[T_MetaInstance], query: Query, **fields: Any
     ) -> tuple[Optional[T_MetaInstance], Optional[dict[str, str]]]:
         """
         Validate input data and then update_and_insert (on max 1 row).
@@ -985,53 +967,57 @@ class TableMeta(type):
             # update on query without result (shouldnt happen)
             return None, None
 
-    def select(self: typing.Type[T_MetaInstance], *a: Any, **kw: Any) -> "QueryBuilder[T_MetaInstance]":
+    def select(self: Type[T_MetaInstance], *a: Any, **kw: Any) -> "QueryBuilder[T_MetaInstance]":
         """
         See QueryBuilder.select!
         """
         return QueryBuilder(self).select(*a, **kw)
 
-    def paginate(self: typing.Type[T_MetaInstance], limit: int, page: int = 1) -> "PaginatedRows[T_MetaInstance]":
+    def paginate(self: Type[T_MetaInstance], limit: int, page: int = 1) -> "PaginatedRows[T_MetaInstance]":
         """
         See QueryBuilder.paginate!
         """
         return QueryBuilder(self).paginate(limit=limit, page=page)
 
-    def chunk(
-        self: typing.Type[T_MetaInstance], chunk_size: int
-    ) -> typing.Generator["TypedRows[T_MetaInstance]", Any, None]:
+    def chunk(self: Type[T_MetaInstance], chunk_size: int) -> typing.Generator["TypedRows[T_MetaInstance]", Any, None]:
         """
         See QueryBuilder.chunk!
         """
         return QueryBuilder(self).chunk(chunk_size)
 
-    def where(self: typing.Type[T_MetaInstance], *a: Any, **kw: Any) -> "QueryBuilder[T_MetaInstance]":
+    def where(self: Type[T_MetaInstance], *a: Any, **kw: Any) -> "QueryBuilder[T_MetaInstance]":
         """
         See QueryBuilder.where!
         """
         return QueryBuilder(self).where(*a, **kw)
 
-    def cache(self: typing.Type[T_MetaInstance], *deps: Any, **kwargs: Any) -> "QueryBuilder[T_MetaInstance]":
+    def cache(self: Type[T_MetaInstance], *deps: Any, **kwargs: Any) -> "QueryBuilder[T_MetaInstance]":
         """
         See QueryBuilder.cache!
         """
         return QueryBuilder(self).cache(*deps, **kwargs)
 
-    def count(self: typing.Type[T_MetaInstance]) -> int:
+    def count(self: Type[T_MetaInstance]) -> int:
         """
         See QueryBuilder.count!
         """
         return QueryBuilder(self).count()
 
-    def first(self: typing.Type[T_MetaInstance]) -> T_MetaInstance | None:
+    def first(self: Type[T_MetaInstance]) -> T_MetaInstance | None:
         """
         See QueryBuilder.first!
         """
         return QueryBuilder(self).first()
 
+    def first_or_fail(self: Type[T_MetaInstance]) -> T_MetaInstance:
+        """
+        See QueryBuilder.first_or_fail!
+        """
+        return QueryBuilder(self).first_or_fail()
+
     def join(
-        self: typing.Type[T_MetaInstance],
-        *fields: str | typing.Type["TypedTable"],
+        self: Type[T_MetaInstance],
+        *fields: str | Type["TypedTable"],
         method: JOIN_OPTIONS = None,
         on: OnQuery | list[Expression] | Expression = None,
         condition: Condition = None,
@@ -1041,7 +1027,7 @@ class TableMeta(type):
         """
         return QueryBuilder(self).join(*fields, on=on, condition=condition, method=method)
 
-    def collect(self: typing.Type[T_MetaInstance], verbose: bool = False) -> "TypedRows[T_MetaInstance]":
+    def collect(self: Type[T_MetaInstance], verbose: bool = False) -> "TypedRows[T_MetaInstance]":
         """
         See QueryBuilder.collect!
         """
@@ -1141,7 +1127,7 @@ class TableMeta(type):
         table = self._ensure_table_defined()
         return typing.cast(Expression, table.on(query))
 
-    def with_alias(self, alias: str) -> _Table:
+    def with_alias(self: Type[T_MetaInstance], alias: str) -> Type[T_MetaInstance]:
         """
         Shadow Table.with_alias.
 
@@ -1151,12 +1137,12 @@ class TableMeta(type):
             http://web2py.com/books/default/chapter/29/06/the-database-abstraction-layer?search=export_to_csv_file#One-to-many-relation
         """
         table = self._ensure_table_defined()
-        return table.with_alias(alias)
+        return typing.cast(Type[T_MetaInstance], table.with_alias(alias))
 
     # @typing.dataclass_transform()
 
 
-class TypedField(typing.Generic[T_Value]):  # pragma: no cover
+class TypedField(Expression, typing.Generic[T_Value]):  # pragma: no cover
     """
     Typed version of pydal.Field, which will be converted to a normal Field in the background.
     """
@@ -1173,28 +1159,28 @@ class TypedField(typing.Generic[T_Value]):  # pragma: no cover
 
     requires: Validator | typing.Iterable[Validator]
 
-    def __init__(self, _type: typing.Type[T_Value] | types.UnionType = str, /, **settings: Any) -> None:  # type: ignore
+    def __init__(self, _type: Type[T_Value] | types.UnionType = str, /, **settings: Any) -> None:  # type: ignore
         """
         A TypedFieldType should not be inited manually, but TypedField (from `fields.py`) should be used!
         """
         self._type = _type
         self.kwargs = settings
-        super().__init__()
+        # super().__init__()
 
     @typing.overload
-    def __get__(self, instance: T_MetaInstance, owner: typing.Type[T_MetaInstance]) -> T_Value:  # pragma: no cover
+    def __get__(self, instance: T_MetaInstance, owner: Type[T_MetaInstance]) -> T_Value:  # pragma: no cover
         """
         row.field -> (actual data).
         """
 
     @typing.overload
-    def __get__(self, instance: None, owner: "typing.Type[TypedTable]") -> "TypedField[T_Value]":  # pragma: no cover
+    def __get__(self, instance: None, owner: "Type[TypedTable]") -> "TypedField[T_Value]":  # pragma: no cover
         """
         Table.field -> Field.
         """
 
     def __get__(
-        self, instance: T_MetaInstance | None, owner: typing.Type[T_MetaInstance]
+        self, instance: T_MetaInstance | None, owner: Type[T_MetaInstance]
     ) -> typing.Union[T_Value, "TypedField[T_Value]"]:
         """
         Since this class is a Descriptor field, \
@@ -1323,6 +1309,17 @@ class TypedField(typing.Generic[T_Value]):  # pragma: no cover
 
         return typing.cast(Expression, ~self._field)
 
+    def lower(self) -> Expression:
+        """
+        For string-fields: compare lowercased values.
+        """
+        if not self._field:  # pragma: no cover
+            raise ValueError("Unbound Field can not be lowered!")
+
+        return typing.cast(Expression, self._field.lower())
+
+    # ... etc
+
 
 class _TypedTable:
     """
@@ -1377,7 +1374,7 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
 
     def __new__(
         cls, row_or_id: typing.Union[Row, Query, pydal.objects.Set, int, str, None, "TypedTable"] = None, **filters: Any
-    ) -> "TypedTable":
+    ) -> Self:
         """
         Create a Typed Rows model instance from an existing row, ID or query.
 
@@ -1391,7 +1388,8 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
 
         if isinstance(row_or_id, TypedTable):
             # existing typed table instance!
-            return row_or_id
+            return typing.cast(Self, row_or_id)
+
         elif isinstance(row_or_id, pydal.objects.Row):
             row = row_or_id
         elif row_or_id is not None:
@@ -1598,7 +1596,7 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
         super().__setattr__(key, value)
 
     @classmethod
-    def update(cls: typing.Type[T_MetaInstance], query: Query, **fields: Any) -> T_MetaInstance | None:
+    def update(cls: Type[T_MetaInstance], query: Query, **fields: Any) -> T_MetaInstance | None:
         """
         Update one record.
 
@@ -1697,7 +1695,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
 
     records: dict[int, T_MetaInstance]
     # _rows: Rows
-    model: typing.Type[T_MetaInstance]
+    model: Type[T_MetaInstance]
     metadata: Metadata
 
     # pseudo-properties: actually stored in _rows
@@ -1710,7 +1708,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
     def __init__(
         self,
         rows: Rows,
-        model: typing.Type[T_MetaInstance],
+        model: Type[T_MetaInstance],
         records: dict[int, T_MetaInstance] = None,
         metadata: Metadata = None,
     ) -> None:
@@ -1940,7 +1938,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
         Update the current rows in the database with new_values.
         """
         # cast to make mypy understand .id is a TypedField and not an int!
-        table = typing.cast(typing.Type[TypedTable], self.model._ensure_table_defined())
+        table = typing.cast(Type[TypedTable], self.model._ensure_table_defined())
 
         ids = set(self.column("id"))
         query = table.id.belongs(ids)
@@ -1951,7 +1949,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
         Delete the currently selected rows from the database.
         """
         # cast to make mypy understand .id is a TypedField and not an int!
-        table = typing.cast(typing.Type[TypedTable], self.model._ensure_table_defined())
+        table = typing.cast(Type[TypedTable], self.model._ensure_table_defined())
 
         ids = set(self.column("id"))
         query = table.id.belongs(ids)
@@ -2006,7 +2004,7 @@ class TypedRows(typing.Collection[T_MetaInstance], Rows):
 
     @classmethod
     def from_rows(
-        cls, rows: Rows, model: typing.Type[T_MetaInstance], metadata: Metadata = None
+        cls, rows: Rows, model: Type[T_MetaInstance], metadata: Metadata = None
     ) -> "TypedRows[T_MetaInstance]":
         """
         Internal method to convert a Rows object to a TypedRows.
@@ -2049,19 +2047,19 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
     Abstration on top of pydal's query system.
     """
 
-    model: typing.Type[T_MetaInstance]
+    model: Type[T_MetaInstance]
     query: Query
     select_args: list[Any]
-    select_kwargs: AnyDict
+    select_kwargs: SelectKwargs
     relationships: dict[str, Relationship[Any]]
     metadata: Metadata
 
     def __init__(
         self,
-        model: typing.Type[T_MetaInstance],
+        model: Type[T_MetaInstance],
         add_query: Optional[Query] = None,
         select_args: Optional[list[Any]] = None,
-        select_kwargs: Optional[AnyDict] = None,
+        select_kwargs: Optional[SelectKwargs] = None,
         relationships: dict[str, Relationship[Any]] = None,
         metadata: Metadata = None,
     ):
@@ -2111,7 +2109,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         add_query: Optional[Query] = None,
         overwrite_query: Optional[Query] = None,
         select_args: Optional[list[Any]] = None,
-        select_kwargs: Optional[AnyDict] = None,
+        select_kwargs: Optional[SelectKwargs] = None,
         relationships: dict[str, Relationship[Any]] = None,
         metadata: Metadata = None,
     ) -> "QueryBuilder[T_MetaInstance]":
@@ -2124,7 +2122,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
             (self.metadata | (metadata or {})) if metadata else self.metadata,
         )
 
-    def select(self, *fields: Any, **options: Any) -> "QueryBuilder[T_MetaInstance]":
+    def select(self, *fields: Any, **options: Unpack[SelectKwargs]) -> "QueryBuilder[T_MetaInstance]":
         """
         Fields: database columns by name ('id'), by field reference (table.id) or other (e.g. table.ALL).
 
@@ -2153,7 +2151,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
 
     def where(
         self,
-        *queries_or_lambdas: Query | typing.Callable[[typing.Type[T_MetaInstance]], Query],
+        *queries_or_lambdas: Query | typing.Callable[[Type[T_MetaInstance]], Query],
         **filters: Any,
     ) -> "QueryBuilder[T_MetaInstance]":
         """
@@ -2194,7 +2192,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
 
     def join(
         self,
-        *fields: str | typing.Type[TypedTable],
+        *fields: str | Type[TypedTable],
         method: JOIN_OPTIONS = None,
         on: OnQuery | list[Expression] | Expression = None,
         condition: Condition = None,
@@ -2221,7 +2219,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
             if isinstance(condition, pydal.objects.Query):
                 condition = as_lambda(condition)
 
-            relationships = {str(fields[0]): relationship(fields[0], condition=condition, join=method)}
+            relationships = {str(fields[0]): Relationship(fields[0], condition=condition, join=method)}
         elif on:
             if len(fields) != 1:
                 raise ValueError("join(field, on=...) can only be used with exactly one field!")
@@ -2231,7 +2229,7 @@ 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)}
+            relationships = {str(fields[0]): Relationship(fields[0], on=on, join=method)}
 
         else:
             if fields:
@@ -2313,7 +2311,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         db = self._get_db()
         return str(db(self.query)._update(**fields))
 
-    def _before_query(self, mut_metadata: Metadata, add_id: bool = True) -> tuple[Query, list[Any], AnyDict]:
+    def _before_query(self, mut_metadata: Metadata, add_id: bool = True) -> tuple[Query, list[Any], SelectKwargs]:
         select_args = [self._select_arg_convert(_) for _ in self.select_args] or [self.model.ALL]
         select_kwargs = self.select_kwargs.copy()
         query = self.query
@@ -2385,7 +2383,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         return db(query).select(*select_args, **select_kwargs)
 
     def collect(
-        self, verbose: bool = False, _to: typing.Type["TypedRows[Any]"] = None, add_id: bool = True
+        self, verbose: bool = False, _to: Type["TypedRows[Any]"] = None, add_id: bool = True
     ) -> "TypedRows[T_MetaInstance]":
         """
         Execute the built query and turn it into model instances, while handling relationships.
@@ -2432,7 +2430,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         self,
         query: Query,
         select_args: list[Any],
-        select_kwargs: AnyDict,
+        select_kwargs: SelectKwargs,
         metadata: Metadata,
     ) -> tuple[Query, list[Any]]:
         db = self._get_db()
@@ -2450,13 +2448,16 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
             other = other.with_alias(f"{key}_{hash(relation)}")
             join.append(other.on(relation.condition(model, other)))
 
-        if limitby := select_kwargs.pop("limitby", None):
+        if limitby := select_kwargs.pop("limitby", ()):
+
             # if limitby + relationships:
             # 1. get IDs of main table entries that match 'query'
             # 2. change query to .belongs(id)
             # 3. add joins etc
 
-            kwargs = {"limitby": limitby}
+            kwargs: SelectKwargs = select_kwargs | {"limitby": limitby}
+            # if orderby := select_kwargs.get("orderby"):
+            #     kwargs["orderby"] = orderby
 
             if join:
                 kwargs["join"] = join
@@ -2520,7 +2521,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         return query, select_args
 
     def _collect_with_relationships(
-        self, rows: Rows, metadata: Metadata, _to: typing.Type["TypedRows[Any]"]
+        self, rows: Rows, metadata: Metadata, _to: Type["TypedRows[Any]"]
     ) -> "TypedRows[T_MetaInstance]":
         """
         Transform the raw rows into Typed Table model instances.
@@ -2801,7 +2802,7 @@ class TypedSet(pydal.objects.Set):  # type: ignore # pragma: no cover
             result: TypedRows[MyTable] = db(MyTable.id > 0).select()
 
             for row in result:
-                typing.reveal_type(row)  # MyTable
+                reveal_type(row)  # MyTable
         """
         rows = super().select(*fields, **attributes)
         return typing.cast(TypedRows[T_MetaInstance], rows)

typedal/helpers.py

@@ -2,6 +2,7 @@
 Helpers that work independently of core.
 """
 
+import datetime as dt
 import fnmatch
 import io
 import types
@@ -265,3 +266,11 @@ def match_strings(patterns: list[str] | str, string_list: list[str]) -> list[str
         matches.extend([s for s in string_list if fnmatch.fnmatch(s, pattern)])
 
     return matches
+
+
+def utcnow() -> dt.datetime:
+    """
+    Replacement of datetime.utcnow.
+    """
+    # return dt.datetime.now(dt.UTC)
+    return dt.datetime.now(dt.timezone.utc)

typedal/types.py

@@ -6,6 +6,7 @@ import typing
 from datetime import datetime
 from typing import Any, Optional, TypedDict
 
+from pydal.adapters.base import BaseAdapter
 from pydal.helpers.classes import OpRow as _OpRow
 from pydal.helpers.classes import Reference as _Reference
 from pydal.objects import Expression as _Expression
@@ -13,9 +14,13 @@ from pydal.objects import Field as _Field
 from pydal.objects import Query as _Query
 from pydal.objects import Rows as _Rows
 from pydal.objects import Set as _Set
+from pydal.objects import Table as _Table
 from pydal.validators import Validator as _Validator
 from typing_extensions import NotRequired
 
+if typing.TYPE_CHECKING:
+    from .core import TypedField
+
 AnyDict: typing.TypeAlias = dict[str, Any]
 
 
@@ -148,6 +153,62 @@ class PaginationMetadata(TypedDict):
     min_max: tuple[int, int]
 
 
+class TableProtocol(typing.Protocol):  # pragma: no cover
+    """
+    Make mypy happy.
+    """
+
+    id: "TypedField[int]"
+
+    def __getitem__(self, item: str) -> Field:
+        """
+        Tell mypy a Table supports dictionary notation for columns.
+        """
+
+
+class Table(_Table, TableProtocol):  # type: ignore
+    """
+    Make mypy happy.
+    """
+
+
+class CacheFn(typing.Protocol):
+    """
+    The cache model (e.g. cache.ram) accepts these parameters (all filled by dfeault).
+    """
+
+    def __call__(
+        self: BaseAdapter,
+        sql: str = "",
+        fields: typing.Iterable[str] = (),
+        attributes: typing.Iterable[str] = (),
+        colnames: typing.Iterable[str] = (),
+    ) -> Rows:
+        """
+        Only used for type-hinting.
+        """
+
+
+# CacheFn = typing.Callable[[], Rows]
+CacheModel = typing.Callable[[str, CacheFn, int], Rows]
+CacheTuple = tuple[CacheModel, int]
+
+
+class SelectKwargs(typing.TypedDict, total=False):
+    """
+    Possible keyword arguments for .select().
+    """
+
+    join: Optional[list[Expression]]
+    left: Optional[list[Expression]]
+    orderby: Optional[Expression | str | Table]
+    limitby: Optional[tuple[int, int]]
+    distinct: bool | Field | Expression
+    orderby_on_limitby: bool
+    cacheable: bool
+    cache: CacheTuple
+
+
 class Metadata(TypedDict):
     """
     Loosely structured metadata used by Query Builder.
@@ -161,7 +222,7 @@ class Metadata(TypedDict):
 
     final_query: NotRequired[Query | str | None]
     final_args: NotRequired[list[Any]]
-    final_kwargs: NotRequired[AnyDict]
+    final_kwargs: NotRequired[SelectKwargs]
     relationships: NotRequired[set[str]]
 
     sql: NotRequired[str]

{typedal-3.2.0.dist-info → typedal-3.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: TypeDAL
-Version: 3.2.0
+Version: 3.3.1
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues
@@ -29,14 +29,17 @@ Requires-Dist: tabulate; extra == 'all'
 Requires-Dist: tomlkit; extra == 'all'
 Requires-Dist: typer; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: contextlib-chdir; extra == 'dev'
 Requires-Dist: hatch; extra == 'dev'
 Requires-Dist: mkdocs; extra == 'dev'
 Requires-Dist: mkdocs-dracula-theme; extra == 'dev'
 Requires-Dist: pytest-mypy-testing; extra == 'dev'
 Requires-Dist: python-semantic-release<8; extra == 'dev'
-Requires-Dist: su6[all]; extra == 'dev'
+Requires-Dist: requests<2.32; extra == 'dev'
+Requires-Dist: su6[all]>=1.9.0; extra == 'dev'
 Requires-Dist: testcontainers; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
 Requires-Dist: types-tabulate; extra == 'dev'
 Provides-Extra: migrations
 Requires-Dist: edwh-migrate>=0.8.0; extra == 'migrations'

typedal-3.3.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+typedal/__about__.py,sha256=Wu5Lv4Jglqs8h2_AjyrHv-m67Gz9cmuGT7s5MPNnAFs,206
+typedal/__init__.py,sha256=QQpLiVl9w9hm2LBxey49Y_tCF_VB2bScVaS_mCjYy54,366
+typedal/caching.py,sha256=SMcJsahLlZ79yykWCveERFx1ZJUNEKhA9SPmCTIuLp8,11798
+typedal/cli.py,sha256=BXXu1w9WRRK9GA82xh_JLvvfpNDFWICXKCAWNg4a3-Y,18180
+typedal/config.py,sha256=0qy1zrTUdtmXPM9jHzFnSR1DJsqGJqcdG6pvhzKQHe0,11625
+typedal/core.py,sha256=ScUZkDzHGULNTcrW9Jq4Anf4axUfha-CXWmm7SWrn90,95991
+typedal/fields.py,sha256=z2PD9vLWqBR_zXtiY0DthqTG4AeF3yxKoeuVfGXnSdg,5197
+typedal/for_py4web.py,sha256=d07b8hL_PvNDUS26Z5fDH2OxWb-IETBuAFPSzrRwm04,1285
+typedal/for_web2py.py,sha256=4RHgzGXgKIO_BYB-7adC5e35u52rX-p1t4tPEz-NK24,1867
+typedal/helpers.py,sha256=KbgP4ZRW7KCroyHwTwdErPqylOX4dsqVnKJeZ5TtTFY,7363
+typedal/mixins.py,sha256=OHhVYLBGTzPSJKgp1uovBs1Y6NJa0d-DxHTOk9LyOXA,5414
+typedal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typedal/types.py,sha256=AsUHrAXk058zmdqDbZlpf6sE85ID1Q2vofsGgCXni1s,4851
+typedal/web2py_py4web_shared.py,sha256=VK9T8P5UwVLvfNBsY4q79ANcABv-jX76YKADt1Zz_co,1539
+typedal/serializers/as_json.py,sha256=ffo152W-sARYXym4BzwX709rrO2-QwKk2KunWY8RNl4,2229
+typedal-3.3.1.dist-info/METADATA,sha256=8sBC0FTFEy7qE17mgnL5sj06hkl3LQc_tRP8_j2-kbU,9462
+typedal-3.3.1.dist-info/WHEEL,sha256=KGYbc1zXlYddvwxnNty23BeaKzh7YuoSIvIMO4jEhvw,87
+typedal-3.3.1.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
+typedal-3.3.1.dist-info/RECORD,,

{typedal-3.2.0.dist-info → typedal-3.3.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.22.4
+Generator: hatchling 1.17.1
 Root-Is-Purelib: true
 Tag: py3-none-any

typedal-3.2.0.dist-info/RECORD

@@ -1,19 +0,0 @@
-typedal/__about__.py,sha256=JM7UvclHJLbyevmmJGGt8HQwzgu3SMpy7q2WeNEm9Io,206
-typedal/__init__.py,sha256=QQpLiVl9w9hm2LBxey49Y_tCF_VB2bScVaS_mCjYy54,366
-typedal/caching.py,sha256=8UABVAhOlBpL96ykmqhxLaFYOe-XeAh7JoGh57OkxP8,11818
-typedal/cli.py,sha256=3tge8B-YjgjMC6425-RMczmWvpOTfWV5QYPXRY23IWA,18200
-typedal/config.py,sha256=jS1K0_1F5rwJtvwTZ-qR29ZCX7WlyORGEIFvfSnusko,11645
-typedal/core.py,sha256=tocfC9KDnuOoPgUTpBhFo2WGTupS5Y0esyFSTcANwLc,95866
-typedal/fields.py,sha256=z2PD9vLWqBR_zXtiY0DthqTG4AeF3yxKoeuVfGXnSdg,5197
-typedal/for_py4web.py,sha256=d07b8hL_PvNDUS26Z5fDH2OxWb-IETBuAFPSzrRwm04,1285
-typedal/for_web2py.py,sha256=4RHgzGXgKIO_BYB-7adC5e35u52rX-p1t4tPEz-NK24,1867
-typedal/helpers.py,sha256=mtRYPFlS0dx2wK8kYSJ4vm1wsTXRkdPumFRlOAjF_xU,7177
-typedal/mixins.py,sha256=OHhVYLBGTzPSJKgp1uovBs1Y6NJa0d-DxHTOk9LyOXA,5414
-typedal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-typedal/types.py,sha256=1kGkNX6vfGg6ln84AG558C4Zx5ACRz-emrUTnuy-rRY,3410
-typedal/web2py_py4web_shared.py,sha256=VK9T8P5UwVLvfNBsY4q79ANcABv-jX76YKADt1Zz_co,1539
-typedal/serializers/as_json.py,sha256=ffo152W-sARYXym4BzwX709rrO2-QwKk2KunWY8RNl4,2229
-typedal-3.2.0.dist-info/METADATA,sha256=foiNGED0K4DE5WJOKqWZt693_ms7zMp8JO8GXbblkok,9316
-typedal-3.2.0.dist-info/WHEEL,sha256=uNdcs2TADwSd5pVaP0Z_kcjcvvTUklh2S7bxZMF8Uj0,87
-typedal-3.2.0.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
-typedal-3.2.0.dist-info/RECORD,,