TypeDAL 4.8.2__tar.gz → 4.8.4__tar.gz

{typedal-4.8.2 → typedal-4.8.4}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!--next-version-placeholder-->
 
+## v4.8.4 (2026-05-28)
+
+### Fix
+
+* Improved typing on OpRow; docstrings ([`064b454`](https://github.com/trialandsuccess/TypeDAL/commit/064b4546ceb709ee6124d4a749919c4193fb3752))
+
+## v4.8.3 (2026-05-25)
+
+### Fix
+
+* Improved typing hints on TypedField properties ([`55b5ce4`](https://github.com/trialandsuccess/TypeDAL/commit/55b5ce4ae2657ae43b9cfa19dbe90e4386609495))
+
 ## v4.8.2 (2026-05-20)
 
 ### Fix

{typedal-4.8.2 → typedal-4.8.4}/PKG-INFO

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

{typedal-4.8.2 → typedal-4.8.4}/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.8.2"
+__version__ = "4.8.4"

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/caching.py

@@ -416,6 +416,8 @@ def _expired_and_valid_query() -> tuple[str, str]:
 
 
 class Stats[T](t.TypedDict):
+    """Typed container for total/valid/expired metric groups."""
+
     total: T
     valid: T
     expired: T
@@ -578,6 +580,7 @@ def memoize[T: t.Any](
     # Cache miss - compute result
 
     def track_execute(_qb: "QueryBuilder[t.Any]", raw: Rows) -> None:
+        """Collect table/id dependencies from executed raw query results."""
         # find dependant table+id combinations, includes relationships:
         deps.update(_determine_dependencies_auto(raw))
 
@@ -591,6 +594,7 @@ def memoize[T: t.Any](
         deps.update({(table, 0) for table in related_tables})
 
     def track_collect(qb: "QueryBuilder[t.Any]", _: TypedRows[t.Any], raw: Rows) -> None:
+        """Collect dependencies from `.collect()` hooks by reusing execute tracking."""
         return track_execute(qb, raw)
 
     # hooks every .collect() to track extra dependencies

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/core.py

@@ -349,6 +349,7 @@ class TypeDAL(_TypeDALBase):
         """
 
         def wrapper(cls: t.Type[T]) -> t.Type[T]:
+            """Define and return a TypedTable class bound to this DB instance."""
             return self._builder.define(cls, **kwargs)
 
         if maybe_cls:

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/define.py

@@ -30,12 +30,7 @@ from .helpers import (
 )
 from .relationships import Relationship, to_relationship
 from .tables import TypedTable
-from .types import (
-    Field,
-    T_annotation,
-    Table,
-    _Types,
-)
+from .types import Field, T_annotation, Table, _Types
 
 try:
     # python 3.14+
@@ -46,12 +41,16 @@ except ImportError:  # pragma: no cover
 
 
 class IS_IN_ENUM(Validator):
+    """Validator that accepts only values present in a specific enum."""
+
     def __init__(self, etype: type[enum.Enum], error_message: str = "value not allowed"):
+        """Initialize the enum validator."""
         super().__init__()
         self.etype = etype
         self.error_message = error_message
 
     def validate(self, value: t.Any, _record_id: int | None = None) -> t.Any:
+        """Validate and normalize an enum-compatible value."""
         if value not in self.etype:
             raise ValidationError(self.translator(self.error_message))
 

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/enum_helpers.py

@@ -1,3 +1,5 @@
+"""Helpers for parsing enum values and preserving invalid enum input context."""
+
 from __future__ import annotations
 
 import enum
@@ -7,6 +9,8 @@ from dataclasses import dataclass
 
 @dataclass(frozen=True)
 class InvalidEnumValue:
+    """Sentinel payload used when a raw value cannot be parsed into an enum member."""
+
     enum_type: type[enum.Enum]
     raw: t.Any
     value: None = None
@@ -19,6 +23,7 @@ class InvalidEnumValue:
 
 
 def enum_value_type(enum_type: type[enum.Enum]) -> type[t.Any]:
+    """Return the shared Python type of all enum member values."""
     values = [member.value for member in enum_type]
     if not values:  # pragma: no cover
         raise TypeError(f"Enum {enum_type.__name__} has no members.")
@@ -32,6 +37,7 @@ def enum_value_type(enum_type: type[enum.Enum]) -> type[t.Any]:
 
 
 def parse_enum_value(enum_type: type[enum.Enum], raw: t.Any) -> enum.Enum | InvalidEnumValue | None:
+    """Parse a raw value into an enum member or return an invalid sentinel."""
     if raw is None:  # pragma: no cover
         return None
 
@@ -43,6 +49,8 @@ def parse_enum_value(enum_type: type[enum.Enum], raw: t.Any) -> enum.Enum | Inva
 
 
 def make_enum_filter_out(enum_type: type[enum.Enum]) -> t.Callable[[t.Any], enum.Enum | InvalidEnumValue | None]:
+    """Build a parser callback for enum values."""
+
     def _filter_out(raw: t.Any) -> enum.Enum | InvalidEnumValue | None:
         return parse_enum_value(enum_type, raw)
 

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/fields.py

@@ -18,9 +18,11 @@ from pydal.objects import Table
 
 from .core import TypeDAL
 from .types import (
+    AnyCallable,
     Expression,
     Field,
     FieldSettings,
+    FileSystemLike,
     Query,
     T_annotation,
     T_MetaInstance,
@@ -50,7 +52,44 @@ class TypedField[T_Value](Expression):  # pragma: no cover
     _type: T_annotation
     kwargs: t.Any
 
+    # Typed hints for common pydal.Field attrs forwarded via __getattr__ after bind().
+    type: str | type | Table | Field | SQLCustomType
+    type_name: str
+    length: int
+    default: T_Value
+    required: bool
+    ondelete: str
+    onupdate: str
+    notnull: bool
+    unique: bool
+    regex: str | None
+    options: list[t.Any] | AnyCallable | None
+    uploadfield: bool | str
+    uploadfolder: str | None
+    uploadseparate: bool
+    uploadfs: FileSystemLike | None
+    widget: AnyCallable | None
+    label: str
+    comment: str | None
+    writable: bool
+    readable: bool
+    searchable: bool
+    listable: bool
+    update: T_Value | AnyCallable | None
+    authorize: AnyCallable | None
+    autodelete: bool
     requires: Validator | t.Iterable[Validator]
+    represent: t.Callable[[T_Value, TypedTable | None], t.Any]
+    compute: AnyCallable | None
+    custom_store: AnyCallable | None
+    custom_retrieve: AnyCallable | None
+    custom_retrieve_file_properties: AnyCallable | None
+    custom_delete: AnyCallable | None
+    filter_in: AnyCallable | None
+    filter_out: AnyCallable | None
+    custom_qualifier: AnyCallable | None
+    map_none: T_Value | None
+    _raw_rname: str | None
 
     # NOTE: for the logic of converting a TypedField into a pydal Field, see TypeDAL._to_field
 

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/mixins.py

@@ -190,7 +190,7 @@ class SlugMixin(Mixin):
 
     @classmethod
     def __generate_slug_before_insert(cls, row: OpRow) -> None:
-        if row.get("slug"):  # type: ignore
+        if row.get("slug"):
             # manually set -> skip
             return None
 

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/relationships.py

@@ -208,22 +208,32 @@ class Relationship[To_Type]:
     @t.overload
     def __get__(
         self: "Relationship[list[_RelTable]]", instance: None, owner: t.Type["TypedTable"]
-    ) -> "Relationship[list[_RelTable]]": ...
+    ) -> "Relationship[list[_RelTable]]":
+        """Return the descriptor itself when accessed on the class."""
+        ...
 
     @t.overload
     def __get__(
         self: "Relationship[list[_RelTable]]", instance: "TypedTable", owner: t.Type["TypedTable"]
-    ) -> list[_RelTable]: ...
+    ) -> list[_RelTable]:
+        """Return related rows for list-valued relationships."""
+        ...
 
     @t.overload
     def __get__(
         self: "Relationship[_RelValue]", instance: None, owner: t.Type["TypedTable"]
-    ) -> "Relationship[_RelValue]": ...
+    ) -> "Relationship[_RelValue]":
+        """Return the descriptor itself when accessed on the class."""
+        ...
 
     @t.overload
     def __get__(
-        self: "Relationship[_RelValue]", instance: "TypedTable", owner: t.Type["TypedTable"]
-    ) -> _RelValue: ...
+        self: "Relationship[_RelValue]",
+        instance: "TypedTable",
+        owner: t.Type["TypedTable"],
+    ) -> _RelValue:
+        """Return the related object for single-valued relationships."""
+        ...
 
     def __get__(
         self,

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/rows.py

@@ -61,7 +61,6 @@ class TypedRows(t.Collection[T_MetaInstance], Rows):
         `metadata` can be t.Any (un)structured data
         `model` is a Typed Table class
         """
-
         records = records or {self._get_id(row, model): model(row) for row in rows}
         raw = raw or {}
 
@@ -433,8 +432,9 @@ class TypedRows(t.Collection[T_MetaInstance], Rows):
         fields: list[Field] | None = None,
     ) -> t.Generator[T_MetaInstance, None, None] | T_MetaInstance:
         """
-        Takes an index and returns a copy of the indexed row with values
-        transformed via the "represent" attributes of the associated fields.
+        Take an index and return a copy of the indexed row with values.
+
+        Values are transformed via the "represent" attributes of the associated fields.
 
         Args:
             i: index. If not specified, a generator is returned for iteration

{typedal-4.8.2 → typedal-4.8.4}/src/typedal/types.py

@@ -62,7 +62,7 @@ class TableProtocol(t.Protocol):  # pragma: no cover
 
     def on(self, query: "QueryLike") -> "Expression | _Expression":
         """
-        pydal Table.on(query) helper used in join callbacks.
+        PyDAL `Table.on(query)` helper used in join callbacks.
         """
 
 
@@ -112,13 +112,26 @@ if t.TYPE_CHECKING:
         Pydal OpRow object for typing (otherwise mypy thinks it's Any).
         """
 
+        def __getattr__(self, name: str) -> t.Any:
+            """Dynamic attribute access (e.g. row.email)."""
+
         def __getitem__(self, item: str) -> t.Any:
             """row.item syntax."""
 
         def __setitem__(self, key: str, value: t.Any) -> None:
             """row.item = key syntax."""
 
-        # more methods could be added
+        def get(self, key: str, default: t.Any = None) -> t.Any:
+            """Dictionary-like get used by update hooks."""
+
+        def keys(self) -> t.Iterable[str]:
+            """Dictionary-like key access."""
+
+        def items(self) -> t.Iterable[tuple[str, t.Any]]:
+            """Dictionary-like item iteration."""
+
+        def values(self) -> t.Iterable[t.Any]:
+            """Dictionary-like value iteration."""
 
 else:
 

{typedal-4.8.2 → typedal-4.8.4}/typing_again.py

@@ -33,3 +33,8 @@ reveal_type(row.rel)  # expected: OtherTable | None; pycharm: Relationship[Other
 
 reveal_type(MyTable.multiple) # expected: Relationship[list[OtherTable]]; pycharm: Relationship[list[OtherTable]]
 reveal_type(row.multiple)  # expected: list[OtherTable]; pycharm: Relationship[list[OtherTable]]
+
+
+
+MyTable.field.label = "Test Label"
+MyTable.field.represent = lambda value, row: "Test Repr"