TypeDAL 4.2.1__tar.gz → 4.3.0__tar.gz

{typedal-4.2.1 → typedal-4.3.0}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 <!--next-version-placeholder-->
 
+## v4.3.0 (2026-01-06)
+
+### Feature
+
+* Re-use database caching logic for function memo ([`4c9ad68`](https://github.com/trialandsuccess/TypeDAL/commit/4c9ad686e5d2041db91981c856d5a748f0d50752))
+
+## 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

{typedal-4.2.1 → typedal-4.3.0}/PKG-INFO

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

{typedal-4.2.1 → typedal-4.3.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.2.1"
+__version__ = "4.3.0"

{typedal-4.2.1 → typedal-4.3.0}/src/typedal/caching.py

@@ -14,7 +14,7 @@ from pydal.objects import Field, Rows, Set
 from .fields import TypedField
 from .rows import TypedRows
 from .tables import TypedTable
-from .types import Query
+from .types import CacheStatus, Query
 
 if t.TYPE_CHECKING:
     from .core import TypeDAL
@@ -159,6 +159,17 @@ def remove_cache(idx: int | t.Iterable[int], table: str) -> None:
     _TypedalCache.where(_TypedalCache.id.belongs(related)).delete()
 
 
+def remove_cache_for_table(table: str) -> None:
+    """
+    Remove all cache entries that depend on a table.
+
+    Used for inserts where we don't know which cached queries
+    the new row would match.
+    """
+    related = _TypedalCacheDependency.where(table=table).select("entry").to_sql()
+    _TypedalCache.where(_TypedalCache.id.belongs(related)).delete()
+
+
 def clear_cache() -> None:
     """
     Remove everything from the cache.
@@ -210,6 +221,27 @@ def get_expire(
     return None
 
 
+def _insert_cache_entry(
+    db: "TypeDAL",
+    key: str,
+    data: t.Any,
+    expires_at: dt.datetime | None,
+    deps: DependencyTupleSet,
+) -> None:
+    """
+    Shared internal function to insert cache entry and dependencies.
+    """
+    entry = _TypedalCache.insert(
+        key=key,
+        data=dill.dumps(data),
+        expires_at=expires_at,
+    )
+
+    _TypedalCacheDependency.bulk_insert([{"entry": entry, "table": table, "idx": idx} for table, idx in deps])
+
+    db.commit()
+
+
 def save_to_cache(
     instance: TypedRows[T_TypedTable],
     rows: Rows,
@@ -224,39 +256,85 @@ def save_to_cache(
     db = rows.db
     if (c := instance.metadata.get("cache", {})) and c.get("enabled") and (key := c.get("key")):
         expires_at = get_expire(expires_at=expires_at, ttl=ttl) or c.get("expires_at")
-
         deps = _determine_dependencies(instance, rows, c["depends_on"])
 
-        entry = _TypedalCache.insert(
-            key=key,
-            data=dill.dumps(instance),
-            expires_at=expires_at,
-        )
-
-        _TypedalCacheDependency.bulk_insert([{"entry": entry, "table": table, "idx": idx} for table, idx in deps])
+        _insert_cache_entry(db, key, instance, expires_at, deps)
 
-        db.commit()
         instance.metadata["cache"]["status"] = "fresh"
     return instance
 
 
-def _load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
-    if not (row := _TypedalCache.where(key=key).first()):
+class CacheMiss:
+    """Sentinel class to represent a cache miss, distinguishing it from a None value."""
+
+    def __bool__(self) -> bool:  # pragma: no cover
+        """
+        Ensures the sentinel evaluates to False in boolean contexts.
+
+        Example:
+            res = _load_memoize_from_cache("key")
+            if not res:  # Triggers if a CacheMiss occurs
+                ...
+        """
+        return False
+
+
+_CACHE_SENTINEL: t.Final[CacheMiss] = CacheMiss()
+
+
+def _fetch_cached_payload(key: str) -> tuple[t.Any, t.Any] | None:
+    """
+    Retrieves and validates a cache entry from the database.
+
+    If the entry exists but is expired, it is deleted from the database
+    to maintain storage hygiene.
+
+    Args:
+        key: The unique string identifier for the cache entry.
+
+    Returns:
+        A tuple of (deserialized_data, db_row) if valid; None if missing or expired.
+    """
+    row = _TypedalCache.where(key=key).first()
+    if not row:
         return None
 
     now = get_now()
-
+    # Ensure comparison is offset-aware if the row has a timestamp
     expires = row.expires_at.replace(tzinfo=dt.timezone.utc) if row.expires_at else None
 
     if expires and now >= expires:
         row.delete_record()
         return None
 
-    inst = dill.loads(row.data)  # nosec
+    # Only one place for deserialization to happen
+    return dill.loads(row.data), row  # nosec
+
+
+def _load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
+    """
+    Loads a specific TypeDAL model instance from the cache and re-hydrates it.
+
+    This binds the cached object back to the active database connection and
+    restores its instance methods/metadata.
+
+    Args:
+        key: Cache key.
+        db: The active TypeDAL database instance.
+
+    Returns:
+        The re-hydrated model instance, or None if the load fails.
+    """
+    result = _fetch_cached_payload(key)
+    if not result:
+        return None
+
+    inst, row = result
 
-    inst.metadata["cache"]["status"] = "cached"
-    inst.metadata["cache"]["cached_at"] = row.cached_at
-    inst.metadata["cache"]["expires_at"] = row.expires_at
+    # Re-hydrate the model instance with metadata and DB context
+    inst.metadata.setdefault("cache", {}).update(
+        {"status": "cached", "cached_at": row.cached_at, "expires_at": row.expires_at},
+    )
 
     inst.db = db
     inst.model = db._class_map[inst.model]
@@ -264,16 +342,43 @@ def _load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
     return inst
 
 
-def load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
+def _load_memoize_from_cache(key: str) -> t.Any:
     """
-    If 'key' matches a non-expired row in the database, try to load the dill.
+    Low-level retrieval for memoized results.
+
+    Used when the caller doesn't need TypeDAL model re-hydration, just the raw data.
 
-    If anything fails, return None.
+    Args:
+        key: Cache key.
+
+    Returns:
+        The deserialized data or the _CACHE_SENTINEL object if not found.
     """
     with contextlib.suppress(Exception):
-        return _load_from_cache(key, db)
+        if result := _fetch_cached_payload(key):
+            return result[0]
 
-    return None  # pragma: no cover
+    return _CACHE_SENTINEL
+
+
+def load_from_cache(key: str, db: "TypeDAL") -> t.Any | None:
+    """
+    Public entry point to load model instances from cache.
+
+    Wraps the internal loader in a broad exception handler to ensure that
+    cache failures never crash the main application flow.
+
+    Args:
+        key: Cache key.
+        db: The active TypeDAL database instance.
+
+    Returns:
+        The model instance or None on any failure/miss.
+    """
+    try:
+        return _load_from_cache(key, db)
+    except Exception:  # pragma: no cover
+        return None
 
 
 def humanize_bytes(size: int | float) -> str:
@@ -319,7 +424,9 @@ RowStats = t.TypedDict(
 def _row_stats(db: "TypeDAL", table: str, query: Query) -> RowStats:
     count_field = _TypedalCacheDependency.entry.count()
     stats: TypedRows[_TypedalCacheDependency] = db(query & (_TypedalCacheDependency.table == table)).select(
-        _TypedalCacheDependency.entry, count_field, groupby=_TypedalCacheDependency.entry
+        _TypedalCacheDependency.entry,
+        count_field,
+        groupby=_TypedalCacheDependency.entry,
     )
     return {
         "Dependent Cache Entries": len(stats),
@@ -353,7 +460,9 @@ TableStats = t.TypedDict(
 def _table_stats(db: "TypeDAL", table: str, query: Query) -> TableStats:
     count_field = _TypedalCacheDependency.entry.count()
     stats: TypedRows[_TypedalCacheDependency] = db(query & (_TypedalCacheDependency.table == table)).select(
-        _TypedalCacheDependency.entry, count_field, groupby=_TypedalCacheDependency.entry
+        _TypedalCacheDependency.entry,
+        count_field,
+        groupby=_TypedalCacheDependency.entry,
     )
     return {
         "Dependent Cache Entries": len(stats),
@@ -408,3 +517,66 @@ def calculate_stats(db: "TypeDAL") -> Stats[GenericStats]:
         "valid": _calculate_stats(db, _TypedalCache.id.belongs(valid_items)),
         "expired": _calculate_stats(db, _TypedalCache.id.belongs(expired_items)),
     }
+
+
+def memoize(
+    db: "TypeDAL",
+    func: t.Callable[..., T],
+    *args: TypedRows[t.Any] | TypedTable,
+    key: str | None = None,
+    ttl: int | dt.timedelta | dt.datetime | None = None,
+    **kwargs: t.Any,
+) -> tuple[T, CacheStatus]:
+    """
+    Cache the result of a function applied to TypedRow(s).
+
+    Tracks dependencies on the table(s) so the cache invalidates
+    when those rows are updated/deleted.
+
+    Args:
+        db: TypeDAL database
+        func: Function to cache
+        *args: TypedRow/TypedRows instances only
+        key: Cache key (required for lambdas)
+        ttl: Time to live in seconds/timedelta, or datetime to expire at
+        **kwargs: Extra parameters passed to func
+
+    Returns:
+        tuple of (result, cache_status)
+    """
+    if not key:
+        if func.__name__ == "<lambda>":
+            raise ValueError(
+                "Lambda functions require explicit 'key' parameter. Use: db.memoize(your_func, data, key='my_key')",
+            )
+        key = func.__qualname__
+
+    # Extract dependencies from args
+    deps: DependencyTupleSet = set()
+    for arg in args:
+        if isinstance(arg, TypedRows):
+            for row in arg:
+                deps.add((str(row._table), row.id))
+        elif isinstance(arg, TypedTable):
+            deps.add((str(arg._table), arg.id))
+
+    # Generate cache key
+    _, hashed_key = create_and_hash_cache_key(key, *[getattr(arg, "id", None) for arg in args], kwargs)
+
+    # Try to load from cache
+    cached = _load_memoize_from_cache(hashed_key)
+    if cached is not _CACHE_SENTINEL:
+        return cached, "cached"
+
+    # Cache miss - compute result
+    result = func(*args, **kwargs)
+
+    # Save to cache
+    if isinstance(ttl, dt.datetime):
+        expires_at: dt.datetime | None = ttl
+    else:
+        expires_at = get_expire(ttl=ttl)
+
+    _insert_cache_entry(db, hashed_key, result, expires_at, deps)
+
+    return result, "fresh"

{typedal-4.2.1 → typedal-4.3.0}/src/typedal/core.py

@@ -4,6 +4,7 @@ Core functionality of TypeDAL.
 
 from __future__ import annotations
 
+import datetime as dt
 import sys
 import typing as t
 import warnings
@@ -20,7 +21,7 @@ from .helpers import (
     sql_expression,
     to_snake,
 )
-from .types import Field, T, Template  # type: ignore
+from .types import CacheStatus, Field, T, Template  # type: ignore
 
 try:
     # python 3.14+
@@ -446,6 +447,32 @@ class TypeDAL(pydal.DAL):
         """
         return sql_expression(self, sql_fragment, *raw_args, output_type=output_type, **raw_kwargs)
 
+    def memoize(
+        self,
+        func: t.Callable[..., T],
+        *args: TypedRows[t.Type[TypedTable]] | TypedTable,  # type: ignore
+        key: str | None = None,
+        ttl: int | dt.timedelta | dt.datetime | None = None,
+        **kwargs: t.Any,  # P.kwargs would be nice but they don't work without .args
+    ) -> tuple[T, CacheStatus]:
+        """
+        Cache the result of a function applied to TypedRow(s).
+
+        Tracks dependencies on the table(s) so the cache invalidates
+        when those rows are updated/deleted.
+
+        Args:
+            func: Function to cache
+            *args: Can contain TypedRow, TypedRows, or other args
+            key: Cache key (required for lambdas)
+            ttl: Time to live in seconds/timedelta, or datetime to expire at
+            **kwargs: Passed to func
+
+        Returns:
+            Cached result or fresh computation
+        """
+        return memoize(self, func, *args, key=key, ttl=ttl, **kwargs)
+
 
 TypeDAL.representers.setdefault("rows_render", default_representer)
 
@@ -453,10 +480,11 @@ TypeDAL.representers.setdefault("rows_render", default_representer)
 
 from .fields import *  # noqa: E402 F403 # isort: skip ; to fill globals() scope
 from .define import TableDefinitionBuilder  # noqa: E402
-from .rows import TypedSet  # noqa: E402
+from .rows import TypedRows, TypedSet  # noqa: E402
 from .tables import TypedTable  # noqa: E402
 
 from .caching import (  # isort: skip # noqa: E402
+    memoize,
     _TypedalCache,
     _TypedalCacheDependency,
 )

{typedal-4.2.1 → typedal-4.3.0}/src/typedal/define.py

@@ -109,8 +109,9 @@ class TableDefinitionBuilder:
             warnings.warn("db.define used without inheriting TypedTable. This could lead to strange problems!")
 
         if not tablename.startswith("typedal_") and cache_dependency:
-            from .caching import _remove_cache
+            from .caching import _remove_cache, remove_cache_for_table
 
+            table._after_insert.append(lambda _row, _id: remove_cache_for_table(tablename))
             table._before_update.append(lambda s, _: _remove_cache(s, tablename))
             table._before_delete.append(lambda s: _remove_cache(s, tablename))
 

{typedal-4.2.1 → typedal-4.3.0}/src/typedal/relationships.py

@@ -277,6 +277,28 @@ def relationship(
     """
 
 
+@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,
@@ -313,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:

{typedal-4.2.1 → typedal-4.3.0}/src/typedal/types.py

@@ -190,13 +190,16 @@ class PaginateDict(t.TypedDict):
     pagination: Pagination
 
 
+CacheStatus = t.Literal["fresh", "cached"]
+
+
 class CacheMetadata(t.TypedDict):
     """Used by query builder metadata in the 'cache' key."""
 
     enabled: bool
     depends_on: list[t.Any]
     key: t.NotRequired[str | None]
-    status: t.NotRequired[str | None]
+    status: t.NotRequired[CacheStatus | None]
     expires_at: t.NotRequired[dt.datetime | None]
     cached_at: t.NotRequired[dt.datetime | None]
 

{typedal-4.2.1 → typedal-4.3.0}/tests/test_relationships.py

@@ -3,6 +3,7 @@ import time
 import types
 import typing
 import warnings
+from datetime import datetime
 from uuid import uuid4
 
 import pytest
@@ -16,6 +17,7 @@ from src.typedal.caching import (
     remove_cache,
 )
 from src.typedal.serializers import as_json
+from typedal import TypedRows
 
 db = TypeDAL("sqlite:memory")
 
@@ -596,6 +598,33 @@ def test_caching():
     assert not User.count()
 
 
+def test_caching_insert_invalidation():
+    _setup_data()
+
+    # Get the writer user
+    writer = User.where(name="Writer 1").collect_or_fail().first()
+
+    # Cache articles filtered by author
+    articles = Article.where(author=writer).cache().collect_or_fail()
+    assert len(articles) == 1
+    assert articles.metadata["cache"]["status"] == "fresh"
+
+    # Get from cache
+    articles_cached = Article.where(author=writer).cache().collect_or_fail()
+    assert articles_cached.metadata["cache"]["status"] == "cached"
+
+    # Insert new article matching the filter
+    Article.insert(title="New Article by Writer", author=writer)
+
+    # Query again with same filter
+    # Cache should be invalidated because a new row matching the filter was inserted
+    articles_after = Article.where(author=writer).cache().collect_or_fail()
+
+    # This is the failing case: status will likely still be "cached" when it should be "fresh"
+    assert len(articles_after) == 2
+    assert articles_after.metadata["cache"]["status"] == "fresh"
+
+
 def test_caching_dependencies():
     first_one, first_two = CacheFirst.bulk_insert([{"name": "one"}, {"name": "two"}])
 
@@ -631,6 +660,45 @@ def test_caching_dependencies():
         assert row.second.name != "een 2.0"
 
 
+def test_memoize_caches_and_invalidates():
+    _setup_data()
+
+    def expensive_func(data: TypedRows[User], field: str) -> set:
+        return set(data.column(field))
+
+    users = User.all()
+
+    # First call - fresh
+    result1, status = db.memoize(expensive_func, users, field="name")
+    assert status == "fresh"
+    assert "Reader 1" in result1
+
+    users = User.all()
+
+    # Second call - should be cached
+    result2, status = db.memoize(expensive_func, users, field="name")
+    assert status == "cached"
+    assert result1 == result2
+
+    # Update a user
+    User.where(name="Reader 1").update(name="Reader Updated")
+
+    users = User.all()
+
+    # Third call - cache should be invalidated, result changed
+    result3, status = db.memoize(expensive_func, users, field="name")
+    assert status == "fresh"
+    assert "Reader Updated" in result3
+    assert "Reader 1" not in result3
+
+    # lambda:
+
+    with pytest.raises(ValueError):
+        db.memoize(lambda x: x, users.first(), ttl=datetime.now())
+
+    db.memoize(lambda x: x, users.first(), key="echo_lambda", ttl=datetime.now())
+
+
 def test_illegal():
     with pytest.raises(ValueError), pytest.warns(UserWarning):