lush-sqlalchemyx 0.4.0__tar.gz → 0.4.2__tar.gz

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lush-sqlalchemyx
-Version: 0.4.0
+Version: 0.4.2
 Summary: SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations
 Author: straydragon
 Author-email: straydragon <straydragonl@foxmail.com>
@@ -12,7 +12,7 @@ Requires-Dist: pydantic>=2.3.0,<3.0.0
 Requires-Dist: typing-extensions>=4.12.2
 Requires-Dist: lush-pydanticx>=0.1.0
 Requires-Dist: lush-stdx>=0.1.0
-Requires-Dist: lush-dal-protocol>=0.1.0
+Requires-Dist: lush-dal-protocol>=0.2.2
 Requires-Dist: sqlalchemy[asyncio]>=2.0.43 ; extra == 'asyncio'
 Requires-Dist: flask-sqlalchemy>=3.1.1 ; extra == 'flask'
 Requires-Python: >=3.10

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lush-sqlalchemyx"
-version = "0.4.0"
+version = "0.4.2"
 description = "SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,7 +16,7 @@ dependencies = [
     "typing-extensions>=4.12.2",
     "lush-pydanticx>=0.1.0",
     "lush-stdx>=0.1.0",
-    "lush-dal-protocol>=0.1.0",
+    "lush-dal-protocol>=0.2.2",
 ]
 
 [project.optional-dependencies]

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/src/lush_sqlalchemyx/__init__.py

@@ -1,7 +1,12 @@
 """lush-sqlalchemyx — SQLAlchemy DAL 实现 + async/sync MySQL manager + 框架集成.
 
-导入本包时会自动注册软删除 Session 事件监听器.
-如需显式管理钩子生命周期, 参见 :func:`register_soft_delete_hooks` 等.
+使用前须在应用启动时调用 :func:`setup_dal_hooks` 注册 Session 事件监听器:
+
+- Flask: 使用 ``LushFlaskSQLAlchemy.init_db()`` 时自动调用
+- FastAPI: 在 ``lifespan`` 中调用 ``setup_dal_hooks()``
+- 其他场景: 在创建 Session 前调用一次 ``setup_dal_hooks()``
+
+不调用则软删除、只读保护等钩子不会生效。
 """
 
 from lush_sqlalchemyx.base.dal import (

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/src/lush_sqlalchemyx/base/dal/_common.py

@@ -343,6 +343,11 @@ def setup_dal_hooks() -> None:
     在应用生命周期开始时**调用一次**即可，无需关注具体注册了哪些钩子。
     涵盖：软删除拦截、软删除查询过滤、只读保护。
 
+    **时序说明**: 模型类的定义（继承 SoftDeleteTableMixin / ReadOnlyMixin）
+    可以在调用 setup_dal_hooks 之前或之后 — 均不影响钩子生效。
+    因为钩子注册在 SyncSession 上，在 flush/query 时通过 isinstance 和
+    with_loader_criteria 动态评估，不依赖模型类在注册时刻的状态。
+
     FastAPI 示例::
 
         @asynccontextmanager
@@ -364,11 +369,18 @@ def setup_dal_hooks() -> None:
 
 # ---------------------------------------------------------------------------
 # Session event listeners (registered on SyncSession — works for both sync
-# and async since AsyncSession delegates to a SyncSession internally)
+# and async since AsyncSession delegates to a SyncSession internally).
+#
+# 不再使用 @sa_event.listens_for 装饰器在 import 时自动注册。
+# 改为通过 setup_dal_hooks() / register_soft_delete_hooks() 显式注册。
+# 这样做的原因: 让注册时机清晰可预测, 避免用户对"何时调用 setup_dal_hooks"
+# 产生困惑。在 Flask/FastAPI 集成中 auto-call 保证开箱即用。
+#
+# 模型类定义在 setup_dal_hooks 之前或之后均不影响钩子生效 —
+# isinstance 和 with_loader_criteria 在 flush/query 时动态评估。
 # ---------------------------------------------------------------------------
 
 
-@sa_event.listens_for(SyncSession, "before_flush")
 def __receive_before_flush(session: SyncSession, flush_context: Any, instances: Any) -> None:  # noqa: ARG001 # pyright: ignore[reportUnusedFunction, reportUnusedParameter]
     for instance in session.deleted:
         if isinstance(instance, SoftDeleteTableMixin):
@@ -376,7 +388,6 @@ def __receive_before_flush(session: SyncSession, flush_context: Any, instances:
             session.add(instance)
 
 
-@sa_event.listens_for(SyncSession, "do_orm_execute")
 def __add_filtering_criteria(execute_state: ORMExecuteState) -> None:  # pyright: ignore[reportUnusedFunction]
     if (
         not execute_state.is_column_load
@@ -393,7 +404,6 @@ def __add_filtering_criteria(execute_state: ORMExecuteState) -> None:  # pyright
         )
 
 
-@sa_event.listens_for(SyncSession, "before_flush")
 def __prevent_readonly_write(session: SyncSession, flush_context: Any, instances: Any) -> None:  # noqa: ARG001 # pyright: ignore[reportUnusedFunction, reportUnusedParameter]
     for obj in session.new.union(session.dirty).union(session.deleted):
         if isinstance(obj, ReadOnlyMixin):

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/src/lush_sqlalchemyx/integrations/fastapi/depends/__init__.py

@@ -1,4 +1,18 @@
-"""FastAPI 依赖工厂:为 AsyncMySQL 管理器与会话提供依赖注入工具."""
+"""FastAPI 依赖工厂:为 AsyncMySQL 管理器与会话提供依赖注入工具.
+
+使用本模块前, 请在 FastAPI lifespan 中调用 ``setup_dal_hooks()``::
+
+    from contextlib import asynccontextmanager
+    from lush_sqlalchemyx import setup_dal_hooks
+
+
+    @asynccontextmanager
+    async def lifespan(app):
+        setup_dal_hooks()
+        yield
+
+不调用则软删除、只读保护等 Session 事件钩子不会生效.
+"""
 
 from collections.abc import AsyncIterator, Awaitable, Callable
 from typing import ClassVar, Generic

{lush_sqlalchemyx-0.4.0 → lush_sqlalchemyx-0.4.2}/src/lush_sqlalchemyx/integrations/flask/ext.py

@@ -29,6 +29,7 @@ except ImportError as _exc:  # pragma: no cover
 
 from sqlalchemy.orm import Session
 
+from lush_sqlalchemyx import setup_dal_hooks
 from lush_sqlalchemyx.base.dal._common import CUModelT, DTOModelT, SQLATableT
 from lush_sqlalchemyx.base.dal._sync import SyncBaseDAL, SyncReadDAL, SyncWriteDAL
 from lush_sqlalchemyx.mgrs.mysql.sync_manager import SyncMySQLManager
@@ -66,9 +67,10 @@ class LushFlaskSQLAlchemy:
             self.init_db(db)
 
     def init_db(self, db: SQLAlchemy) -> None:
-        """绑定到 Flask-SQLAlchemy 实例."""
+        """绑定到 Flask-SQLAlchemy 实例, 并注册 DAL Session 事件钩子."""
         self._db = db
         self._manager = SyncMySQLManager.from_engine(db.engine)
+        setup_dal_hooks()
 
     @property
     def manager(self) -> SyncMySQLManager: