TypeDAL 4.4.5__tar.gz → 4.5.0__tar.gz

{typedal-4.4.5 → typedal-4.5.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!--next-version-placeholder-->
 
+## v4.5.0 (2026-03-06)
+
+### Feature
+
+* **typing:** Support mixin-typed table class APIs without MRO conflicts ([`fe0c99e`](https://github.com/trialandsuccess/TypeDAL/commit/fe0c99eb2790baff8ddf4de3ec1f23c53e4b3a11))
+
+## v4.4.6 (2026-03-05)
+
+### Fix
+
+* Support .first() when using querybuilder on pydal-style tables. ([`d75f254`](https://github.com/trialandsuccess/TypeDAL/commit/d75f25440f0dcca51991bc047bf7ce8d479f942b))
+
+### Documentation
+
+* Make docs up-to-date with recently introduced features, improve reading flow for new users ([`64bb7be`](https://github.com/trialandsuccess/TypeDAL/commit/64bb7be220c5f1a5998940b320565b5a3dbca988))
+
 ## v4.4.5 (2026-02-27)
 
 ### Fix

{typedal-4.4.5 → typedal-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypeDAL
-Version: 4.4.5
+Version: 4.5.0
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues
@@ -81,13 +81,49 @@ the underlying `db.define_table` pydal Tables.
   e.g. `rows: TypedRows[SomeTable] = db(...).select()`. When using the QueryBuilder, a `TypedRows` instance is returned
   by `.collect()`.
 
-Version 2.0 also introduces more ORM-like funcionality.
+Version 2.0 also introduces more ORM-like functionality.
 Most notably, a Typed Query Builder that sees your table classes as models with relationships to each other.
 See [3. Building Queries](https://typedal.readthedocs.io/en/stable/3_building_queries/) for more
 details.
 
+## Quickstart
+
+```bash
+uv pip install typedal
+# alternative:
+pip install typedal
+```
+
+```python
+from typedal import TypeDAL, TypedTable
+
+db = TypeDAL("sqlite:memory")
+# Alternatives:
+# db = TypeDAL("sqlite://storage.sqlite")
+# db = TypeDAL("postgres://user:password@localhost:5432/mydb")
+# db = TypeDAL("mysql://user:password@localhost:3306/mydb")
+# ...
+
+@db.define()
+class User(TypedTable):
+    name: str
+    age: int | None
+
+
+User.insert(name="Alice", age=30)
+adults = User.where(User.age >= 18).collect()
+print(adults.column("name"))  # ['Alice']
+```
+
+If you are new to TypeDAL, start with:
+
+1. [Getting Started](https://typedal.readthedocs.io/en/stable/1_getting_started/)
+2. [Defining Tables](https://typedal.readthedocs.io/en/stable/2_defining_tables/)
+3. [Building Queries](https://typedal.readthedocs.io/en/stable/3_building_queries/)
+4. [Relationships](https://typedal.readthedocs.io/en/stable/4_relationships/)
+
 ## CLI
-The Typedal CLI provides a convenient interface for generating SQL migrations for [edwh-migrate](https://github.com/educationwarehouse/migrate#readme)
+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.
 
@@ -252,7 +288,7 @@ row = db.table_name(id=1)  # -> Any (Row)
 # all:
 all_rows = TableName.collect()  # or .all()
 # some:
-# order of select and where is interchangable here
+# order of select and where is interchangeable here
 rows = TableName.select(Tablename.id).where(TableName.id > 5).where(TableName.id < 50).collect()
 # one:
 row = TableName(id=1)  # or .where(...).first()
@@ -330,13 +366,10 @@ db.commit() # this is usually done automatically but sometimes you want to manua
 
 ## Caveats
 
-- This package depends heavily on the current implementation of annotations (which are computed when the class is
-  defined). PEP 563 (Postponed Evaluation of Annotations, accepted) aims to change this behavior (
-  and `from __future__ import annotations` already does) in a way that this module currently can not handle: all
-  annotations are converted to string representations. This makes it very hard to re-evaluate the annotation into the
-  original type, since the variable scope is lost (and thus references to variables or other classes are ambiguous or
-  simply impossible to find).
+- Some editors (notably PyCharm) cannot always distinguish class-level and instance-level access on the same symbol.
+  For example, `Model.somefield` is a field descriptor (query operations like `.belongs()`), while
+  `model.somefield` is the runtime value (for example `list[str]`).
 - `TypedField` limitations; Since pydal implements some magic methods to perform queries, some features of typing will
   not work on a typed field: `typing.Optional` or a union (`Field() | None`) will result in errors. The only way to make
   a typedfield optional right now, would be to set `required=False` as an argument yourself. This is also a reason
-  why `typing.get_type_hints` is not a solution for the first caveat.
+  why `typing.get_type_hints` is not a complete solution.

{typedal-4.4.5 → typedal-4.5.0}/README.md

@@ -24,13 +24,49 @@ the underlying `db.define_table` pydal Tables.
   e.g. `rows: TypedRows[SomeTable] = db(...).select()`. When using the QueryBuilder, a `TypedRows` instance is returned
   by `.collect()`.
 
-Version 2.0 also introduces more ORM-like funcionality.
+Version 2.0 also introduces more ORM-like functionality.
 Most notably, a Typed Query Builder that sees your table classes as models with relationships to each other.
 See [3. Building Queries](https://typedal.readthedocs.io/en/stable/3_building_queries/) for more
 details.
 
+## Quickstart
+
+```bash
+uv pip install typedal
+# alternative:
+pip install typedal
+```
+
+```python
+from typedal import TypeDAL, TypedTable
+
+db = TypeDAL("sqlite:memory")
+# Alternatives:
+# db = TypeDAL("sqlite://storage.sqlite")
+# db = TypeDAL("postgres://user:password@localhost:5432/mydb")
+# db = TypeDAL("mysql://user:password@localhost:3306/mydb")
+# ...
+
+@db.define()
+class User(TypedTable):
+    name: str
+    age: int | None
+
+
+User.insert(name="Alice", age=30)
+adults = User.where(User.age >= 18).collect()
+print(adults.column("name"))  # ['Alice']
+```
+
+If you are new to TypeDAL, start with:
+
+1. [Getting Started](https://typedal.readthedocs.io/en/stable/1_getting_started/)
+2. [Defining Tables](https://typedal.readthedocs.io/en/stable/2_defining_tables/)
+3. [Building Queries](https://typedal.readthedocs.io/en/stable/3_building_queries/)
+4. [Relationships](https://typedal.readthedocs.io/en/stable/4_relationships/)
+
 ## CLI
-The Typedal CLI provides a convenient interface for generating SQL migrations for [edwh-migrate](https://github.com/educationwarehouse/migrate#readme)
+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.
 
@@ -195,7 +231,7 @@ row = db.table_name(id=1)  # -> Any (Row)
 # all:
 all_rows = TableName.collect()  # or .all()
 # some:
-# order of select and where is interchangable here
+# order of select and where is interchangeable here
 rows = TableName.select(Tablename.id).where(TableName.id > 5).where(TableName.id < 50).collect()
 # one:
 row = TableName(id=1)  # or .where(...).first()
@@ -273,13 +309,10 @@ db.commit() # this is usually done automatically but sometimes you want to manua
 
 ## Caveats
 
-- This package depends heavily on the current implementation of annotations (which are computed when the class is
-  defined). PEP 563 (Postponed Evaluation of Annotations, accepted) aims to change this behavior (
-  and `from __future__ import annotations` already does) in a way that this module currently can not handle: all
-  annotations are converted to string representations. This makes it very hard to re-evaluate the annotation into the
-  original type, since the variable scope is lost (and thus references to variables or other classes are ambiguous or
-  simply impossible to find).
+- Some editors (notably PyCharm) cannot always distinguish class-level and instance-level access on the same symbol.
+  For example, `Model.somefield` is a field descriptor (query operations like `.belongs()`), while
+  `model.somefield` is the runtime value (for example `list[str]`).
 - `TypedField` limitations; Since pydal implements some magic methods to perform queries, some features of typing will
   not work on a typed field: `typing.Optional` or a union (`Field() | None`) will result in errors. The only way to make
   a typedfield optional right now, would be to set `required=False` as an argument yourself. This is also a reason
-  why `typing.get_type_hints` is not a solution for the first caveat.
+  why `typing.get_type_hints` is not a complete solution.

typedal-4.5.0/docs/10_advanced_apis.md

@@ -0,0 +1,76 @@
+# 10. Advanced APIs
+
+This chapter documents a few public APIs that are useful in specific cases, but are not part of the default onboarding flow.
+
+## QueryBuilder on old-style pyDAL tables
+
+If you are migrating incrementally, you can still use TypeDAL's query builder on existing pyDAL tables:
+
+```python
+from typedal import QueryBuilder
+
+rows = QueryBuilder(db.some_table).where(id=2).collect()
+```
+
+This gives you partial builder ergonomics while keeping your existing table definitions.
+
+> **Important:** support is intentionally limited for old-style tables.
+> Internally, `.collect()` is effectively a passthrough to `.execute()` and returns regular pyDAL `Rows`.
+> `.first()`/`.first_or_fail()` return a regular pyDAL `Row` in this mode.
+
+### Verified working methods
+
+- Query composition: `.where(...)`, `.select(...)`, `.orderby(...)`, `.groupby(...)`, `.having(...)`
+- Execution/introspection: `.execute()`, `.collect()`, `.to_sql()`
+- Row access: `.first()`, `.first_or_fail()`
+- Pagination helpers: `.paginate()`, `.chunk()`
+- Basic set operations: `.count()`, `.exists()`, `.update(...)`, `.delete(...)`, `.collect_or_fail()`
+- `.cache(...).collect()` runs (returns pyDAL `Rows`)
+
+### Verified unsupported methods
+
+- `.join(...)`: **not supported** for old-style tables (depends on TypeDAL model relationship internals)
+
+### Behavioral caveat
+
+Legacy mode does not perform typed model mapping. Expect pyDAL `Rows`/`Row` outputs rather than typed entities.
+
+If you need full QueryBuilder behavior (typed entities, relationships, typed joins, cache integration), 
+migrate that table to `TypedTable`.
+
+## Upsert and validation helpers
+
+`TypedTable` exposes convenience methods for common upsert/validation flows:
+
+```python
+# update if found, otherwise insert
+user = User.update_or_insert(User.email == "a@example.com", email="a@example.com", name="Alice")
+
+# validate before insert
+created, errors = User.validate_and_insert(email="a@example.com")
+
+# validate before update
+updated, errors = User.validate_and_update(User.id == 1, name="Alice Updated")
+
+# validate before update-or-insert
+row, errors = User.validate_and_update_or_insert(User.email == "a@example.com", name="Alice")
+```
+
+Behavior notes:
+
+- `update_or_insert(...)` returns the resulting instance.
+- `validate_and_*` methods return `(instance_or_none, errors_or_none)`.
+
+## Reordering table fields
+
+You can reorder fields on a defined table with `reorder_fields`:
+
+```python
+# Keep listed fields first, keep all other fields after them
+MyTable.reorder_fields(MyTable.id, MyTable.name)
+
+# Keep only the listed fields
+MyTable.reorder_fields(MyTable.id, MyTable.name, keep_others=False)
+```
+
+This is useful when you want deterministic field order for SQL generation, inspection, or exports.

{typedal-4.4.5 → typedal-4.5.0}/docs/2_defining_tables.md

@@ -40,7 +40,7 @@ Any keyword arguments you would pass to `db.define_table`, you can also pass to
 | `Field('name', 'time')`                   | `name: datetime.time`        | `name: TypedField[datetime.time]`      | `name = TypedField(datetime.time)`        | `name = TimeField()`                 |
 | `Field('name', 'datetime')`               | `name: datetime.datetime`    | `name: TypedField[datetime.datetime]`  | `name = TypedField(datetime.datetime)`    | `name = DatetimeField()`             |
 | `Field('name', 'password')`               | ×                            | ×                                      | `name = TypedField(str, type="password")` | `name = PasswordField()`             |
-| `Field('name', 'upload')`                 | ×                            | ×                                      | `name = TypedField(str, type="upload)`    | `name = UploadField()`               |
+| `Field('name', 'upload')`                 | ×                            | ×                                      | `name = TypedField(str, type="upload")`   | `name = UploadField()`               |
 | `Field('name', 'reference <table>')`      | `name: Table`                | `name: TypedField[Table]`              | `name = TypedField(Table)`                | `name = ReferenceField('table')`     |
 | `Field('name', 'list:string')`            | `name: list[str]`            | `name: TypedField[list[str]]`          | `name = TypedField(list[str])`            | `name = ListStringField()`           |
 | `Field('name', 'list:integer')`           | `name: list[int]`            | `name: TypedField[list[int]]`          | `name = TypedField()`                     | `name = ListIntegerField()`          |
@@ -104,4 +104,4 @@ row.delete_record() # to trigger
 MyTable.where(...).delete() # to trigger
 ```
 
-"Now that we have some tables, it's time to actually query them! Let's go to [3. Building Queries](./3_building_queries.md) to learn how.
+Now that we have some tables, it's time to actually query them! Let's go to [3. Building Queries](./3_building_queries.md) to learn how.

{typedal-4.4.5 → typedal-4.5.0}/docs/3_building_queries.md

@@ -236,8 +236,8 @@ The Query Builder has a few operations that don't return a new builder instance:
 - first: get the first entity matching your query, possibly with relationships loaded (if .join was used)
 - first_or_fail: where `first` may return an empty result, this variant will raise an error if there are no results.
 - to_sql: get the SQL string that would run, useful for debugging, subqueries and other advanced SQL operations.
-- update: instead of selecting rows, update those matching the current query (see [Delete](#delete))
-- delete: instead of selecting rows, delete those matching the current query (see [Update](#update))
+- update: instead of selecting rows, update those matching the current query (see [Update](#update))
+- delete: instead of selecting rows, delete those matching the current query (see [Delete](#delete))
 
 Additionally, you can directly call `.all()`, `.collect()`, `.count()`, `.first()` on a model (e.g. `User.all()`).
 
@@ -264,7 +264,7 @@ person.update_record(name="New Name")
 db(db.person.name == "Old Name").delete()
 
 row = db.person(4)
-row.update_record(name="New Name")
+row.delete_record()
 
 # typedal:
 Person.where(id="Old Name").delete()  # via query builder
@@ -272,3 +272,8 @@ Person.where(id="Old Name").delete()  # via query builder
 person = Person(4)
 person.delete_record()
 ```
+
+---
+
+Need less-common query patterns (for example, using `QueryBuilder` on old-style pyDAL tables)?
+See [10. Advanced APIs](./10_advanced_apis.md).

{typedal-4.4.5 → typedal-4.5.0}/docs/4_relationships.md

@@ -98,6 +98,30 @@ In this example, `Relationship["Sidekick"]` is added as an extra type hint, sinc
 after the superhero class.
 Adding the `Relationship["Sidekick"]` hint is optional, but recommended to improve editor support.
 
+### Forward References with `Ref[...]` (typing helper)
+
+For relationship targets, you can use `Ref[...]` as a typed replacement for the string form:
+
+```python
+from typedal.relationships import Ref
+
+bestie = relationship(Ref["BestFriend"], lambda user, bestie: user.id == bestie.friend)
+```
+
+This is equivalent at runtime to:
+
+```python
+bestie = relationship("BestFriend", lambda user, bestie: user.id == bestie.friend)
+```
+
+`Ref[...]` is primarily for type-checking/editor support. It does not change runtime behavior.
+
+For normal table fields, `Ref[...]` is not needed. Use standard forward-reference annotations, for example:
+
+```python
+owner: "User"
+```
+
 ## Many-to-Many
 
 Setting up a relationship that uses a junction/pivot table is slightly harder.
@@ -199,4 +223,3 @@ Depending on your setup:
 - **Using py4web or web2py?** → [5. py4web & web2py](./5_py4web.md)
 - **Ready to manage your database?** → [6. Migrations](./6_migrations.md)
 - **Dive deeper into functionality?** → [8.: Mixins](./8_mixins.md)
-

{typedal-4.4.5 → typedal-4.5.0}/docs/7_configuration.md

@@ -55,7 +55,7 @@ noop = false
 ### Generating Migrations (pydal2sql)
 
 - **`input`**: Path to your TypeDAL table definitions file
-- **`output`**: Path to the generated migration `.py` fil
+- **`output`**: Path to the generated migration `.py` file
 - **`dialect`**: Database type: `sqlite`, `postgres`, `mysql`, etc. (if unclear from database uri)
 - **`magic`**: Insert missing variables to prevent crashes (default: `true`).
   See [pydal2sql docs](https://github.com/robinvandernoord/pydal2sql#configuration).

{typedal-4.4.5 → typedal-4.5.0}/docs/9_memoization.md

@@ -148,3 +148,8 @@ class SpecialTable(TypedTable):
 ```
 
 **Warning:** Disabling this may break caching functionality for queries involving this table.
+
+---
+
+Want to explore less common but useful APIs (like old-style pyDAL `QueryBuilder`, validation/upsert helpers, and field reordering)?
+Continue with [10. Advanced APIs](./10_advanced_apis.md).

{typedal-4.4.5 → typedal-4.5.0}/docs/index.md

@@ -9,3 +9,4 @@
 7. [Advanced Configuration](./7_configuration.md)
 8. [Mixins](./8_mixins.md)
 9. [Function Memoization](./9_memoization.md)
+10. [Advanced APIs](./10_advanced_apis.md)

{typedal-4.4.5 → typedal-4.5.0}/mkdocs.yml

@@ -11,6 +11,7 @@ nav:
   - 7. Configuration: 7_configuration.md
   - 8. Mixins: 8_mixins.md
   - 9. Function Memoization: 9_memoization.md
+  - 10. Advanced APIs: 10_advanced_apis.md
 extra:
   version:
     default: stable
@@ -40,4 +41,4 @@ theme:
 
 extra_css:
   - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/tokyo-night-dark.min.css
-  - css/code_blocks.css
+  - css/code_blocks.css

{typedal-4.4.5 → typedal-4.5.0}/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.4.5"
+__version__ = "4.5.0"

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/cli.py

@@ -392,7 +392,8 @@ def fake_migrations(
 
     previously_migrated = (
         db(
-            db.ewh_implemented_features.name.belongs(to_fake) & (db.ewh_implemented_features.installed == True)  # noqa E712
+            db.ewh_implemented_features.name.belongs(to_fake)
+            & (db.ewh_implemented_features.installed == True)  # noqa E712
         )
         .select(db.ewh_implemented_features.name)
         .column("name")

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/fields.py

@@ -31,7 +31,7 @@ from .types import (
 
 if t.TYPE_CHECKING:
     # will be imported for real later:
-    from .tables import TypedTable
+    from .tables import TypedTable, _TypedTable
 
 
 ## general
@@ -79,7 +79,7 @@ class TypedField(Expression, t.Generic[T_Value]):  # pragma: no cover
         """
 
     @t.overload
-    def __get__(self, instance: None, owner: "t.Type[TypedTable]") -> "TypedField[T_Value]":  # pragma: no cover
+    def __get__(self, instance: None, owner: "t.Type[_TypedTable]") -> "TypedField[T_Value]":  # pragma: no cover
         """
         Table.field -> Field.
         """

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/mixins.py

@@ -16,21 +16,18 @@ from slugify import slugify
 
 from .core import TypeDAL
 from .fields import DatetimeField, StringField
-from .tables import _TypedTable
+from .tables import TableMeta, _TypedTable
 from .types import OpRow, Set, T_MetaInstance
 
-if t.TYPE_CHECKING:
-    from .tables import TypedTable  # noqa: F401
 
-
-class Mixin(_TypedTable):
+class Mixin(_TypedTable, metaclass=TableMeta):
     """
     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
+    During runtime, mixin should not inherit from TypedTable to prevent MRO issues
         ('inconsistent method resolution' or 'metaclass conflicts')
     """
 

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/query_builder.py

@@ -23,7 +23,7 @@ from .helpers import (
     normalize_table_keys,
     throw,
 )
-from .tables import TableMeta, TypedTable
+from .tables import TableMeta, TypedTable, _TypedTable
 from .types import (
     CacheMetadata,
     Condition,
@@ -698,7 +698,7 @@ class QueryBuilder(t.Generic[T_MetaInstance]):
         return joins
 
     def _build_inner_joins_recursive(
-        self, relation: Relationship[t.Any], parent_table: t.Type[TypedTable], key: str, parent_key: str = ""
+        self, relation: Relationship[t.Any], parent_table: t.Type[_TypedTable], key: str, parent_key: str = ""
     ) -> list[t.Any]:
         """Recursively build inner joins for a relationship and its nested relationships."""
         db = self._get_db()
@@ -764,7 +764,7 @@ class QueryBuilder(t.Generic[T_MetaInstance]):
         key: str,
         select_args: list[t.Any],
         left_joins: list[Expression],
-        parent_table: t.Type[TypedTable],
+        parent_table: t.Type[_TypedTable],
         parent_key: str = "",
     ) -> list[t.Any]:
         """Process a single relationship for left join and field selection."""
@@ -1133,11 +1133,16 @@ class QueryBuilder(t.Generic[T_MetaInstance]):
 
         Also adds paginate, since it would be a waste to select more rows than needed.
         """
-        if row := self.paginate(page=1, limit=1, verbose=verbose).first():
-            return self.model.from_row(row)
-        else:
+        row = self.paginate(page=1, limit=1, verbose=verbose).first()
+        if not row:
             return None
 
+        if not isinstance(self.model, TableMeta):
+            # old-style pydal table: keep pydal semantics and return raw Row
+            return row
+
+        return self.model.from_row(row)
+
     def _first(self) -> str:
         return self._paginate(page=1, limit=1)
 

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/relationships.py

@@ -184,7 +184,7 @@ class Relationship(t.Generic[To_Type]):
             return db._config.lazy_policy
 
         # conservative fallback:
-        return "warn"
+        return "warn"  # pragma: no cover
 
     def get_table_name(self) -> str:
         """

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/rows.py

@@ -400,11 +400,27 @@ class TypedRows(t.Collection[T_MetaInstance], Rows):
         self.__dict__.update(state)
         # db etc. set after undill by caching.py
 
+    @t.overload
     def render(
         self,
-        i: int | None = None,
+        i: None = None,
         fields: list[Field] | None = None,
     ) -> t.Generator[T_MetaInstance, None, None]:
+        """With no index, yield rendered rows as a generator."""
+
+    @t.overload
+    def render(
+        self,
+        i: int,
+        fields: list[Field] | None = None,
+    ) -> T_MetaInstance:
+        """With an index, return one rendered row instance."""
+
+    def render(
+        self,
+        i: int | None = None,
+        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.

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/tables.py

@@ -650,7 +650,7 @@ class TableMeta(type):
         return reorder_fields(cls._table, fields, keep_others=keep_others)
 
 
-class _TypedTable:
+class _TypedTable(metaclass=TableMeta):
     """
     This class is a final shared parent between TypedTable and Mixins.
 
@@ -661,6 +661,9 @@ class _TypedTable:
         -> Setting 'TypedTable' as the parent for Mixin does not work at runtime (and works semi at type check time)
     """
 
+    # This class contains weird typing glue to dodge MRO headaches without losing editor/mypy table methods
+    # you can safely ignore it when changing runtime behavior; touch it only for typing/mypy issues
+
     id: "TypedField[int]"
 
     _before_insert: list[t.Callable[[t.Self], t.Optional[bool]] | t.Callable[[OpRow], t.Optional[bool]]]
@@ -671,6 +674,8 @@ class _TypedTable:
     _after_update: list[t.Callable[[Set, t.Self], t.Optional[bool]] | t.Callable[[Set, OpRow], t.Optional[bool]]]
     _before_delete: list[t.Callable[[Set], t.Optional[bool]]]
     _after_delete: list[t.Callable[[Set], t.Optional[bool]]]
+    _rows: tuple[Row, ...]
+    _with: list[str]
 
     @classmethod
     def __on_define__(cls, db: TypeDAL) -> None:
@@ -681,16 +686,49 @@ class _TypedTable:
         where you need a reference to the current database, which may not exist yet when defining the model.
         """
 
-    @classproperty
-    def _hooks(cls) -> dict[str, list[t.Callable[..., t.Optional[bool]]]]:
-        return {
-            "before_insert": cls._before_insert,
-            "after_insert": cls._after_insert,
-            "before_update": cls._before_update,
-            "after_update": cls._after_update,
-            "before_delete": cls._before_delete,
-            "after_delete": cls._after_delete,
-        }
+    def __new__(cls, *_args: t.Any, **_kwargs: t.Any) -> t.Self:
+        """
+        Shared constructor signature for typing.
+
+        TypedTable provides the concrete behavior; this base only keeps static typing happy
+        for generic classmethod flows that instantiate `self(...)`.
+        """
+        return super().__new__(cls)
+
+    # Add an abstract placeholder here only when generic code is typed against
+    # `T_MetaInstance` (bound to `_TypedTable`) and directly calls/accesses that member.
+    # If a member is only used on concrete `TypedTable` paths, it should stay on `TypedTable`.
+    def _ensure_matching_row(self) -> Row:
+        # Typed on the shared base so generic instance helpers can call into row access safely.
+        raise NotImplementedError  # pragma: no cover
+
+    def _update(self: t.Self, **fields: t.Any) -> t.Self:
+        # Declared here for generic update flows; real behavior is implemented in TypedTable.
+        raise NotImplementedError  # pragma: no cover
+
+    def _update_record(self: t.Self, **fields: t.Any) -> t.Self:
+        # Declared here for generic update flows; real behavior is implemented in TypedTable.
+        raise NotImplementedError  # pragma: no cover
+
+    def update_record(self: t.Self, **fields: t.Any) -> t.Self:
+        # Declared here for generic update flows; real behavior is implemented in TypedTable.
+        raise NotImplementedError  # pragma: no cover
+
+    def as_dict(self, *args: t.Any, **kwargs: t.Any) -> AnyDict:
+        # Broad signature keeps class/instance serialization overrides LSP-compatible.
+        raise NotImplementedError  # pragma: no cover
+
+    def render(self: t.Self, *fields: t.Any, **kwargs: t.Any) -> t.Self:
+        # Rows/QueryBuilder treat render as model-preserving, so this returns Self for typing.
+        raise NotImplementedError  # pragma: no cover
+
+    def __getitem__(self, key: str) -> t.Any:
+        # Relationship collection writes into model instances via dict-style access.
+        raise NotImplementedError  # pragma: no cover
+
+    def __setitem__(self, key: str, value: t.Any) -> None:
+        # Relationship collection writes into model instances via dict-style access.
+        raise NotImplementedError  # pragma: no cover
 
 
 class TypedTable(_TypedTable, metaclass=TableMeta):
@@ -702,8 +740,21 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
     _row: Row | None = None
     _rows: tuple[Row, ...] = ()
 
+    id: "TypedField[int]"
+
     _with: list[str]
 
+    @classproperty
+    def _hooks(cls) -> dict[str, list[t.Callable[..., t.Optional[bool]]]]:
+        return {
+            "before_insert": cls._before_insert,
+            "after_insert": cls._after_insert,
+            "before_update": cls._before_update,
+            "after_update": cls._after_update,
+            "before_delete": cls._before_delete,
+            "after_delete": cls._after_delete,
+        }
+
     def _setup_instance_methods(self) -> None:
         self.as_dict = self._as_dict  # type: ignore
         self.__json__ = self.as_json = self._as_json  # type: ignore
@@ -990,7 +1041,7 @@ class TypedTable(_TypedTable, metaclass=TableMeta):
     def _update_record(self: T_MetaInstance, **fields: t.Any) -> T_MetaInstance:
         row = self._ensure_matching_row()
         new_row = row.update_record(**fields)
-        self.update(**new_row)
+        self._update(**new_row)
         return self
 
     def update_record(self: T_MetaInstance, **fields: t.Any) -> T_MetaInstance:  # pragma: no cover

{typedal-4.4.5 → typedal-4.5.0}/src/typedal/types.py

@@ -35,7 +35,7 @@ except ImportError:
 # Internal references
 if t.TYPE_CHECKING:
     from .fields import TypedField
-    from .tables import TypedTable
+    from .tables import TypedTable, _TypedTable
 
 # ---------------------------------------------------------------------------
 # Aliases
@@ -297,7 +297,7 @@ T = t.TypeVar("T", bound=t.Any)
 P = t.ParamSpec("P")
 R = t.TypeVar("R")
 
-T_MetaInstance = t.TypeVar("T_MetaInstance", bound="TypedTable")
+T_MetaInstance = t.TypeVar("T_MetaInstance", bound="_TypedTable")
 T_Query = t.Union[
     "Table",
     Query,

{typedal-4.4.5 → typedal-4.5.0}/tests/test_mypy.py

@@ -10,6 +10,7 @@ from typedal import (  # todo: why does src.typedal not work anymore?
     TypedRows,
     TypedTable,
 )
+from typedal.mixins import Mixin
 from typedal.types import CacheFn, CacheTuple, OpRow, Reference, Rows
 
 db = TypeDAL("sqlite:memory")
@@ -29,6 +30,14 @@ class OtherTable(TypedTable): ...
 class LaterDefine(TypedTable): ...
 
 
+class SearchMixin(Mixin): ...
+
+
+@db.define
+class SearchableTable(TypedTable, SearchMixin):
+    title: str
+
+
 old_style = db.define_table("old_table")
 
 
@@ -152,6 +161,21 @@ def mypy_test_query() -> None:
     reveal_type(MyTable.where().column(MyTable.fancy))  # R: builtins.list[builtins.str]
 
 
+@pytest.mark.mypy_testing
+def mypy_test_rows_render_overload() -> None:
+    rows = MyTable.where().collect()
+    reveal_type(rows.render())  # R: typing.Generator[tests.test_mypy.MyTable, None, None]
+    reveal_type(rows.render(1))  # R: tests.test_mypy.MyTable
+
+
+@pytest.mark.mypy_testing
+def mypy_test_mixin_typed_table_argument() -> None:
+    def using_mixin(table: type[SearchMixin]) -> None:
+        reveal_type(table.where())  # R: typedal.query_builder.QueryBuilder[tests.test_mypy.SearchMixin]
+
+    using_mixin(SearchableTable)
+
+
 @pytest.mark.mypy_testing
 def mypy_test_cachefn() -> None:
     def cache_model(key: str, fn: CacheFn, expire: int) -> Rows:

{typedal-4.4.5 → typedal-4.5.0}/tests/test_query_builder.py

@@ -526,6 +526,14 @@ def test_minimal_functionality_on_pydal_style_tables():
     assert qb2
     assert len(qb2) == 1
 
+    first = QueryBuilder(db.test_query_table).where(number=2).first()
+    assert first
+    assert first.id == qb1.first().id
+
+    first_or_fail = QueryBuilder(db.test_query_table).where(number=2).first_or_fail()
+    assert first_or_fail
+    assert first_or_fail.id == qb1.first().id
+
 
 def test_before_after_collect(capsys):
     _setup_data()

typedal-4.4.5/.crush/.gitignore

@@ -1 +0,0 @@
-*

typedal-4.4.5/.crush/logs/crush.log

@@ -1,37 +0,0 @@
-{"time":"2026-01-20T14:19:21.359487106+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":55},"msg":"Fetching providers from Catwalk"}
-{"time":"2026-01-20T14:19:21.518115889+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":63},"msg":"Catwalk providers not modified"}
-{"time":"2026-01-20T14:19:21.52626179+01:00","level":"INFO","msg":"OK   20250424200609_initial.sql (1.52ms)"}
-{"time":"2026-01-20T14:19:21.526651475+01:00","level":"INFO","msg":"OK   20250515105448_add_summary_message_id.sql (330.71µs)"}
-{"time":"2026-01-20T14:19:21.526995425+01:00","level":"INFO","msg":"OK   20250624000000_add_created_at_indexes.sql (325.29µs)"}
-{"time":"2026-01-20T14:19:21.527303588+01:00","level":"INFO","msg":"OK   20250627000000_add_provider_to_messages.sql (293.15µs)"}
-{"time":"2026-01-20T14:19:21.52790648+01:00","level":"INFO","msg":"OK   20250810000000_add_is_summary_message.sql (495.71µs)"}
-{"time":"2026-01-20T14:19:21.528316924+01:00","level":"INFO","msg":"OK   20250812000000_add_todos_to_sessions.sql (389.38µs)"}
-{"time":"2026-01-20T14:19:21.528324939+01:00","level":"INFO","msg":"goose: successfully migrated database to version: 20250812000000"}
-{"time":"2026-01-20T14:19:21.528356959+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).initLSPClients","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":21},"msg":"LSP clients initialization started in background"}
-{"time":"2026-01-20T14:19:21.52843831+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":102},"msg":"Initializing MCP clients"}
-{"time":"2026-01-20T14:21:06.413595152+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:21:14.539289381+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:21:15.710688424+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/agent/tools.init.func1","file":"github.com/charmbracelet/crush/internal/agent/tools/rg.go","line":18},"msg":"Ripgrep (rg) not found in $PATH. Some grep features might be limited or slower."}
-{"time":"2026-01-20T14:21:17.08089755+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:21:17.151106375+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:22:05.503761296+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:26:05.030425805+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:36:26.778665189+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T14:38:51.314473736+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T15:02:22.602405814+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).Shutdown.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":403},"msg":"Shutdown took 6.62949ms"}
-{"time":"2026-01-20T15:02:23.719585648+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":55},"msg":"Fetching providers from Catwalk"}
-{"time":"2026-01-20T15:02:23.881789126+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":63},"msg":"Catwalk providers not modified"}
-{"time":"2026-01-20T15:02:23.884044691+01:00","level":"INFO","msg":"goose: no migrations to run. current version: 20250812000000"}
-{"time":"2026-01-20T15:02:23.884082792+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).initLSPClients","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":21},"msg":"LSP clients initialization started in background"}
-{"time":"2026-01-20T15:02:23.884273487+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":102},"msg":"Initializing MCP clients"}
-{"time":"2026-01-20T15:04:13.024457515+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T15:04:14.232072885+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/agent/tools.init.func1","file":"github.com/charmbracelet/crush/internal/agent/tools/rg.go","line":18},"msg":"Ripgrep (rg) not found in $PATH. Some grep features might be limited or slower."}
-{"time":"2026-01-20T15:11:24.612161916+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).Shutdown.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":403},"msg":"Shutdown took 9.537141ms"}
-{"time":"2026-01-20T15:11:25.263960575+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":55},"msg":"Fetching providers from Catwalk"}
-{"time":"2026-01-20T15:11:25.431990051+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.(*catwalkSync).Get.func1","file":"github.com/charmbracelet/crush/internal/config/catwalk.go","line":63},"msg":"Catwalk providers not modified"}
-{"time":"2026-01-20T15:11:25.434282035+01:00","level":"INFO","msg":"goose: no migrations to run. current version: 20250812000000"}
-{"time":"2026-01-20T15:11:25.434366662+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).initLSPClients","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":21},"msg":"LSP clients initialization started in background"}
-{"time":"2026-01-20T15:11:25.434579879+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":102},"msg":"Initializing MCP clients"}
-{"time":"2026-01-20T15:24:40.456010578+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).generateTitle","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":788},"msg":"generated title with small model"}
-{"time":"2026-01-20T15:24:51.673808433+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/agent/tools.init.func1","file":"github.com/charmbracelet/crush/internal/agent/tools/rg.go","line":18},"msg":"Ripgrep (rg) not found in $PATH. Some grep features might be limited or slower."}
-{"time":"2026-01-20T15:26:03.868420566+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/agent.(*sessionAgent).Cancel","file":"github.com/charmbracelet/crush/internal/agent/agent.go","line":907},"msg":"Request cancellation initiated","session_id":"4c2d1684-8db2-4ffd-83bb-9c08fe850f29"}