TypeDAL 4.4.4__tar.gz → 4.4.6__tar.gz

{typedal-4.4.4 → typedal-4.4.6}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 <!--next-version-placeholder-->
 
+## 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
+
+* Add `Ref` type so you can do forward references in types, ([`3240a74`](https://github.com/trialandsuccess/TypeDAL/commit/3240a747a4dd63a887464c0a748c68907d38d7d0))
+* Pass known classes as namespace so `col: "ForwardRef"` works in 3.13 too ([`b655da8`](https://github.com/trialandsuccess/TypeDAL/commit/b655da812d7ea014b95adf73974ca301a6c42ca2))
+
 ## v4.4.4 (2026-02-25)
 
 ### Fix

{typedal-4.4.4 → typedal-4.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypeDAL
-Version: 4.4.4
+Version: 4.4.6
 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.4 → typedal-4.4.6}/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.4.6/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/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.4"
+__version__ = "4.4.6"

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/caching.py

@@ -577,7 +577,7 @@ def memoize(
         return cached, "cached"
     # Cache miss - compute result
 
-    def track_execute(_qb: "QueryBuilder[t.Any]", raw: Rows):
+    def track_execute(_qb: "QueryBuilder[t.Any]", raw: Rows) -> None:
         # find dependant table+id combinations, includes relationships:
         deps.update(_determine_dependencies_auto(raw))
 

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/config.py

@@ -9,13 +9,11 @@ from pathlib import Path
 
 import tomli
 from configuraptor import TypedConfig, alias
-from configuraptor.helpers import find_pyproject_toml
+from configuraptor.helpers import expand_env_vars_into_toml_values, find_pyproject_toml
 from dotenv import dotenv_values, find_dotenv
 
 from .types import AnyDict
 
-from configuraptor.helpers import expand_env_vars_into_toml_values
-
 if t.TYPE_CHECKING:
     from edwh_migrate import Config as MigrateConfig
     from pydal2sql.typer_support import Config as P2SConfig

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/core.py

@@ -106,27 +106,27 @@ def evaluate_forward_reference(
         return evaluate_forward_reference_314(fw_ref, namespace=namespace or {})
 
 
-def resolve_annotation_313(ftype: str) -> type:  # pragma: no cover
+def resolve_annotation_313(ftype: str, namespace: dict[str, type] | None = None) -> type:  # pragma: no cover
     """
     Resolve an annotation that's in string representation.
 
     Variant for Python 3.13
     """
     fw_ref: ForwardRef = t.get_args(t.Type[ftype])[0]
-    return evaluate_forward_reference(fw_ref)
+    return evaluate_forward_reference(fw_ref, namespace=namespace)
 
 
-def resolve_annotation_314(ftype: str) -> type:  # pragma: no cover
+def resolve_annotation_314(ftype: str, namespace: dict[str, type] | None = None) -> type:  # pragma: no cover
     """
     Resolve an annotation that's in string representation.
 
     Variant for Python 3.14 + using annotationlib
     """
     fw_ref = ForwardRef(ftype)
-    return evaluate_forward_reference(fw_ref)
+    return evaluate_forward_reference(fw_ref, namespace=namespace)
 
 
-def resolve_annotation(ftype: str) -> type:  # pragma: no cover
+def resolve_annotation(ftype: str, namespace: dict[str, type] | None = None) -> type:  # pragma: no cover
     """
     Resolve an annotation that's in string representation.
 
@@ -135,9 +135,9 @@ def resolve_annotation(ftype: str) -> type:  # pragma: no cover
     if sys.version_info.major != 3:
         raise EnvironmentError("Only python 3 is supported.")
     elif sys.version_info.minor <= 13:
-        return resolve_annotation_313(ftype)
+        return resolve_annotation_313(ftype, namespace=namespace)
     else:
-        return resolve_annotation_314(ftype)
+        return resolve_annotation_314(ftype, namespace=namespace)
 
 
 class TypeDAL(pydal.DAL):

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/define.py

@@ -133,13 +133,13 @@ class TableDefinitionBuilder:
         """Convert Python type annotation to pydal field type string."""
         ftype = t.cast(type, ftype_annotation)  # cast from Type to type to make mypy happy)
 
+        known_classes = {table.__name__: table for table in self.class_map.values()}
+
         if isinstance(ftype, str):
             # extract type from string
-            ftype = resolve_annotation(ftype)
+            ftype = resolve_annotation(ftype, namespace=known_classes)
 
         if isinstance(ftype, ForwardRef):
-            known_classes = {table.__name__: table for table in self.class_map.values()}
-
             ftype = evaluate_forward_reference(ftype, namespace=known_classes)
 
         if mapping := BASIC_MAPPINGS.get(ftype):

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/mixins.py

@@ -116,7 +116,7 @@ class HAS_UNIQUE_SLUG(IS_NOT_IN_DB):
         if not value.strip():
             raise ValidationError(self.translator(self.error_message))
 
-        (tablename, fieldname) = str(self.field).split(".")
+        tablename, fieldname = str(self.field).split(".")
         table = self.dbset.db[tablename]
         field = table[fieldname]
         query = field == value

{typedal-4.4.4 → typedal-4.4.6}/src/typedal/query_builder.py

@@ -555,7 +555,7 @@ class QueryBuilder(t.Generic[T_MetaInstance]):
         for fn_before in db._before_execute:
             fn_before(self)
 
-        rows = db(query).select(*select_args, **select_kwargs)
+        rows: Rows = db(query).select(*select_args, **select_kwargs)
 
         for fn_after in db._after_execute:
             fn_after(self, rows)
@@ -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.4 → typedal-4.4.6}/src/typedal/relationships.py

@@ -5,17 +5,18 @@ Contains base functionality related to Relationships.
 import inspect
 import typing as t
 import warnings
+from typing import ForwardRef
 
 import pydal.objects
 
 from .config import LazyPolicy
 from .constants import JOIN_OPTIONS
-from .core import TypeDAL
+from .core import TypeDAL, evaluate_forward_reference
 from .fields import TypedField
 from .helpers import extract_type_optional, looks_like, unwrap_type
 from .types import Condition, OnQuery, T_Field
 
-To_Type = t.TypeVar("To_Type")
+To_Type = t.TypeVar("To_Type", bound="TypedTable")
 
 
 # default lazy policy is defined at the TypeDAL() instance settings level
@@ -63,6 +64,10 @@ class Relationship(t.Generic[To_Type]):
         self.condition_and = condition_and
         self._lazy = lazy
 
+        if t.get_origin(_type) == Ref:
+            # unwrap Ref["City"] to ForwardRef("City") to be evaluated/stringified later on:
+            _type = t.get_args(_type)[0]
+
         if args := t.get_args(_type):
             self.table = unwrap_type(args[0])
             self.multiple = True
@@ -70,6 +75,12 @@ class Relationship(t.Generic[To_Type]):
             self.table = t.cast(type[TypedTable], _type)
             self.multiple = False
 
+        if isinstance(self.table, ForwardRef):
+            try:
+                self.table = evaluate_forward_reference(self.table)
+            except Exception:
+                self.table = self.table.__forward_arg__
+
         if isinstance(self.table, str):
             self.table = TypeDAL.to_snake(self.table)
 
@@ -264,6 +275,18 @@ class Relationship(t.Generic[To_Type]):
             return fallback_value
 
 
+class Ref(t.Generic[To_Type]):
+    """
+    Type-level forward reference wrapper.
+
+    Allows writing:
+
+        relationship(Ref["User"])
+
+    so that type checkers resolve the inner type correctly.
+    """
+
+
 @t.overload
 def relationship(
     _type: type[list[To_Type]],
@@ -286,7 +309,7 @@ def relationship(
 
 @t.overload
 def relationship(
-    _type: t.Type[To_Type] | str,
+    _type: t.Type[To_Type] | str | t.Type[Ref[To_Type]],
     condition: Condition = None,
     *,
     join: t.Literal["inner"],
@@ -308,7 +331,7 @@ def relationship(
 
 @t.overload
 def relationship(
-    _type: t.Type[To_Type] | str,
+    _type: t.Type[To_Type] | str | t.Type[Ref[To_Type]],
     condition: Condition = None,
     join: JOIN_OPTIONS = None,
     on: OnQuery = None,
@@ -327,7 +350,7 @@ def relationship(
 
 
 def relationship(
-    _type: type[list[To_Type]] | t.Type[To_Type] | str,
+    _type: type[list[To_Type]] | t.Type[To_Type] | str | t.Type[Ref[To_Type]],
     condition: Condition = None,
     join: JOIN_OPTIONS = None,
     on: OnQuery = None,

{typedal-4.4.4 → typedal-4.4.6}/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.4 → typedal-4.4.6}/tests/test_relationships.py

@@ -8,7 +8,7 @@ from uuid import uuid4
 
 import pytest
 
-from src.typedal import Relationship, TypeDAL, TypedField, TypedTable, relationship
+from src.typedal import Relationship, TypeDAL, TypedField, TypedRows, TypedTable, relationship
 from src.typedal.caching import (
     _TypedalCache,
     _TypedalCacheDependency,
@@ -16,8 +16,8 @@ from src.typedal.caching import (
     clear_expired,
     remove_cache,
 )
+from src.typedal.relationships import Ref
 from src.typedal.serializers import as_json
-from typedal import TypedRows
 
 db = TypeDAL("sqlite:memory", lazy_policy="warn")
 
@@ -970,7 +970,8 @@ class Office(TypedTable):
     city_id: City
     company: "Company"
 
-    city_alternative = relationship(City, lambda office, city: office.city_id == city.id)
+    city = relationship(City, lambda office, city: office.city_id == city.id)
+    city_alternative = relationship(Ref["City"], lambda office, city: office.city_id == city.id)
 
 
 class Company(TypedTable):

typedal-4.4.4/.crush/.gitignore

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

typedal-4.4.4/.crush/logs/crush.log

@@ -1,34 +0,0 @@
-{"time":"2026-01-26T17:01:48.91963488+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-26T17:01:49.11634171+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-26T17:01:49.116589785+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/config.(*Config).configureProviders","file":"github.com/charmbracelet/crush/internal/config/load.go","line":259},"msg":"Skipping provider due to missing API key","provider":"anthropic"}
-{"time":"2026-01-26T17:01:49.128053484+01:00","level":"INFO","msg":"OK   20250424200609_initial.sql (1.26ms)"}
-{"time":"2026-01-26T17:01:49.128338994+01:00","level":"INFO","msg":"OK   20250515105448_add_summary_message_id.sql (263.8µs)"}
-{"time":"2026-01-26T17:01:49.128678839+01:00","level":"INFO","msg":"OK   20250624000000_add_created_at_indexes.sql (325.2µs)"}
-{"time":"2026-01-26T17:01:49.128984204+01:00","level":"INFO","msg":"OK   20250627000000_add_provider_to_messages.sql (291.73µs)"}
-{"time":"2026-01-26T17:01:49.12929983+01:00","level":"INFO","msg":"OK   20250810000000_add_is_summary_message.sql (265.62µs)"}
-{"time":"2026-01-26T17:01:49.129580779+01:00","level":"INFO","msg":"OK   20250812000000_add_todos_to_sessions.sql (268.09µs)"}
-{"time":"2026-01-26T17:01:49.129585964+01:00","level":"INFO","msg":"goose: successfully migrated database to version: 20250812000000"}
-{"time":"2026-01-26T17:01:49.129633405+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-26T17:01:49.129745943+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":110},"msg":"Initializing MCP clients"}
-{"time":"2026-01-26T17:01:49.73470854+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).createAndStartLSPClient","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":76},"msg":"LSP client initialized","name":"python"}
-{"time":"2026-01-26T17:02:52.962674187+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-26T17:02:57.3247847+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-26T17:11:33.432259554+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":507},"msg":"Shutdown took 6.286852ms"}
-{"time":"2026-01-26T17:11:33.982816329+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-26T17:11:34.178260248+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-26T17:11:34.178494988+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/config.(*Config).configureProviders","file":"github.com/charmbracelet/crush/internal/config/load.go","line":259},"msg":"Skipping provider due to missing API key","provider":"anthropic"}
-{"time":"2026-01-26T17:11:34.18216688+01:00","level":"INFO","msg":"goose: no migrations to run. current version: 20250812000000"}
-{"time":"2026-01-26T17:11:34.182194111+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-26T17:11:34.182335616+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":110},"msg":"Initializing MCP clients"}
-{"time":"2026-01-26T17:11:34.786142525+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).createAndStartLSPClient","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":76},"msg":"LSP client initialized","name":"python"}
-{"time":"2026-01-26T17:11:43.042930337+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-26T17:11:44.911909276+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-26T18:10:19.727802782+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-26T18:10:19.926137244+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-26T18:10:19.926245207+01:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/config.(*Config).configureProviders","file":"github.com/charmbracelet/crush/internal/config/load.go","line":259},"msg":"Skipping provider due to missing API key","provider":"anthropic"}
-{"time":"2026-01-26T18:10:19.927808467+01:00","level":"INFO","msg":"goose: no migrations to run. current version: 20250812000000"}
-{"time":"2026-01-26T18:10:19.927858435+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-26T18:10:19.928006013+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.New.func1","file":"github.com/charmbracelet/crush/internal/app/app.go","line":110},"msg":"Initializing MCP clients"}
-{"time":"2026-01-26T18:10:20.546676356+01:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).createAndStartLSPClient","file":"github.com/charmbracelet/crush/internal/app/lsp.go","line":76},"msg":"LSP client initialized","name":"python"}
-{"time":"2026-01-26T18:11:07.640056766+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-26T18:11:11.201161834+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."}