TypeDAL 3.0.1__py3-none-any.whl → 3.1.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.0.1"
+__version__ = "3.1.1"

typedal/core.py

@@ -1317,15 +1317,16 @@ class TypedField(typing.Generic[T_Value]):  # pragma: no cover
         return typing.cast(Expression, ~self._field)
 
 
-class TypedTable(metaclass=TableMeta):
+class _TypedTable:
     """
-    Enhanded modeling system on top of pydal's Table that adds typing and additional functionality.
-    """
-
-    # set up by 'new':
-    _row: Row | None = None
+    This class is a final shared parent between TypedTable and Mixins.
 
-    _with: list[str]
+    This needs to exist because otherwise the __on_define__ of Mixins are not executed.
+    Notably, this class exists at a level ABOVE the `metaclass=TableMeta`,
+        because otherwise typing gets confused when Mixins are used and multiple types could satisfy
+            generic 'T subclass of TypedTable'
+        -> Setting 'TypedTable' as the parent for Mixin does not work at runtime (and works semi at type check time)
+    """
 
     id: "TypedField[int]"
 
@@ -1336,6 +1337,26 @@ class TypedTable(metaclass=TableMeta):
     _before_delete: list[BeforeDeleteCallable]
     _after_delete: list[AfterDeleteCallable]
 
+    @classmethod
+    def __on_define__(cls, db: TypeDAL) -> None:
+        """
+        Method that can be implemented by tables to do an action after db.define is completed.
+
+        This can be useful if you need to add something like requires=IS_NOT_IN_DB(db, "table.field"),
+        where you need a reference to the current database, which may not exist yet when defining the model.
+        """
+
+
+class TypedTable(_TypedTable, metaclass=TableMeta):
+    """
+    Enhanded modeling system on top of pydal's Table that adds typing and additional functionality.
+    """
+
+    # set up by 'new':
+    _row: Row | None = None
+
+    _with: list[str]
+
     def _setup_instance_methods(self) -> None:
         self.as_dict = self._as_dict  # type: ignore
         self.__json__ = self.as_json = self._as_json  # type: ignore
@@ -1382,15 +1403,6 @@ class TypedTable(metaclass=TableMeta):
         inst._setup_instance_methods()
         return inst
 
-    @classmethod
-    def __on_define__(cls, db: TypeDAL) -> None:
-        """
-        Method that can be implemented by tables to do an action after db.define is completed.
-
-        This can be useful if you need to add something like requires=IS_NOT_IN_DB(db, "table.field"),
-        where you need a reference to the current database, which may not exist yet when defining the model.
-        """
-
     def __iter__(self) -> typing.Generator[Any, None, None]:
         """
         Allows looping through the columns.

typedal/for_web2py.py

@@ -24,6 +24,8 @@ class AuthGroup(TypedTable):
         """
         When we have access to 'db', set the NOT IN DB requirement to make the role unique.
         """
+        super().__on_define__(db)
+
         cls.role.requires = IS_NOT_IN_DB(db, "w2p_auth_group.role")
 
 

typedal/helpers.py

@@ -25,19 +25,28 @@ def is_union(some_type: type | types.UnionType) -> bool:
     return typing.get_origin(some_type) in (types.UnionType, typing.Union)
 
 
+def reversed_mro(cls: type) -> typing.Iterable[type]:
+    """
+    Get the Method Resolution Order (mro) for a class, in reverse order to be used with ChainMap.
+    """
+    return reversed(getattr(cls, "__mro__", []))
+
+
 def _all_annotations(cls: type) -> ChainMap[str, type]:
     """
     Returns a dictionary-like ChainMap that includes annotations for all \
     attributes defined in cls or inherited from superclasses.
     """
-    return ChainMap(*(c.__annotations__ for c in getattr(cls, "__mro__", []) if "__annotations__" in c.__dict__))
+    # chainmap reverses the iterable, so reverse again beforehand to keep order normally:
+
+    return ChainMap(*(c.__annotations__ for c in reversed_mro(cls) if "__annotations__" in c.__dict__))
 
 
 def all_dict(cls: type) -> AnyDict:
     """
     Get the internal data of a class and all it's parents.
     """
-    return dict(ChainMap(*(c.__dict__ for c in getattr(cls, "__mro__", []))))
+    return dict(ChainMap(*(c.__dict__ for c in reversed_mro(cls))))  # type: ignore
 
 
 def all_annotations(cls: type, _except: typing.Iterable[str] = None) -> dict[str, type]:

typedal/mixins.py

@@ -0,0 +1,135 @@
+"""
+This file contains example Mixins.
+
+Mixins can add reusable fields and behavior (optimally both, otherwise it doesn't add much).
+"""
+
+import base64
+import os
+import typing
+from datetime import datetime
+from typing import Any
+
+from slugify import slugify
+
+from .core import TypedTable  # noqa F401 - used by example in docstring
+from .core import TypeDAL, _TypedTable
+from .fields import DatetimeField, StringField
+from .types import OpRow, Set
+
+
+class Mixin(_TypedTable):
+    """
+    A mixin should be derived from this class.
+
+    The mixin base class itself doesn't do anything,
+    but using it makes sure the mixin fields are placed AFTER the table's normal fields (instead of before)
+
+    During runtime, mixin should not have a base class in order to prevent MRO issues
+        ('inconsistent method resolution' or 'metaclass conflicts')
+    """
+
+
+class TimestampsMixin(Mixin):
+    """
+    A Mixin class for adding timestamp fields to a model.
+    """
+
+    created_at = DatetimeField(default=datetime.now, writable=False)
+    updated_at = DatetimeField(default=datetime.now, writable=False)
+
+    @classmethod
+    def __on_define__(cls, db: TypeDAL) -> None:
+        """
+        Hook called when defining the model to initialize timestamps.
+
+        Args:
+            db (TypeDAL): The database layer.
+        """
+        super().__on_define__(db)
+
+        def set_updated_at(_: Set, row: OpRow) -> None:
+            """
+            Callback function to update the 'updated_at' field before saving changes.
+
+            Args:
+                _: Set: Unused parameter.
+                row (OpRow): The row to update.
+            """
+            row["updated_at"] = datetime.now()
+
+        cls._before_update.append(set_updated_at)
+
+
+def slug_random_suffix(length: int = 8) -> str:
+    """
+    Generate a random suffix to make slugs unique, even when titles are the same.
+
+    UUID4 uses 16 bytes, but 8 is probably more than enough given you probably don't have THAT much duplicate titles.
+    Strip away '=' to make it URL-safe
+        (even though 'urlsafe_b64encode' sounds like it should already be url-safe - it is not)
+    """
+    return base64.urlsafe_b64encode(os.urandom(length)).rstrip(b"=").decode().strip("=")
+
+
+class SlugMixin(Mixin):
+    """
+    (Opinionated) example mixin to add a 'slug' field, which depends on a user-provided other field.
+
+    Some random bytes are added at the end to prevent duplicates.
+
+    Example:
+        >>> class MyTable(TypedTable, SlugMixin, slug_field="some_name"):
+        >>>    some_name: str
+        >>>    ...
+    """
+
+    # pub:
+    slug = StringField(unique=True)
+    # priv:
+    __settings__: typing.TypedDict(  # type: ignore
+        "SlugFieldSettings",
+        {
+            "slug_field": str,
+            "slug_suffix": int,
+        },
+    )  # set via init subclass
+
+    def __init_subclass__(cls, slug_field: str = None, slug_suffix: int = 8, **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).
+        """
+        # unfortunately, PyCharm and mypy do not recognize/autocomplete/typecheck init subclass (keyword) arguments.
+        if slug_field is None:
+            raise ValueError(
+                "SlugMixin requires a valid slug_field setting: "
+                "e.g. `class MyClass(TypedTable, SlugMixin, slug_field='title'): ...`"
+            )
+
+        cls.__settings__ = {
+            "slug_field": slug_field,
+            "slug_suffix": slug_suffix,
+        }
+
+    @classmethod
+    def __on_define__(cls, db: TypeDAL) -> None:
+        """
+        When db is available, include a before_insert hook to generate and include a slug.
+        """
+        super().__on_define__(db)
+
+        # slugs should not be editable (for SEO reasons), so there is only a before insert hook:
+        def generate_slug_before_insert(row: OpRow) -> None:
+            settings = cls.__settings__
+
+            text_input = row[settings["slug_field"]]
+            generated_slug = slugify(text_input)
+
+            if suffix_len := settings["slug_suffix"]:
+                generated_slug += f"-{slug_random_suffix(suffix_len)}"
+
+            row["slug"] = slugify(generated_slug)
+
+        cls._before_insert.append(generate_slug_before_insert)

typedal/web2py_py4web_shared.py

@@ -33,6 +33,8 @@ class AuthUser(TypedTable):
         """
         When we have access to 'db', set the IS_NOT_IN_DB requirement.
         """
+        super().__on_define__(db)
+
         cls.email.requires = (
             IS_EMAIL(),
             IS_NOT_IN_DB(

{typedal-3.0.1.dist-info → typedal-3.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: TypeDAL
-Version: 3.0.1
+Version: 3.1.1
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues
@@ -19,8 +19,9 @@ Requires-Dist: configurable-json
 Requires-Dist: configuraptor>=1.26.2
 Requires-Dist: dill
 Requires-Dist: pydal
+Requires-Dist: python-slugify
 Provides-Extra: all
-Requires-Dist: edwh-migrate>=0.8.0b1; extra == 'all'
+Requires-Dist: edwh-migrate>=0.8.0; extra == 'all'
 Requires-Dist: py4web; extra == 'all'
 Requires-Dist: pydal2sql[all]>=1.1.3; extra == 'all'
 Requires-Dist: questionary; extra == 'all'
@@ -37,7 +38,7 @@ Requires-Dist: su6[all]; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Requires-Dist: types-tabulate; extra == 'dev'
 Provides-Extra: migrations
-Requires-Dist: edwh-migrate>=0.8.0b1; extra == 'migrations'
+Requires-Dist: edwh-migrate>=0.8.0; extra == 'migrations'
 Requires-Dist: pydal2sql>=1.1.3; extra == 'migrations'
 Requires-Dist: questionary; extra == 'migrations'
 Requires-Dist: tabulate; extra == 'migrations'
@@ -59,7 +60,7 @@ Description-Content-Type: text/markdown
 Typing support for [PyDAL](http://web2py.com/books/default/chapter/29/6).
 This package aims to improve the typing support for PyDAL. By using classes instead of the define_table method,
 type hinting the result of queries can improve the experience while developing. In the background, the queries are still
-generated and executed by pydal itself, this package only proves some logic to properly pass calls from class methods to
+generated and executed by pydal itself, this package only provides some logic to properly pass calls from class methods to
 the underlying `db.define_table` pydal Tables.
 
 - `TypeDAL` is the replacement class for DAL that manages the code on top of DAL.
@@ -75,13 +76,49 @@ the underlying `db.define_table` pydal Tables.
 
 Version 2.0 also introduces more ORM-like funcionality.
 Most notably, a Typed Query Builder that sees your table classes as models with relationships to each other.
-See [3. Building Queries](https://github.com/trialandsuccess/TypeDAL/blob/master/docs/3_building_queries.md) for more
+See [3. Building Queries](https://typedal.readthedocs.io/en/stable/3_building_queries/) for more
 details.
 
-## Quick Overview
+## CLI
+The Typedal CLI provides a convenient interface for generating SQL migrations for [edwh-migrate](https://github.com/educationwarehouse/migrate#readme)
+from PyDAL or TypeDAL configurations using [pydal2sql](https://github.com/robinvandernoord/pydal2sql). 
+It offers various commands to streamline database management tasks.
 
-Below you'll find a quick overview of translation from pydal to TypeDAL. For more info,
-see [the docs](https://typedal.readthedocs.io/en/latest/).
+### Usage
+
+```bash
+typedal --help
+```
+
+## Options
+
+- `--show-config`: Toggle to show configuration details. Default is `no-show-config`.
+- `--version`: Toggle to display version information. Default is `no-version`.
+- `--install-completion`: Install completion for the current shell.
+- `--show-completion`: Show completion for the current shell, for copying or customization.
+- `--help`: Display help message and exit.
+
+## Commands
+
+- `cache.clear`: Clear expired items from the cache.
+- `cache.stats`: Show caching statistics.
+- `migrations.fake`: Mark one or more migrations as completed in the database without executing the SQL code.
+- `migrations.generate`: Run `pydal2sql` based on the TypeDAL configuration.
+- `migrations.run`: Run `edwh-migrate` based on the TypeDAL configuration.
+- `setup`: Interactively setup a `[tool.typedal]` entry in the local `pyproject.toml`.
+
+### Configuration
+
+TypeDAL and its CLI can be configured via `pyproject.toml`.  
+See [6. Migrations](https://typedal.readthedocs.io/en/stable/6_migrations/) for more information about configuration.
+
+
+## TypeDAL for PyDAL users - Quick Overview
+
+Below you'll find a quick overview of translation from pydal to TypeDAL.  
+For more info, see **[the docs](https://typedal.readthedocs.io/en/latest/)**.
+
+---
 
 ### Translations from pydal to typedal
 
@@ -258,7 +295,7 @@ row: TableName = db.table_name(id=1)
 
 ### All Types
 
-See [2. Defining Tables](docs/2_defining_tables.md)
+See [2. Defining Tables](https://typedal.readthedocs.io/en/stable/2_defining_tables/)
 
 ## Caveats
 

typedal-3.1.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+typedal/__about__.py,sha256=OTBqn2XOHv_4-hOGbfVC29HOywMZOEFQS_8L6KP94Y4,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=zkjuSmfkDAagahiOE43__dpd3cYNwqlIXnX-qGz1VDQ,95613
+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=stGjFBWPtRHteGJa3F6c-z9SPcYzFa2ToEbS9qlXEB0,4345
+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.1.dist-info/METADATA,sha256=TlBsIu6-i1xGFDGHPw76tFtE8I4oambuIGOVEbt2dyE,9270
+typedal-3.1.1.dist-info/WHEEL,sha256=KGYbc1zXlYddvwxnNty23BeaKzh7YuoSIvIMO4jEhvw,87
+typedal-3.1.1.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
+typedal-3.1.1.dist-info/RECORD,,

{typedal-3.0.1.dist-info → typedal-3.1.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.0.1.dist-info/RECORD

@@ -1,18 +0,0 @@
-typedal/__about__.py,sha256=8UfBCir8PsjPHcCRJyA0FLS1a3orteNLkZd6vHHlXjc,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=nHJ2Iq67rFIB4j43KCCD-tLIjvvvf4oJhT9T6tjXqxU,95063
-typedal/fields.py,sha256=z2PD9vLWqBR_zXtiY0DthqTG4AeF3yxKoeuVfGXnSdg,5197
-typedal/for_py4web.py,sha256=d07b8hL_PvNDUS26Z5fDH2OxWb-IETBuAFPSzrRwm04,1285
-typedal/for_web2py.py,sha256=zvd5xC-SmuKc0JLDqT3hMIs6COaYnwTFXD_BIeC1vug,1832
-typedal/helpers.py,sha256=n9dpIjXIjPpVFQnLBQreTWqRDR6hIsoNt8vGdEHGo_s,6871
-typedal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-typedal/types.py,sha256=1kGkNX6vfGg6ln84AG558C4Zx5ACRz-emrUTnuy-rRY,3410
-typedal/web2py_py4web_shared.py,sha256=cEbjkK0WOS9Q0nTyZuQaJWffeP4bjrL79Bx0xGy_UOs,1504
-typedal/serializers/as_json.py,sha256=ffo152W-sARYXym4BzwX709rrO2-QwKk2KunWY8RNl4,2229
-typedal-3.0.1.dist-info/METADATA,sha256=GTmtFnSnOhgJI-P_hriMxRSZJf1EkEu9cT6eV2APM0s,7782
-typedal-3.0.1.dist-info/WHEEL,sha256=uNdcs2TADwSd5pVaP0Z_kcjcvvTUklh2S7bxZMF8Uj0,87
-typedal-3.0.1.dist-info/entry_points.txt,sha256=m1wqcc_10rHWPdlQ71zEkmJDADUAnZtn7Jac_6mbyUc,44
-typedal-3.0.1.dist-info/RECORD,,