sqlmodel-ext 0.3.4__tar.gz → 0.4.0__tar.gz

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.3.4
+Version: 0.4.0
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext
@@ -170,10 +170,12 @@ async def demo(session: AsyncSession):
 A complete REST API -- models, DTOs, and five endpoints:
 
 ```python
+from collections.abc import AsyncGenerator
 from typing import Annotated
 from uuid import UUID
 
 from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sqlmodel_ext import (
@@ -181,17 +183,37 @@ from sqlmodel_ext import (
     ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
 )
 
-# ── Dependencies (defined once, reused everywhere) ────────────────
+# ── Dependency-injection layer: declare once (e.g. in a shared
+#    deps module), every router imports the type aliases ────────────
+
+_engine = create_async_engine("postgresql+asyncpg://localhost/app")
+_Session = async_sessionmaker(_engine, expire_on_commit=True)
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with _Session() as session:
+        yield session
 
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
-TableViewDep = Annotated[TableViewRequest, Depends()]
+"""Request-scoped AsyncSession. The single way endpoints touch the DB."""
 
-# ── Models ────────────────────────────────────────────────────────
+# TableViewRequest is a Pydantic model → FastAPI binds its fields as
+# query params automatically. No hand-written offset/limit/order plumbing.
+TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+
+async def get_current_user(session: SessionDep) -> "User":
+    ...  # decode the bearer token, load the user — your auth, unchanged
+
+CurrentUserDep = Annotated["User", Depends(get_current_user)]
+
+# ── Models: the DTO ladder (Base → Create → Update → Response) ─────
 
 class ArticleBase(SQLModelBase):
     title: Str64
+    """Article title"""
     body: Text10K
+    """Article body (max 10k chars)"""
     is_published: bool = False
+    """Whether the article is publicly visible"""
 
 class Article(ArticleBase, UUIDTableBaseMixin, table=True):
     author_id: UUID = Field(foreign_key='user.id')
@@ -199,14 +221,24 @@ class Article(ArticleBase, UUIDTableBaseMixin, table=True):
 class ArticleCreate(ArticleBase):
     pass
 
-class ArticleUpdate(ArticleBase):
-    title: Str64 | None = None       # Override to optional,
-    body: Text10K | None = None      # preserving the original
-    is_published: bool | None = None  # type constraints from Base
+# all_fields_optional flips every inherited field to ``T | None = None``
+# while preserving its Annotated constraints AND attribute docstrings —
+# no hand-maintained per-field overrides.
+class ArticleUpdate(ArticleBase, all_fields_optional=True):
+    pass
 
 class ArticleResponse(ArticleBase, UUIDIdDatetimeInfoMixin):
     author_id: UUID
 
+# ── Resource-as-dependency: wrap "load by id or 404" once, then the
+#    fetched ORM instance is just another injected parameter ────────
+
+async def get_article(session: SessionDep, article_id: UUID) -> Article:
+    return await Article.get_exist_one(session, article_id)
+
+ArticleDep = Annotated[Article, Depends(get_article)]
+"""The Article for {article_id}, or 404 — fetched before the handler runs."""
+
 # ── Endpoints ─────────────────────────────────────────────────────
 
 router = APIRouter(prefix="/articles", tags=["articles"])
@@ -220,7 +252,7 @@ async def create_article(
 
 @router.get("", response_model=ListResponse[ArticleResponse])
 async def list_articles(
-        session: SessionDep, table_view: TableViewDep,
+        session: SessionDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Article]:
     return await Article.get_with_count(
         session,
@@ -228,24 +260,24 @@ async def list_articles(
         table_view=table_view,
     )
 
+# article: ArticleDep — the 404 + fetch is the dependency's job, so the
+# single-resource handlers carry no lookup boilerplate at all.
 @router.get("/{article_id}", response_model=ArticleResponse)
-async def get_article(session: SessionDep, article_id: UUID) -> Article:
-    return await Article.get_exist_one(session, article_id)
+async def get_article_detail(article: ArticleDep) -> Article:
+    return article
 
 @router.patch("/{article_id}", response_model=ArticleResponse)
 async def update_article(
-        session: SessionDep, article_id: UUID, data: ArticleUpdate,
+        session: SessionDep, article: ArticleDep, data: ArticleUpdate,
 ) -> Article:
-    article = await Article.get_exist_one(session, article_id)
     return await article.update(session, data)
 
 @router.delete("/{article_id}")
-async def delete_article(session: SessionDep, article_id: UUID) -> None:
-    article = await Article.get_exist_one(session, article_id)
+async def delete_article(session: SessionDep, article: ArticleDep) -> None:
     await Article.delete(session, article)
 ```
 
-No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
+No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewRequestDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
 
 **What the client gets from `GET /articles?offset=0&limit=10&desc=true`:**
 
@@ -440,7 +472,7 @@ class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMix
 
 @router.get("/notifications", response_model=ListResponse[NotificationBase])
 async def list_notifications(
-        session: SessionDep, user: CurrentUserDep, table_view: TableViewDep,
+        session: SessionDep, user: CurrentUserDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Notification]:
     return await Notification.get_with_count(
         session,
@@ -1370,18 +1402,42 @@ class UserUpdateRequest(UserBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1398,7 +1454,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/README.md

@@ -125,10 +125,12 @@ async def demo(session: AsyncSession):
 A complete REST API -- models, DTOs, and five endpoints:
 
 ```python
+from collections.abc import AsyncGenerator
 from typing import Annotated
 from uuid import UUID
 
 from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sqlmodel_ext import (
@@ -136,17 +138,37 @@ from sqlmodel_ext import (
     ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
 )
 
-# ── Dependencies (defined once, reused everywhere) ────────────────
+# ── Dependency-injection layer: declare once (e.g. in a shared
+#    deps module), every router imports the type aliases ────────────
+
+_engine = create_async_engine("postgresql+asyncpg://localhost/app")
+_Session = async_sessionmaker(_engine, expire_on_commit=True)
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with _Session() as session:
+        yield session
 
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
-TableViewDep = Annotated[TableViewRequest, Depends()]
+"""Request-scoped AsyncSession. The single way endpoints touch the DB."""
 
-# ── Models ────────────────────────────────────────────────────────
+# TableViewRequest is a Pydantic model → FastAPI binds its fields as
+# query params automatically. No hand-written offset/limit/order plumbing.
+TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+
+async def get_current_user(session: SessionDep) -> "User":
+    ...  # decode the bearer token, load the user — your auth, unchanged
+
+CurrentUserDep = Annotated["User", Depends(get_current_user)]
+
+# ── Models: the DTO ladder (Base → Create → Update → Response) ─────
 
 class ArticleBase(SQLModelBase):
     title: Str64
+    """Article title"""
     body: Text10K
+    """Article body (max 10k chars)"""
     is_published: bool = False
+    """Whether the article is publicly visible"""
 
 class Article(ArticleBase, UUIDTableBaseMixin, table=True):
     author_id: UUID = Field(foreign_key='user.id')
@@ -154,14 +176,24 @@ class Article(ArticleBase, UUIDTableBaseMixin, table=True):
 class ArticleCreate(ArticleBase):
     pass
 
-class ArticleUpdate(ArticleBase):
-    title: Str64 | None = None       # Override to optional,
-    body: Text10K | None = None      # preserving the original
-    is_published: bool | None = None  # type constraints from Base
+# all_fields_optional flips every inherited field to ``T | None = None``
+# while preserving its Annotated constraints AND attribute docstrings —
+# no hand-maintained per-field overrides.
+class ArticleUpdate(ArticleBase, all_fields_optional=True):
+    pass
 
 class ArticleResponse(ArticleBase, UUIDIdDatetimeInfoMixin):
     author_id: UUID
 
+# ── Resource-as-dependency: wrap "load by id or 404" once, then the
+#    fetched ORM instance is just another injected parameter ────────
+
+async def get_article(session: SessionDep, article_id: UUID) -> Article:
+    return await Article.get_exist_one(session, article_id)
+
+ArticleDep = Annotated[Article, Depends(get_article)]
+"""The Article for {article_id}, or 404 — fetched before the handler runs."""
+
 # ── Endpoints ─────────────────────────────────────────────────────
 
 router = APIRouter(prefix="/articles", tags=["articles"])
@@ -175,7 +207,7 @@ async def create_article(
 
 @router.get("", response_model=ListResponse[ArticleResponse])
 async def list_articles(
-        session: SessionDep, table_view: TableViewDep,
+        session: SessionDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Article]:
     return await Article.get_with_count(
         session,
@@ -183,24 +215,24 @@ async def list_articles(
         table_view=table_view,
     )
 
+# article: ArticleDep — the 404 + fetch is the dependency's job, so the
+# single-resource handlers carry no lookup boilerplate at all.
 @router.get("/{article_id}", response_model=ArticleResponse)
-async def get_article(session: SessionDep, article_id: UUID) -> Article:
-    return await Article.get_exist_one(session, article_id)
+async def get_article_detail(article: ArticleDep) -> Article:
+    return article
 
 @router.patch("/{article_id}", response_model=ArticleResponse)
 async def update_article(
-        session: SessionDep, article_id: UUID, data: ArticleUpdate,
+        session: SessionDep, article: ArticleDep, data: ArticleUpdate,
 ) -> Article:
-    article = await Article.get_exist_one(session, article_id)
     return await article.update(session, data)
 
 @router.delete("/{article_id}")
-async def delete_article(session: SessionDep, article_id: UUID) -> None:
-    article = await Article.get_exist_one(session, article_id)
+async def delete_article(session: SessionDep, article: ArticleDep) -> None:
     await Article.delete(session, article)
 ```
 
-No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
+No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewRequestDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
 
 **What the client gets from `GET /articles?offset=0&limit=10&desc=true`:**
 
@@ -395,7 +427,7 @@ class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMix
 
 @router.get("/notifications", response_model=ListResponse[NotificationBase])
 async def list_notifications(
-        session: SessionDep, user: CurrentUserDep, table_view: TableViewDep,
+        session: SessionDep, user: CurrentUserDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Notification]:
     return await Notification.get_with_count(
         session,
@@ -1325,18 +1357,42 @@ class UserUpdateRequest(UserBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1353,7 +1409,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/README_zh.md

@@ -1288,15 +1288,28 @@ class ArticleUpdateRequest(ArticleBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### 增强 AsyncSession（缓存感知 commit/reset/refresh）
 
-安全重置异步会话，同时清理 FOR UPDATE 锁跟踪：
+`sqlmodel_ext.AsyncSession` 是 sqlmodel `AsyncSession` 的增强子类，把缓存正确性变为自动行为。把 session 工厂指向它：
 
 ```python
-from sqlmodel_ext import safe_reset
-await safe_reset(session)
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
+
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
+能力：
+
+- **`commit()`** 自动登记 session 中所有 `CachedTableBaseMixin` 变更（含裸 `session.add()` / 改属性 / `session.delete()` 路径），commit 后同步失效 Redis 缓存——消除"忘记 cache-aware commit"的 stale 窗口。
+- **`reset()`** 释放连接并清理 `session.info` 中的 FOR UPDATE 锁跟踪 + 缓存失效跟踪（替代已删除的 `safe_reset()`——直接 `await session.reset()` 即可）。
+- **`refresh()`** 对缓存模型的整体刷新走 `Model.get()`（Redis 命中 + STI 多态列），而非裸查 DB。
+- **`execute()`** 对绕过缓存失效的裸 `UPDATE`/`DELETE` 打 WARNING。
+
+不使用 `CachedTableBaseMixin` 的模型完全不受影响——所有钩子退化为上游行为。
+
+> **0.4.0 Breaking change**：`safe_reset()` 与 `CachedTableBaseMixin.cache_aware_commit()` 已删除。CRUD 方法不再自行失效缓存，失效统一发生在 `AsyncSession.commit()` 内。使用 `CachedTableBaseMixin` 时**必须**以 `class_=sqlmodel_ext.AsyncSession` 构造 session（普通 session 会退化为 fire-and-forget 的 `after_commit` 补偿钩子，重新引入短暂的 stale 窗口）。
+
 ---
 
 ## 架构
@@ -1312,7 +1325,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse、TimeFilterRequest、PaginationRequest、TableViewRequest
     mixins/
         __init__.py          # Mixin 重导出
-        table.py             # TableBaseMixin、UUIDTableBaseMixin、safe_reset（异步 CRUD）
+        table.py             # TableBaseMixin、UUIDTableBaseMixin（异步 CRUD）
         cached_table.py      # CachedTableBaseMixin（双层 Redis 缓存 + 版本号失效）
         polymorphic.py       # PolymorphicBaseMixin、AutoPolymorphicIdentityMixin、create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin、OptimisticLockError

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/docs/en/how-to/index.md

@@ -20,7 +20,7 @@
 
 - [Handle concurrent updates](./handle-concurrent-updates) — Use `OptimisticLockMixin` to prevent lost updates
 - [Prevent MissingGreenlet errors](./prevent-missing-greenlet) — `@requires_relations` + `lazy='raise_on_sql'` + static analysis: three layers of defense
-- [Release the DB connection during long I/O](./release-connection-during-long-io) — Use `safe_reset()` to keep external I/O from exhausting the pool
+- [Release the DB connection during long I/O](./release-connection-during-long-io) — Use `session.reset()` to keep external I/O from exhausting the pool
 
 ### Performance
 

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/docs/en/how-to/release-connection-during-long-io.md

@@ -28,11 +28,11 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     return file
 ```
 
-## 2. Use `safe_reset()` around the I/O block
+## 2. Use `session.reset()` around the I/O block
 
-```python
-from sqlmodel_ext import safe_reset
+> Since 0.4.0 `safe_reset()` has been removed -- its responsibility moved into the enhanced `sqlmodel_ext.AsyncSession.reset()` (construct sessions with `async_sessionmaker(class_=AsyncSession)`). `reset()` releases the connection and also clears FOR UPDATE lock tracking and cache-invalidation tracking.
 
+```python
 @router.get("/files/{file_id}")
 async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     file = await UserFile.get(session, UserFile.id == file_id)
@@ -42,7 +42,7 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
         key = file.key
         file_id = file.id
 
-        await safe_reset(session)  # ← release the DB connection // [!code ++]
+        await session.reset()  # ← release the DB connection // [!code ++]
 
         # ↓ This block holds NO DB connection — concurrent requests can use the pool
         data = await s3.download_file(bucket_id, key)
@@ -56,26 +56,26 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
 ```
 
 **Key points**:
-- `safe_reset` releases the current transaction and connection, but the session object itself stays alive (it's not closed)
+- `session.reset()` releases the current transaction and connection, but the session object itself stays alive (it's not closed)
 - Any subsequent `await Model.get/save` that issues SQL transparently checks out a new connection from the pool
 - During the released window all 30 connections are idle (unless other requests use them) — concurrent requests **are not stalled**
 
-## 3. Object state after `safe_reset`: detached but not expired
+## 3. Object state after `session.reset()`: detached but not expired
 
-After `safe_reset`, every ORM object in the session enters the **detached** state (no longer in `session.identity_map`), but **already-loaded scalar fields remain in `obj.__dict__`** — accessing them does not trigger a SQL query, so it does **not** raise `MissingGreenlet`.
+After `session.reset()`, every ORM object in the session enters the **detached** state (no longer in `session.identity_map`), but **already-loaded scalar fields remain in `obj.__dict__`** — accessing them does not trigger a SQL query, so it does **not** raise `MissingGreenlet`.
 
 ```python
 from sqlalchemy import inspect as sa_inspect
 
-# Before safe_reset:
+# Before reset:
 file = await UserFile.get(session, UserFile.id == fid)
 print(sa_inspect(file).detached)  # False
 print(sa_inspect(file).expired)   # False
 print(file.bucket_id)             # OK, loaded
 
-await safe_reset(session)
+await session.reset()
 
-# After safe_reset:
+# After reset:
 print(sa_inspect(file).detached)  # True  ← note // [!code highlight]
 print(sa_inspect(file).expired)   # False ← loaded fields are NOT expired // [!code highlight]
 print(file.bucket_id)             # OK! scalar field access is safe // [!code ++]
@@ -84,7 +84,7 @@ print(file.parent)                # InvalidRequestError or MissingGreenlet // [!
 
 ### Safe-access rules
 
-| Access | After safe_reset | Why |
+| Access | After session.reset() | Why |
 |--------|-----------------|-----|
 | Already-loaded scalar field | ✓ Safe | In `__dict__`, no DB query |
 | Already-loaded relation (preloaded via `load=`) | ✓ Safe | Same |
@@ -93,7 +93,7 @@ print(file.parent)                # InvalidRequestError or MissingGreenlet // [!
 
 ### Recommended style
 
-When writing the code that runs **before** `safe_reset`, extract any field you'll need later into local variables:
+When writing the code that runs **before** `session.reset()`, extract any field you'll need later into local variables:
 
 ```python
 # Recommended:
@@ -102,7 +102,7 @@ bucket_id = file.bucket_id
 key = file.key
 user_id = file.user_id
 
-await safe_reset(session)
+await session.reset()
 
 # The code below uses local variables (file_id / bucket_id / ...),
 # never touches file.X again.
@@ -112,10 +112,10 @@ This way, even if some field on the model becomes lazy-loaded in the future, the
 
 ## 4. You must re-query before writing
 
-After `safe_reset` the object is detached and **cannot be saved directly**. To write, re-query a fresh attached instance:
+After `session.reset()` the object is detached and **cannot be saved directly**. To write, re-query a fresh attached instance:
 
 ```python
-await safe_reset(session)
+await session.reset()
 
 # Long I/O...
 metadata = await fetch_external_metadata(...)
@@ -130,15 +130,15 @@ file.metadata = metadata
 await file.save(session)
 ```
 
-## 5. When to use safe_reset vs Taskiq dispatch
+## 5. When to use session.reset() vs Taskiq dispatch
 
-`safe_reset` fits when you **must** synchronously return a result to the client. If your business can tolerate async — dispatch a job, return immediately, let the client poll — use Taskiq instead and **don't do long I/O in the HTTP endpoint at all**.
+`session.reset()` fits when you **must** synchronously return a result to the client. If your business can tolerate async — dispatch a job, return immediately, let the client poll — use Taskiq instead and **don't do long I/O in the HTTP endpoint at all**.
 
 ```mermaid
 flowchart TD
     A["Need long I/O in the endpoint?"] --> B{Can the response wait until the next poll?}
     B -- Yes --> C["Dispatch a Taskiq task<br/>return status=pending immediately"]
-    B -- No --> D["safe_reset to release connection<br/>execute the long I/O synchronously"]
+    B -- No --> D["session.reset() to release connection<br/>execute the long I/O synchronously"]
     C --> E["Cleanest, holds zero connection time"]
     D --> F["Pool is usable during the released window<br/>but still occupies a worker coroutine"]
 ```
@@ -147,7 +147,7 @@ flowchart TD
 |----------|-------------|
 | Polling for upload status | Taskiq (the polling client picks up the state change) |
 | AI generation tasks (image/video) | Taskiq (the project's mainstream pattern) |
-| Synchronous response that must contain the full result (e.g. PDF export) | safe_reset |
+| Synchronous response that must contain the full result (e.g. PDF export) | session.reset() |
 | WebSocket long connections | `session.close()` + per-message short-lived sessions |
 
 ## 6. Verification: did your endpoint actually release the connection?
@@ -169,13 +169,13 @@ def _on_checkin(conn, rec):
 
 Trigger a request that hits the long-I/O path. You should see:
 1. `checkout 1/N` — endpoint starts
-2. `checkin 0/N` — safe_reset fires
+2. `checkin 0/N` — session.reset() fires
 3. 30 seconds of external I/O with no checkout log in between
 4. `checkout 1/N` — subsequent DB op
 5. `checkin 0/N` — endpoint cleanup
 
 ## 7. Related
 
-- [`safe_reset()` API reference](/en/reference/decorators#safe-reset)
+- [`session.reset()` API reference](/en/reference/decorators#session-reset)
 - [Integrate with FastAPI](./integrate-with-fastapi)
 - [Prevent MissingGreenlet](./prevent-missing-greenlet)

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.4.0}/docs/en/reference/decorators.md

@@ -113,21 +113,23 @@ scope = cond(UserFile.user_id == current_user.id)
 condition = scope & cond(UserFile.status == FileStatusEnum.uploaded)
 ```
 
-## `safe_reset()`
+## `session.reset()` (enhanced AsyncSession) {#session-reset}
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlmodel_ext import AsyncSession
 ```
 
-**Signature**:
+**Signature** (enhanced method on `sqlmodel_ext.session.AsyncSession`):
 
 ```python
-async def safe_reset(session: AsyncSession) -> None
+async def reset(self) -> None
 ```
 
-**Purpose**: clears the FOR UPDATE lock tracking set in `session.info[SESSION_FOR_UPDATE_KEY]` before calling `session.reset()`. Safer than calling `session.reset()` directly — prevents the lock-tracking set from leaking into the next session reuse cycle.
+> Replaces the removed `safe_reset()` helper since 0.4.0. Construct sessions with `async_sessionmaker(class_=AsyncSession)` and simply `await session.reset()`.
+
+**Purpose**: after the upstream `reset()` (releasing the transaction and connection), automatically clears the FOR UPDATE lock-tracking set in `session.info[SESSION_FOR_UPDATE_KEY]` and the cache-invalidation tracking state — preventing tracking state from leaking into the next session reuse cycle.
 
-**Typical use case**: an HTTP endpoint / Taskiq task needs to do long external I/O mid-flight (S3, ffprobe, third-party HTTP polling, etc.). Call `safe_reset` first to release the DB connection, so the connection isn't blocked on network I/O and the pool isn't exhausted. See [Release the DB connection during long I/O](/en/how-to/release-connection-during-long-io).
+**Typical use case**: an HTTP endpoint / Taskiq task needs to do long external I/O mid-flight (S3, ffprobe, third-party HTTP polling, etc.). Call `session.reset()` first to release the DB connection, so the connection isn't blocked on network I/O and the pool isn't exhausted. See [Release the DB connection during long I/O](/en/how-to/release-connection-during-long-io).
 
 **Object state after the call**: