TypeDAL 3.1.4__py3-none-any.whl → 3.3.0__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.1.4"
+__version__ = "3.3.0"

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

@@ -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,6 +58,8 @@ from .types import (
     Pagination,
     Query,
     Rows,
+    SelectKwargs,
+    Table,
     Validator,
     _Types,
 )
@@ -753,25 +755,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.
@@ -953,10 +936,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
@@ -1029,6 +1009,12 @@ class TableMeta(type):
         """
         return QueryBuilder(self).first()
 
+    def first_or_fail(self: typing.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"],
@@ -1156,7 +1142,7 @@ class TableMeta(type):
     # @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.
     """
@@ -1179,7 +1165,7 @@ class TypedField(typing.Generic[T_Value]):  # pragma: no cover
         """
         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
@@ -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":
+    ) -> typing.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:
@@ -2052,7 +2050,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
     model: typing.Type[T_MetaInstance]
     query: Query
     select_args: list[Any]
-    select_kwargs: AnyDict
+    select_kwargs: SelectKwargs
     relationships: dict[str, Relationship[Any]]
     metadata: Metadata
 
@@ -2061,7 +2059,7 @@ class QueryBuilder(typing.Generic[T_MetaInstance]):
         model: typing.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).
 
@@ -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
@@ -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

typedal/mixins.py

@@ -7,13 +7,20 @@ Mixins can add reusable fields and behavior (optimally both, otherwise it doesn'
 import base64
 import os
 import typing
+import warnings
 from datetime import datetime
-from typing import Any
+from typing import Any, Optional
 
 from slugify import slugify
 
-from .core import TypedTable  # noqa F401 - used by example in docstring
-from .core import TypeDAL, _TypedTable
+from .core import (  # noqa F401 - used by example in docstring
+    QueryBuilder,
+    T_MetaInstance,
+    TableMeta,
+    TypeDAL,
+    TypedTable,
+    _TypedTable,
+)
 from .fields import DatetimeField, StringField
 from .types import OpRow, Set
 
@@ -79,7 +86,7 @@ class SlugMixin(Mixin):
     Some random bytes are added at the end to prevent duplicates.
 
     Example:
-        >>> class MyTable(TypedTable, SlugMixin, slug_field="some_name"):
+        >>> class MyTable(TypedTable, SlugMixin, slug_field="some_name", slug_suffix_length=8):
         >>>    some_name: str
         >>>    ...
     """
@@ -95,11 +102,11 @@ class SlugMixin(Mixin):
         },
     )  # set via init subclass
 
-    def __init_subclass__(cls, slug_field: str = None, slug_suffix: int = 8, **kw: Any) -> None:
+    def __init_subclass__(cls, slug_field: str = None, slug_suffix_length: int = 0, **kw: Any) -> None:
         """
         Bind 'slug field' option to be used later (on_define).
 
-        You can control the length of the random suffix with the `slug_suffix` option (0 is no suffix).
+        You can control the length of the random suffix with the `slug_suffix_length` option (0 is no suffix).
         """
         # unfortunately, PyCharm and mypy do not recognize/autocomplete/typecheck init subclass (keyword) arguments.
         if slug_field is None:
@@ -108,6 +115,14 @@ class SlugMixin(Mixin):
                 "e.g. `class MyClass(TypedTable, SlugMixin, slug_field='title'): ...`"
             )
 
+        if "slug_suffix" in kw:
+            warnings.warn(
+                "The 'slug_suffix' option is deprecated, use 'slug_suffix_length' instead.",
+                DeprecationWarning,
+            )
+
+        slug_suffix = slug_suffix_length or kw.get("slug_suffix", 0)
+
         cls.__settings__ = {
             "slug_field": slug_field,
             "slug_suffix": slug_suffix,
@@ -133,3 +148,25 @@ class SlugMixin(Mixin):
             row["slug"] = slugify(generated_slug)
 
         cls._before_insert.append(generate_slug_before_insert)
+
+    @classmethod
+    def from_slug(cls: typing.Type[T_MetaInstance], slug: str, join: bool = True) -> Optional[T_MetaInstance]:
+        """
+        Find a row by its slug.
+        """
+        builder = cls.where(slug=slug)
+        if join:
+            builder = builder.join()
+
+        return builder.first()
+
+    @classmethod
+    def from_slug_or_fail(cls: typing.Type[T_MetaInstance], slug: str, join: bool = True) -> T_MetaInstance:
+        """
+        Find a row by its slug, or raise an error if it doesn't exist.
+        """
+        builder = cls.where(slug=slug)
+        if join:
+            builder = builder.join()
+
+        return builder.first_or_fail()

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.1.4.dist-info → typedal-3.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: TypeDAL
-Version: 3.1.4
+Version: 3.3.0
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues
@@ -35,6 +35,7 @@ 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: testcontainers; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Requires-Dist: types-tabulate; extra == 'dev'
 Provides-Extra: migrations

typedal-3.3.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+typedal/__about__.py,sha256=3-Xok9ZOvvrfDNbH5xUjdw3tCd6M_cLiUWxppT-gDuk,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=Wa6Vu7ppD278tIPAl4eW8rHZRXYETM1rI3-raJ4_8GE,96148
+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=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.0.dist-info/METADATA,sha256=IiO1uKvVp-xZHz_9xeAyizZVAA-WQlAuPhmOxRRVp7E,9316
+typedal-3.3.0.dist-info/WHEEL,sha256=KGYbc1zXlYddvwxnNty23BeaKzh7YuoSIvIMO4jEhvw,87
+typedal-3.3.0.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
+typedal-3.3.0.dist-info/RECORD,,

typedal-3.1.4.dist-info/RECORD

@@ -1,19 +0,0 @@
-typedal/__about__.py,sha256=rg1ktSg7m5s-wVEyJZGLexDBUkbBQvnRft88RSv-4tY,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=UzuTgrJF30cowpKTHI4Y4iSub9wJoxo88XmrWHRrtGs,4361
-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.1.4.dist-info/METADATA,sha256=yh1PzCqEG-XLvhPRLgD33O6fW-GAspkIKobbj7qNA5I,9270
-typedal-3.1.4.dist-info/WHEEL,sha256=KGYbc1zXlYddvwxnNty23BeaKzh7YuoSIvIMO4jEhvw,87
-typedal-3.1.4.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
-typedal-3.1.4.dist-info/RECORD,,