TypeDAL 4.7.1__tar.gz → 4.7.2__tar.gz

{typedal-4.7.1 → typedal-4.7.2}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 <!--next-version-placeholder-->
 
+## v4.7.2 (2026-04-20)
+
+### Fix
+
+* **enums:** Add safe enum parsing helper and docs for mixed-type rejection + invalid DB sentinel ([`33ee169`](https://github.com/trialandsuccess/TypeDAL/commit/33ee169b61522cf7a863e29c68822a3b0e07d376))
+
 ## v4.7.1 (2026-04-20)
 
 ### Fix

{typedal-4.7.1 → typedal-4.7.2}/PKG-INFO

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

{typedal-4.7.1 → typedal-4.7.2}/docs/2_defining_tables.md

@@ -51,6 +51,37 @@ Any keyword arguments you would pass to `db.define_table`, you can also pass to
 | `Field('name', 'big-id')`                            | ×                                           | ×                                                                   | ×                                                                     | ×                                               |
 | `Field('name', 'big-reference')`                     | ×                                           | ×                                                                   | ×                                                                     | ×                                               |
 
+### Enum fields
+
+TypeDAL supports `enum.Enum` subclasses directly (including `enum.StrEnum` and `enum.IntEnum`):
+
+```python
+import enum
+
+
+class Status(enum.StrEnum):
+    DRAFT = "draft"
+    PUBLISHED = "published"
+
+
+class Priority(enum.IntEnum):
+    LOW = 1
+    HIGH = 2
+
+
+@db.define()
+class Article(TypedTable):
+    status: Status
+    priority: Priority
+```
+
+Important constraints and behavior:
+
+- All enum member values in one enum must share the same underlying Python type for DB fields.
+  Mixed enums (for example `str` + `int` in one enum class) raise `TypeError` when defining the table.
+- Reading rows with invalid enum values in the database does not crash. Those values are returned as
+  `typedal.enum_helpers.InvalidEnumValue`, where `.value` is `None`.
+
 ### Making a field required/optional
 
 | pydal                                    | typedal (native python type)                                              | typedal (using TypedField annotation)                                                             | typedal (using TypedField)                            | typedal (using specific Field)       |

{typedal-4.7.1 → typedal-4.7.2}/src/typedal/__about__.py

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

{typedal-4.7.1 → typedal-4.7.2}/src/typedal/define.py

@@ -17,6 +17,7 @@ from pydal.validators import IS_IN_SET, ValidationError, Validator
 
 from .constants import BASIC_MAPPINGS
 from .core import TypeDAL, evaluate_forward_reference, resolve_annotation
+from .enum_helpers import enum_value_type, make_enum_filter_out
 from .fields import TypedField, is_typed_field
 from .helpers import (
     all_annotations,
@@ -178,10 +179,10 @@ class TableDefinitionBuilder:
             _child_type = type(t.get_args(ftype)[0])
             return self.annotation_to_pydal_fieldtype(_child_type, mut_kw)
         elif isinstance(ftype, type) and issubclass(ftype, enum.Enum):
-            _values = [v.value for v in ftype]
-            _child_type = type(_values[0])
+            _child_type = enum_value_type(ftype)
             # mut_kw.setdefault("requires", [IS_IN_SET(_values)])
             mut_kw.setdefault("requires", [IS_IN_ENUM(ftype)])
+            mut_kw.setdefault("filter_out", make_enum_filter_out(ftype))
             return self.annotation_to_pydal_fieldtype(_child_type, mut_kw)
         elif isinstance(ftype, types.GenericAlias) and t.get_origin(ftype) in (list, TypedField):
             # list[str] -> str -> string -> list:string

typedal-4.7.2/src/typedal/enum_helpers.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import enum
+import typing as t
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class InvalidEnumValue:
+    enum_type: type[enum.Enum]
+    raw: t.Any
+    value: None = None
+
+
+def enum_value_type(enum_type: type[enum.Enum]) -> type[t.Any]:
+    values = [member.value for member in enum_type]
+    if not values:  # pragma: no cover
+        raise TypeError(f"Enum {enum_type.__name__} has no members.")
+
+    first_type = type(values[0])
+    if any(type(value) is not first_type for value in values):
+        raise TypeError(
+            f"Enum {enum_type.__name__} has mixed value types; all values must share one type for DB fields.",
+        )
+    return first_type
+
+
+def parse_enum_value(enum_type: type[enum.Enum], raw: t.Any) -> enum.Enum | InvalidEnumValue | None:
+    if raw is None:  # pragma: no cover
+        return None
+
+    if isinstance(raw, enum_type):  # pragma: no cover
+        return raw
+
+    value_map = {str(member.value): member for member in enum_type}
+    return value_map.get(str(raw), InvalidEnumValue(enum_type=enum_type, raw=raw))
+
+
+def make_enum_filter_out(enum_type: type[enum.Enum]) -> t.Callable[[t.Any], enum.Enum | InvalidEnumValue | None]:
+    def _filter_out(raw: t.Any) -> enum.Enum | InvalidEnumValue | None:
+        return parse_enum_value(enum_type, raw)
+
+    return _filter_out

{typedal-4.7.1 → typedal-4.7.2}/tests/test_main.py

@@ -10,6 +10,7 @@ import pytest
 
 from src.typedal import TypedRows
 from src.typedal.__about__ import __version__
+from src.typedal.enum_helpers import InvalidEnumValue
 from src.typedal.fields import *
 
 
@@ -193,14 +194,12 @@ def test_dont_allow_bool_in_query():
 
 def test_invalid_union():
     with pytest.raises(NotImplementedError):
-
         @db.define
         class Invalid(TypedTable):
             valid: int | None
             invalid: int | str
 
     with pytest.raises(NotImplementedError):
-
         @db.define
         class Invalid(TypedTable):
             valid: list[int]
@@ -278,7 +277,6 @@ def test_typedfield_to_field_type():
         optional_two = TypedField(str | None)
 
     with pytest.raises(NotImplementedError):
-
         @db.define()
         class Invalid(TypedTable):
             third = TypedField(dict[str, int])  # not supported
@@ -592,7 +590,8 @@ def test_forward_reference_class_314():
     class WithFakeRef(TypedTable):
         fwd: Fake
 
-    class Future(TypedTable): ...
+    class Future(TypedTable):
+        ...
 
     # note: this still has to be defined first because otherwise pydal can't create a database relation!:
     assert db.define(Future)
@@ -643,34 +642,52 @@ def test_reorder_fields():
 
 
 def test_literal_enum_fields():
-    class TestEnum(enum.Enum):
+    class MixedEnum(enum.Enum):
         FIRST = "first"
         SECOND = 2
 
+    with pytest.raises(TypeError, match="mixed value types"):
+        @db.define()
+        class MixedLiteralTable(TypedTable):
+            enum_one: MixedEnum
+
+    class TestStrEnum(enum.StrEnum):
+        FIRST = "first"
+        SECOND = "second"
+
+    class TestIntEnum(enum.IntEnum):
+        FIRST = 1
+        SECOND = 2
+
     @db.define()
     class LiteralTable(TypedTable):
         lit_one: t.Literal["first", "second"]
         lit_two = TypedField(t.Literal["first", "second"])
 
-        enum_one: TestEnum
-        enum_two = TypedField(TestEnum)
+        enum_one: TestStrEnum
+        enum_two = TypedField(TestIntEnum)
 
     # should be ok
     row, err = LiteralTable.validate_and_insert(
         lit_one="first",
         lit_two="second",
-        enum_one=TestEnum.FIRST,
+        enum_one=TestStrEnum.FIRST,
         enum_two=2,
     )
     assert not err, "unexpected error"
     assert row, "expected row"
 
+    assert isinstance(row.enum_one, TestStrEnum)
+    assert row.enum_one.value == "first"
+    assert isinstance(row.enum_two, TestIntEnum)
+    assert row.enum_two == TestIntEnum.SECOND
+
     # should error on lit_one
     row, err = LiteralTable.validate_and_insert(
         lit_one="wrong",
         lit_two="wronger",
-        enum_one=1,
-        enum_two="two",
+        enum_one="invalid",
+        enum_two=-1,
     )
     assert not row, "unexpected row"
     assert err, "expected err"
@@ -679,3 +696,17 @@ def test_literal_enum_fields():
     assert "lit_two" in err
     assert "enum_one" in err
     assert "enum_two" in err
+
+    idx = db.executesql("""
+                        INSERT INTO literal_table(lit_one, lit_two, enum_one, enum_two)
+                            VALUES ('fake', 'fake', 'fake', 999)
+                            RETURNING id
+                        """)[0][0]
+
+    invalid_row = LiteralTable(idx)
+    assert isinstance(invalid_row.enum_one, InvalidEnumValue)
+    assert invalid_row.enum_one.raw == "fake"
+    assert invalid_row.enum_one.value is None
+    assert isinstance(invalid_row.enum_two, InvalidEnumValue)
+    assert invalid_row.enum_two.raw == 999
+    assert invalid_row.enum_two.value is None

typedal-4.7.1/release_4_7.md

@@ -1,139 +0,0 @@
-# TypeDAL 4.7: A literal improvement to Enums
-
-**Release date:** 20-04-2026
-
----
-
-TypeDAL v4.7 introduces native support for `typing.Literal` and `enum.Enum` as field types.
-No more manually wiring `IS_IN_SET` validators for constrained values.
-
-## What's New
-
-### `typing.Literal` fields
-
-Declare a field with a fixed set of allowed string/integer values and TypeDAL automatically infers the database type and
-attaches an `IS_IN_SET` validator:
-
-```python
-from typing import Literal
-
-
-@db.define()
-class Ticket(TypedTable):
-    status: Literal["open", "in_progress", "closed"]
-    priority: Literal[1, 2, 3]
-```
-
-### `Enum` fields
-
-Use Python `Enum` classes directly. TypeDAL extracts the values, infers the underlying type, and applies an `IS_IN_ENUM`
-validator:
-
-```python
-import enum
-
-
-class Color(enum.Enum):
-    RED = "red"
-    GREEN = "green"
-    BLUE = "blue"
-
-
-@db.define()
-class Palette(TypedTable):
-    color: Color
-```
-
-The `IS_IN_ENUM` validator accepts both enum members and their raw values:
-
-```python
-row = Palette(color=Color.RED)   # via enum member
-row = Palette(color="red")       # via raw value
-```
-
-## Other changes since v4.6
-
-These fixes landed incrementally between v4.6 and now (shipped as 4.6.1–4.6.4):
-Included here as a recap for users upgrading from 4.6.0 directly to 4.7.
-
-### collect_into
-
-Collect query results into a different model class. A practical use case is
-returning a safe API-facing view from the same underlying table:
-
-The `init` callback is optional and only needed for per-row runtime enrichment.
-Without an explicit `.select(...)`, TypeDAL maps fields declared on the target model.
-
-```python
-@db.define()
-class User(TypedTable):
-    id: int
-    email: str
-    password_hash: str
-    is_active: bool
-
-class PublicUser(TypedTable):
-    """Same users table, but safe for API responses."""
-    id: int
-    email: str
-    is_active: bool
-    # note: no password_hash
-    profile_url: str | None = None
-
-def enrich_profile_url(row: PublicUser, _raw):
-    row.profile_url = f"/users/{row.id}"
-
-rows = (
-    User.where(is_active=True)
-    # note: `init` is optional
-    .collect_into(PublicUser, init=enrich_profile_url)
-)
-row = rows.first()
-assert isinstance(row, PublicUser)
-assert hasattr(row, "profile_url")
-assert "password_hash" not in row
-```
-
-The cache is isolated per model class, so `.cache().collect_into(PublicUser)`
-and a regular `.cache().collect()` do not interfere.
-
-### render() → as_dict() consistency
-
-As of this fix, calling `.render()` on a row also affects subsequent
-`.as_dict()` output:
-
-```python
-row = db.article(1).render()
-row.as_dict()  # now returns the rendered representation, not raw pydal dict
-```
-
-### Pydantic visibility / readable=False
-
-Fields marked with `readable=False` are now excluded from generated Pydantic
-schemas, matching pydal/py4web behavior. Visibility and lazy-load filtering has
-also been moved into the schema-converter path so it applies consistently to
-FastAPI endpoints.
-
-### Mixin typing without MRO conflicts
-
-Mixin-based table classes now type-check properly in mypy and PyCharm while
-keeping runtime MRO clean:
-
-```python
-class SearchMixin(Mixin):
-    @classmethod
-    def by_title(cls, title: str):
-        return cls.where(title=title)
-
-@db.define()
-class SearchableTable(TypedTable, SearchMixin):
-    title: str
-
-def search(table: type[SearchMixin], q: str):
-    table.by_title(q)  # fully typed now
-```
-
-## 📜 Changelog
-
-For all details, see the full changelog:
-**[CHANGELOG.md](https://github.com/trialandsuccess/TypeDAL/blob/master/CHANGELOG.md)**