TypeDAL 5.0.6__tar.gz → 5.1.1__tar.gz

{typedal-5.0.6 → typedal-5.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: TypeDAL
-Version: 5.0.6
+Version: 5.1.1
 Summary: Typing support for PyDAL
 Keywords: 
 Author: Robin van der Noord

{typedal-5.0.6 → typedal-5.1.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 name = "TypeDAL"
 description = "Typing support for PyDAL"
 readme = "README.md"
-version = "5.0.6"
+version = "5.1.1"
 requires-python = ">=3.12"
 license-expression = "MIT"
 keywords = []
@@ -164,7 +164,7 @@ badge = true
 mypy = "--disable-error-code misc"
 
 [tool.black]
-target-version = ["py314"]
+target-version = ["py312"]
 line-length = 120
 extend-exclude = '''
 # A regex preceded with ^/ will apply only to files and directories
@@ -199,7 +199,7 @@ exclude = [
 ]
 
 [tool.ruff]
-target-version = "py314"
+target-version = "py312"
 line-length = 120
 extend-exclude = [
     "*.bak/",

{typedal-5.0.6 → typedal-5.1.1}/pyproject.toml.orig

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 name = "TypeDAL"
 description = 'Typing support for PyDAL'
 readme = "README.md"
-version = "5.0.6"
+version = "5.1.1"
 requires-python = ">=3.12"
 license-expression = "MIT"
 keywords = []
@@ -181,7 +181,7 @@ badge = true
 mypy = "--disable-error-code misc"
 
 [tool.black]
-target-version = ["py314"]
+target-version = ["py312"]
 line-length = 120
 # 'extend-exclude' excludes files or directories in addition to the defaults
 extend-exclude = '''
@@ -229,7 +229,7 @@ strict = true
 exclude = ["venv", ".bak"]
 
 [tool.ruff]
-target-version = "py314"
+target-version = "py312"
 line-length = 120
 
 extend-exclude = ["*.bak/", "venv*/", "tests/", "example_*.py"]

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/asynchronous.py

@@ -434,6 +434,7 @@ class BlockingAccessHandler(ExecutionHandler):
             f"the extra query. command: {command}",
             category=BlockingDatabaseAccessWarning,
             skip_file_prefixes=_SKIP_FRAMES,
+            stacklevel=2,
         )
 
 

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/cli.py

@@ -30,6 +30,7 @@ except ImportError as e:
         "to fix this.",
         source=e,
         category=RuntimeWarning,
+        stacklevel=2,
     )
     exit(127)  # command not found
 
@@ -226,7 +227,7 @@ def setup(
     data.pop("connection", None)
 
     # ignore any None:
-    old_contents["tool"]["typedal"] = {k: v for k, v in data.items() if v is not None}
+    old_contents["tool"]["typedal"] = {k: v for k, v in data.items() if v is not None}  # type: ignore
 
     with toml_path.open("w") as f:
         tomlkit.dump(old_contents, f)

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/config.py

@@ -159,7 +159,7 @@ def _load_toml(path: str | bool | Path | None = True) -> tuple[str, AnyDict]:
 
         return str(toml_path) or "", t.cast(AnyDict, data["tool"]["typedal"])
     except Exception as e:
-        warnings.warn(f"Could not load typedal config toml: {e}", source=e)
+        warnings.warn(f"Could not load typedal config toml: {e}", source=e, stacklevel=2)
         return str(toml_path) or "", {}
 
 

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/core.py

@@ -53,8 +53,8 @@ def _expression_subclasses() -> t.Iterator[type]:
     """
     Yield Expression and every (nested) subclass currently loaded, e.g. Field and TypedField.
     """
-    seen = {Expression}
-    stack = [Expression]
+    seen: set[type[Expression]] = {Expression}
+    stack: list[type[Expression]] = [Expression]
     while stack:
         for subclass in stack.pop().__subclasses__():
             if subclass not in seen:
@@ -476,7 +476,12 @@ class TypeDAL(_TypeDALBase):
                 delattr(self, tablename)
 
             if verbose:
-                warnings.warn(f"{model} could not be migrated, try faking", source=e, category=RuntimeWarning)
+                warnings.warn(
+                    f"{model} could not be migrated, try faking",
+                    source=e,
+                    category=RuntimeWarning,
+                    stacklevel=2,
+                )
 
             # try again:
             return self.define(model, migrate=self._migrate, fake_migrate=self._migrate, redefine=True)

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/define.py

@@ -123,7 +123,10 @@ class TableDefinitionBuilder:
             self.class_map[table._rname] = cls  # table_model - sql name
             cls.__on_define__(self.db)
         else:
-            warnings.warn("db.define used without inheriting TypedTable. This could lead to strange problems!")
+            warnings.warn(
+                "db.define used without inheriting TypedTable. This could lead to strange problems!",
+                stacklevel=2,
+            )
 
         if not tablename.startswith("typedal_") and cache_dependency:
             from .caching import _remove_cache, remove_cache_for_table

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/mixins.py

@@ -180,6 +180,7 @@ class SlugMixin(Mixin):
             warnings.warn(
                 "The 'slug_suffix' option is deprecated, use 'slug_suffix_length' instead.",
                 DeprecationWarning,
+                stacklevel=2,
             )
 
         slug_suffix = slug_suffix_length or kw.get("slug_suffix", 0)

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/query_builder.py

@@ -8,6 +8,7 @@ import datetime as dt
 import math
 import time
 import typing as t
+import warnings
 from collections import defaultdict
 
 from pydal.helpers.classes import SQLALL
@@ -45,6 +46,19 @@ from .types import (
     merge_permissions,
     require_permission,
 )
+from .warnings import NoopQueryWarning, UnusedWindowWarning
+
+
+def warn_noop(method: str) -> None:
+    """
+    Warn that `method` was called without arguments, which has no effect.
+    """
+    # stacklevel: 1 = here, 2 = the query builder method, 3 = the caller.
+    warnings.warn(
+        f"`.{method}()` without arguments does nothing. You can remove this call.",
+        stacklevel=3,
+        category=NoopQueryWarning,
+    )
 
 
 class QueryBuilder[T_MetaInstance: _TypedTable](Select):
@@ -173,6 +187,10 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
         """
         Return a clone of this builder with permission overrides merged in.
         """
+        if not permissions and self:
+            warn_noop("permissions")
+            return self
+
         return self._extend(permissions=permissions)
 
     def _normalize_select_option(
@@ -214,8 +232,15 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
             join: othertable.on(query) - do an INNER JOIN. Using TypeDAL relationships with .join() is recommended!
             left: othertable.on(query) - do a LEFT JOIN. Using TypeDAL relationships with .join() is recommended!
             cache: cache the query result to speed up repeated queries; e.g. (cache=(cache.ram, 3600), cacheable=True)
+
+        Calling this without any fields or options on a builder that already has settings
+        does nothing and emits a NoopQueryWarning.
         """
 
+        if not fields and not options and self:
+            warn_noop("select")
+            return self
+
         for key in ("distinct",):
             if options.get(key):
                 options[key] = self._normalize_select_option(options[key])
@@ -280,7 +305,15 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
             .where(lambda table: table.id == 5).where(lambda table: table.id == 6) == (table.id == 5) & (table.id=6)
         When passing multiple queries to a single .where, they will be ORed:
             .where(lambda table: table.id == 5, lambda table: table.id == 6) == (table.id == 5) | (table.id=6)
+
+        Calling this without any arguments on a builder that already has settings
+        does nothing and emits a NoopQueryWarning.
+        Starting an empty builder (e.g. `Model.where()`) is allowed and stays silent.
         """
+        if not queries_or_lambdas and not filters and self:
+            warn_noop("where")
+            return self
+
         new_query = self.query
         table = self._ensure_table_defined()
 
@@ -296,7 +329,7 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
             elif isinstance(query_part, (Query, Expression)):
                 subquery |= t.cast(Query, query_part)
             elif callable(query_part):
-                if result := query_part(self.model):  # ty: ignore[call-top-callable]
+                if result := query_part(self.model):
                     subquery |= result
             elif isinstance(query_part, dict):
                 subsubquery = DummyQuery()
@@ -662,6 +695,17 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
 
         query, select_args, select_kwargs = self._before_query(metadata, add_id=add_id)
 
+        window_size = metadata.get("window_size", None)
+        is_iterating = metadata.get("iterating", False)
+
+        if window_size is not None and is_iterating is not True:
+            warnings.warn(
+                "A window size was configured, but collect() was called directly. "
+                "Use iteration over the query builder to fetch rows in windows.",
+                stacklevel=2,
+                category=UnusedWindowWarning,
+            )
+
         metadata["sql"] = db(query)._select(*select_args, **select_kwargs)
 
         if verbose:  # pragma: no cover
@@ -1222,13 +1266,40 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
         """
         You can start iterating a Query Builder object before calling collect, for ease of use.
         """
-        yield from self.collect()
+        builder = self._extend(metadata={"iterating": True})
+        window_size = self.metadata.get("window_size", None)
+
+        if not window_size:
+            yield from builder.collect()
+            return
+
+        for chunk in builder.chunk(window_size):
+            yield from chunk
+
+    def __await__(self):
+        return self.collect_async().__await__()
+
+    async def __aiter__(self):
+        builder = self._extend(metadata={"iterating": True})
+
+        window_size = self.metadata.get("window_size", None)
+
+        if window_size:
+            async for chunk in builder.chunk_async(window_size):
+                for row in chunk:
+                    yield row
+        else:
+            rows = await builder.collect_async()
+            for row in rows:
+                yield row
+
+    def window(self, window_size: int) -> QueryBuilder[T_MetaInstance]:
+        return self._extend(metadata={"window_size": window_size})
 
     def __count(
         self,
         db: TypeDAL,
         distinct: t.Optional[bool] = None,
-        *,
         include_left_for_distinct: bool = True,
     ) -> Query:
         # internal, shared logic between .count and ._count
@@ -1351,7 +1422,10 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
                     pass
             ```
         """
-        require_permission(self._permissions, "read")
+        # require_permission checked in .collect()
+        if "limitby" in self.select_kwargs:
+            raise ValueError("chunk() cannot be combined with an existing limitby")
+
         page = 1
 
         while rows := self.__paginate(chunk_size, page).collect():
@@ -1506,7 +1580,10 @@ class QueryBuilder[T_MetaInstance: _TypedTable](Select):
         writer can be visible halfway through the iteration; wrap it in `db.session()` if you
         need every page to come from the same snapshot.
         """
-        require_permission(self._permissions, "read")
+        # require_permission checked in .collect()
+        if "limitby" in self.select_kwargs:
+            raise ValueError("chunk_async() cannot be combined with an existing limitby")
+
         db = self._get_db()
         page = 1
 

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/relationships.py

@@ -110,7 +110,7 @@ class Relationship[To_Type]:
 
     @staticmethod
     def _error_duplicate_condition(condition: Condition, on: OnQuery) -> t.Never:
-        warnings.warn(f"Relation | Both specified! {condition=} {on=}")
+        warnings.warn(f"Relation | Both specified! {condition=} {on=}", stacklevel=2)
         raise ValueError("Please specify either a condition or an 'on' statement for this relationship!")
 
     def __repr__(self) -> str:
@@ -278,6 +278,7 @@ class Relationship[To_Type]:
                 f"Trying to access relationship '{self.name}' without joining. "
                 f"Did you forget to use .join('{self.name}')? Returning empty value.",
                 category=RuntimeWarning,
+                stacklevel=2,
             )
             return fallback_value
 
@@ -296,6 +297,7 @@ class Relationship[To_Type]:
                     "This performs an extra database query. "
                     f"Consider using .join('{self.name}') for better performance.",
                     category=RuntimeWarning,
+                    stacklevel=2,
                 )
 
             return builder.first()[self.name]  # type: ignore
@@ -304,6 +306,7 @@ class Relationship[To_Type]:
                 f"Failed to lazy load relationship '{self.name}': {e}",
                 category=RuntimeWarning,
                 source=e,
+                stacklevel=2,
             )
 
             return fallback_value
@@ -501,12 +504,12 @@ def to_relationship(
     try:
         condition = _generate_relationship_condition(cls, key, field)
     except Exception as e:  # pragma: no cover
-        warnings.warn("Could not generate Relationship condition", source=e)
+        warnings.warn("Could not generate Relationship condition", source=e, stacklevel=2)
         condition = None
 
     if not condition:  # pragma: no cover
         # something went wrong, not a valid relationship
-        warnings.warn(f"Invalid relationship for {cls.__name__}.{key}: {field}")
+        warnings.warn(f"Invalid relationship for {cls.__name__}.{key}: {field}", stacklevel=2)
         return None
 
     join = "left" if optional or t.get_origin(field) is list else "inner"

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/serializers/typescript.py

@@ -31,7 +31,7 @@ class TypedDictRegistry(Singleton):
     def __init__(self) -> None:
         """Initialize the singleton registry and optional shared typtyp world."""
         self._types: dict[type, type[dict[str, t.Any]]] = {}
-        self._world = typtyp.World() if typtyp else None
+        self._world = typtyp.World() if typtyp else None  # type: ignore
         self._names: set[str] = set()
 
     @property
@@ -78,6 +78,7 @@ class TypedDictRegistry(Singleton):
         if world is None:  # pragma: ignore
             warnings.warn(
                 f"`{caller_name}` can not be used without the typescript extra. Please install `typedal[typescript]`",
+                stacklevel=2,
             )
             return ""
 

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/tables.py

@@ -138,6 +138,23 @@ class TableMeta(type):
         self._relationships = None
         self._permissions = None
 
+    def __getattribute__(self, col: str) -> t.Any:
+        """
+        Resolve bound table fields before metaclass convenience methods.
+
+        Annotation-only fields are not stored in the model class dictionary, so
+        normal class lookup would otherwise return a same-named method defined
+        on this metaclass. For example, a model may have a 'window' column
+        while this metaclass also provides 'window()'. The column takes
+        precedence on the model class; use 'QueryBuilder(Model).window()' to
+        call the query helper in that case.
+        """
+        table = type.__getattribute__(self, "_table")
+        if table is not None and col in table._fields:
+            return table[col]
+
+        return type.__getattribute__(self, col)
+
     def __getattr__(self, col: str) -> t.Optional[Field]:
         """
         Magic method used by TypedTableMeta to get a database field with dot notation on a class.
@@ -465,6 +482,12 @@ class TableMeta(type):
         """
         return QueryBuilder(self).join(*fields, on=on, condition=condition, method=method, condition_and=condition_and)
 
+    def window(self: t.Type[T_MetaInstance], window_size: int) -> "QueryBuilder[T_MetaInstance]":
+        """
+        See QueryBuilder.window!
+        """
+        return QueryBuilder(self).window(window_size)
+
     def collect(self: t.Type[T_MetaInstance], verbose: bool = False) -> "TypedRows[T_MetaInstance]":
         """
         See QueryBuilder.collect!

{typedal-5.0.6 → typedal-5.1.1}/src/typedal/types.py

@@ -313,6 +313,8 @@ class Metadata(t.TypedDict):
     select_duration: t.NotRequired[float]
     relationships: t.NotRequired[set[str]]
     sql: t.NotRequired[str]
+    window_size: t.NotRequired[int]
+    iterating: t.NotRequired[bool]
 
 
 class FieldSettings(t.TypedDict, total=False):

typedal-5.1.1/src/typedal/warnings.py

@@ -0,0 +1,9 @@
+"""Warning types emitted by TypeDAL."""
+
+
+class UnusedWindowWarning(RuntimeWarning):
+    """Warn when a window size is configured but the query is collected directly."""
+
+
+class NoopQueryWarning(RuntimeWarning):
+    """Warn when a query builder method is called without arguments, so it does nothing."""