TypeDAL 4.2.0__tar.gz → 4.2.2__tar.gz

{typedal-4.2.0 → typedal-4.2.2}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!--next-version-placeholder-->
 
+## v4.2.2 (2025-12-10)
+
+### Fix
+
+* Improved type hints for relationships (when join='inner') ([`e54cf91`](https://github.com/trialandsuccess/TypeDAL/commit/e54cf918461757b2fd146f1f3c7d9957c723f68c))
+
+## v4.2.1 (2025-12-10)
+
+### Fix
+
+* Improved type hints for relationships (non-list) ([`3fb53bc`](https://github.com/trialandsuccess/TypeDAL/commit/3fb53bc7a9b4c53c1bc533124ed205c5ec46fa92))
+
 ## v4.2.0 (2025-11-28)
 
 ### Feature

{typedal-4.2.0 → typedal-4.2.2}/PKG-INFO

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

{typedal-4.2.0 → typedal-4.2.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.2.0"
+__version__ = "4.2.2"

{typedal-4.2.0 → typedal-4.2.2}/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.2.0 → typedal-4.2.2}/src/typedal/query_builder.py

@@ -36,6 +36,7 @@ from .types import (
     SelectKwargs,
     T,
     T_MetaInstance,
+    Table,
 )
 
 
@@ -76,13 +77,13 @@ class QueryBuilder(t.Generic[T_MetaInstance]):
         self.relationships = relationships or {}
         self.metadata = metadata or {}
 
-    def _ensure_table_defined(self):
+    def _ensure_table_defined(self) -> Table:
         model = self.model
         if hasattr(model, "_ensure_table_defined"):
             return model._ensure_table_defined()
         else:
             # already a pydal table
-            return model
+            return t.cast(Table, model)
 
     def __str__(self) -> str:
         """

{typedal-4.2.0 → typedal-4.2.2}/src/typedal/relationships.py

@@ -257,14 +257,76 @@ class Relationship(t.Generic[To_Type]):
             return fallback_value
 
 
+@t.overload
 def relationship(
-    _type: t.Type[To_Type] | str,
+    _type: type[list[To_Type]],
     condition: Condition = None,
     join: JOIN_OPTIONS = None,
     on: OnQuery = None,
     lazy: LazyPolicy | None = None,
     explicit: bool = False,
+) -> list[To_Type]:
+    """
+    Define a relationship that returns a list of related instances.
+
+    Args:
+        _type: A list type hint like list[Office] to indicate multiple related records.
+
+    Returns:
+        A list of related instances.
+    """
+
+
+@t.overload
+def relationship(
+    _type: t.Type[To_Type] | str,
+    condition: Condition = None,
+    *,
+    join: t.Literal["inner"],
+    on: OnQuery = None,
+    lazy: LazyPolicy | None = None,
+    explicit: bool = False,
 ) -> To_Type:
+    """
+    Define a relationship that returns a single related instance (never None with inner join).
+
+    Args:
+        _type: A type or string reference like City to indicate a single related record.
+        join: Set to 'inner' to guarantee a non-null result.
+
+    Returns:
+        A single related instance (guaranteed non-null with inner join).
+    """
+
+
+@t.overload
+def relationship(
+    _type: t.Type[To_Type] | str,
+    condition: Condition = None,
+    join: JOIN_OPTIONS = None,
+    on: OnQuery = None,
+    lazy: LazyPolicy | None = None,
+    explicit: bool = False,
+) -> To_Type | None:
+    """
+    Define a relationship that returns a single optional related instance.
+
+    Args:
+        _type: A type or string reference like City to indicate a single related record.
+
+    Returns:
+        A single related instance or None.
+    """
+
+
+def relationship(
+    _type: type[list[To_Type]] | t.Type[To_Type] | str,
+    condition: Condition = None,
+    join: JOIN_OPTIONS = None,
+    on: OnQuery = None,
+    lazy: LazyPolicy | None = None,
+    explicit: bool = False,
+) -> list[To_Type] | To_Type | None:
     """
     Define a relationship to another table, when its id is not stored in the current table.
 
@@ -273,6 +335,7 @@ def relationship(
         condition: Lambda function defining the join condition between tables.
                    Example: lambda self, post: self.id == post.author
         join: Join strategy ('left', 'inner', etc.). Defaults to 'left' when using 'on'.
+              When 'inner' is used with a single type, the result is guaranteed non-null.
         on: Alternative to condition for complex queries with pivot tables.
             Allows specifying multiple join conditions to avoid cross joins.
         lazy: Controls behavior when accessing relationship data without explicitly joining: