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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lush-sqlalchemyx
-Version: 0.3.2
+Version: 0.4.0
 Summary: SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations
 Author: straydragon
 Author-email: straydragon <straydragonl@foxmail.com>

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

@@ -1,6 +1,6 @@
 [project]
 name = "lush-sqlalchemyx"
-version = "0.3.2"
+version = "0.4.0"
 description = "SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations"
 readme = "README.md"
 requires-python = ">=3.10"

lush_sqlalchemyx-0.4.0/src/lush_sqlalchemyx/__init__.py

@@ -0,0 +1,19 @@
+"""lush-sqlalchemyx — SQLAlchemy DAL 实现 + async/sync MySQL manager + 框架集成.
+
+导入本包时会自动注册软删除 Session 事件监听器.
+如需显式管理钩子生命周期, 参见 :func:`register_soft_delete_hooks` 等.
+"""
+
+from lush_sqlalchemyx.base.dal import (
+    is_soft_delete_hooks_registered,
+    register_soft_delete_hooks,
+    setup_dal_hooks,
+    unregister_soft_delete_hooks,
+)
+
+__all__ = (
+    "is_soft_delete_hooks_registered",
+    "register_soft_delete_hooks",
+    "setup_dal_hooks",
+    "unregister_soft_delete_hooks",
+)

{lush_sqlalchemyx-0.3.2 → lush_sqlalchemyx-0.4.0}/src/lush_sqlalchemyx/base/dal/__init__.py

@@ -43,6 +43,7 @@ from ._common import (
     CUModelT,
     DBRetryableError,
     DTOModelT,
+    FieldIsDeleteSoftDeleteTableMixin,
     FieldMixin,
     ReadOnlyMixin,
     RetryConfig,
@@ -52,6 +53,10 @@ from ._common import (
     StdBaseDTO,
     escape_like,
     filtered_in_sql_values,
+    is_soft_delete_hooks_registered,
+    register_soft_delete_hooks,
+    setup_dal_hooks,
+    unregister_soft_delete_hooks,
 )
 
 # Event listener references — accessed by tests via getattr(module, name).
@@ -102,10 +107,15 @@ __all__ = (
     "RetryConfig",
     "SQLATableT",
     "SoftDeleteTableMixin",
+    "FieldIsDeleteSoftDeleteTableMixin",
     "StdBaseCU",
     "StdBaseDTO",
     "escape_like",
     "filtered_in_sql_values",
+    "is_soft_delete_hooks_registered",
+    "register_soft_delete_hooks",
+    "setup_dal_hooks",
+    "unregister_soft_delete_hooks",
     # async
     "AsyncBaseDAL",
     "AsyncRawDAL",

{lush_sqlalchemyx-0.3.2 → lush_sqlalchemyx-0.4.0}/src/lush_sqlalchemyx/base/dal/_async.py

@@ -31,6 +31,7 @@ from ._common import (
     CUModelT,
     DBRetryableError,
     DTOModelT,
+    FieldIsDeleteSoftDeleteTableMixin,
     ReadOnlyMixin,
     RetryConfig,
     SoftDeleteTableMixin,
@@ -142,7 +143,7 @@ class ReadOnlyBasicAsyncBaseTable(AsyncSqlATableBase, ReadOnlyMixin):
     __abstract__ = True
 
 
-class StdAsyncBaseTable(BasicAsyncBaseTable, SoftDeleteTableMixin):
+class StdAsyncBaseTable(BasicAsyncBaseTable, FieldIsDeleteSoftDeleteTableMixin):
     """标准异步表类: 包含 id/时间戳/操作人/软删除等标准字段.
 
     .. deprecated::
@@ -333,7 +334,10 @@ class AsyncReadDAL(
         session: AsyncSession,
         entity_id: int,
     ) -> AsyncSQLATableT | None:
-        return await session.get(cls._Table, entity_id)
+        entity = await session.get(cls._Table, entity_id)
+        if entity is not None and isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted:
+            return None
+        return entity
 
     @classmethod
     async def batch_get_field__entity(
@@ -407,6 +411,8 @@ class AsyncReadDAL(
     ) -> DTOModelT | None:
         entity = await session.get(cls._Table, entity_id)
         if entity:
+            if isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted:
+                return None
             if need_refresh:
                 await session.refresh(entity)
             return cls._DTO.model_validate(entity)
@@ -428,7 +434,9 @@ class AsyncReadDAL(
     @classmethod
     async def exists(cls, session: AsyncSession, entity_id: int) -> bool:
         entity = await session.get(cls._Table, entity_id)
-        return entity is not None
+        if entity is None:
+            return False
+        return not (isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted)
 
     @classmethod
     async def get_by_id_for_update(

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

@@ -212,15 +212,51 @@ class StdBaseDTO(BaseDTO[CUModelT]):
 
 
 class SoftDeleteTableMixin:
-    """软删除表混入类."""
+    """软删除表标记混入类 — 不强制任何列名或类型.
 
-    is_delete: Mapped[int] = mapped_column(sa.Integer, default=0, comment="逻辑删除")
+    子类必须提供软删除列并覆写 ``is_soft_deleted`` property.
+    快捷方式: 继承 ``FieldIsDeleteSoftDeleteTableMixin`` 获得标准 ``is_delete`` 列.
+
+    自定义示例::
+
+        class MyTable(Base, SoftDeleteTableMixin):
+            __soft_delete_column__ = "deleted_at"
+
+            deleted_at: Mapped[datetime | None] = mapped_column(sa.DateTime, nullable=True, default=None)
+
+            @property
+            def is_soft_deleted(self) -> bool:
+                return self.deleted_at is not None
 
-    def delete(self, is_delete: int = 1) -> None:
-        self.is_delete = is_delete
+            def soft_delete(self) -> None:
+                from datetime import datetime, timezone
 
-    def undelete(self) -> None:
-        self.is_delete = 0
+                self.deleted_at = datetime.now(timezone.utc)
+    """
+
+    __soft_delete_column__: ClassVar[str] = "is_delete"
+
+    def soft_delete(self) -> None:
+        """标记为软删除."""
+        setattr(self, self.__soft_delete_column__, 1)
+
+    def soft_undelete(self) -> None:
+        """恢复软删除."""
+        setattr(self, self.__soft_delete_column__, 0)
+
+    @property
+    def is_soft_deleted(self) -> bool:
+        """实体是否已被软删除（默认检查 ``is_delete != 0``，子类可覆写）."""
+        return bool(getattr(self, self.__soft_delete_column__))
+
+
+class FieldIsDeleteSoftDeleteTableMixin(SoftDeleteTableMixin):
+    """标准软删除混入类 — 提供 ``is_delete: Mapped[int]`` 列.
+
+    等价旧版 ``SoftDeleteTableMixin``，仅需 rename.
+    """
+
+    is_delete: Mapped[int] = mapped_column(sa.Integer, default=0, comment="逻辑删除")
 
 
 class ReadOnlyMixin:
@@ -267,6 +303,65 @@ class FieldMixin:
                 return
 
 
+# ---------------------------------------------------------------------------
+# Soft-delete hook management API (explicit register/unregister/check)
+# ---------------------------------------------------------------------------
+
+
+def register_soft_delete_hooks() -> None:
+    """显式注册软删除 Session 事件监听器（幂等）。
+
+    在以下场景需要显式调用:
+    - 多进程 worker 子进程（import 可能未触发）
+    - 测试中自建 Session、未走应用启动链
+    - FastAPI lifespan / Flask app factory 显式初始化
+    """
+    if not sa_event.contains(SyncSession, "before_flush", __receive_before_flush):
+        sa_event.listen(SyncSession, "before_flush", __receive_before_flush, insert=True)
+    if not sa_event.contains(SyncSession, "do_orm_execute", __add_filtering_criteria):
+        sa_event.listen(SyncSession, "do_orm_execute", __add_filtering_criteria, insert=True)
+
+
+def unregister_soft_delete_hooks() -> None:
+    """注销软删除 Session 事件监听器（幂等）。"""
+    if sa_event.contains(SyncSession, "before_flush", __receive_before_flush):
+        sa_event.remove(SyncSession, "before_flush", __receive_before_flush)
+    if sa_event.contains(SyncSession, "do_orm_execute", __add_filtering_criteria):
+        sa_event.remove(SyncSession, "do_orm_execute", __add_filtering_criteria)
+
+
+def is_soft_delete_hooks_registered() -> bool:
+    """检查软删除钩子是否已注册。"""
+    return sa_event.contains(SyncSession, "before_flush", __receive_before_flush) and sa_event.contains(
+        SyncSession, "do_orm_execute", __add_filtering_criteria
+    )
+
+
+def setup_dal_hooks() -> None:
+    """注册所有必要的 Session 事件监听器（幂等）。
+
+    在应用生命周期开始时**调用一次**即可，无需关注具体注册了哪些钩子。
+    涵盖：软删除拦截、软删除查询过滤、只读保护。
+
+    FastAPI 示例::
+
+        @asynccontextmanager
+        async def lifespan(app):
+            setup_dal_hooks()
+            yield
+
+    Flask 示例::
+
+        def create_app():
+            app = Flask(__name__)
+            setup_dal_hooks()
+            return app
+    """
+    register_soft_delete_hooks()
+    if not sa_event.contains(SyncSession, "before_flush", __prevent_readonly_write):
+        sa_event.listen(SyncSession, "before_flush", __prevent_readonly_write, insert=True)
+
+
 # ---------------------------------------------------------------------------
 # Session event listeners (registered on SyncSession — works for both sync
 # and async since AsyncSession delegates to a SyncSession internally)
@@ -277,7 +372,7 @@ class FieldMixin:
 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):
-            instance.delete()
+            instance.soft_delete()
             session.add(instance)
 
 
@@ -292,7 +387,7 @@ def __add_filtering_criteria(execute_state: ORMExecuteState) -> None:  # pyright
         execute_state.statement = execute_state.statement.options(
             with_loader_criteria(
                 SoftDeleteTableMixin,
-                lambda t: t.is_delete == 0,
+                lambda cls: getattr(cls, getattr(cls, "__soft_delete_column__", "is_delete"), sa.null()) == 0,
                 include_aliases=True,
             )
         )
@@ -352,6 +447,11 @@ __all__ = (
     "T",
     "V",
     "_ensure_strict_fields",
+    "FieldIsDeleteSoftDeleteTableMixin",
     "escape_like",
     "filtered_in_sql_values",
+    "is_soft_delete_hooks_registered",
+    "register_soft_delete_hooks",
+    "setup_dal_hooks",
+    "unregister_soft_delete_hooks",
 )

{lush_sqlalchemyx-0.3.2 → lush_sqlalchemyx-0.4.0}/src/lush_sqlalchemyx/base/dal/_sync.py

@@ -28,6 +28,7 @@ from ._common import (
     CUModelT,
     DBRetryableError,
     DTOModelT,
+    FieldIsDeleteSoftDeleteTableMixin,
     ReadOnlyMixin,
     RetryConfig,
     SoftDeleteTableMixin,
@@ -136,7 +137,7 @@ class ReadOnlySyncBaseTable(SyncSqlATableBase, ReadOnlyMixin):
     __abstract__ = True
 
 
-class StdSyncBaseTable(BasicSyncBaseTable, SoftDeleteTableMixin):
+class StdSyncBaseTable(BasicSyncBaseTable, FieldIsDeleteSoftDeleteTableMixin):
     """标准同步表类: 包含 id/时间戳/操作人/软删除等标准字段.
 
     .. deprecated::
@@ -326,7 +327,10 @@ class SyncReadDAL(
         session: Session,
         entity_id: int,
     ) -> SyncSQLATableT | None:
-        return session.get(cls._Table, entity_id)
+        entity = session.get(cls._Table, entity_id)
+        if entity is not None and isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted:
+            return None
+        return entity
 
     @classmethod
     def batch_get_field__entity(
@@ -398,6 +402,8 @@ class SyncReadDAL(
     ) -> DTOModelT | None:
         entity = session.get(cls._Table, entity_id)
         if entity:
+            if isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted:
+                return None
             if need_refresh:
                 session.refresh(entity)
             return cls._DTO.model_validate(entity)
@@ -419,7 +425,9 @@ class SyncReadDAL(
     @classmethod
     def exists(cls, session: Session, entity_id: int) -> bool:
         entity = session.get(cls._Table, entity_id)
-        return entity is not None
+        if entity is None:
+            return False
+        return not (isinstance(entity, SoftDeleteTableMixin) and entity.is_soft_deleted)
 
     @classmethod
     def get_by_id_for_update(