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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lush-sqlalchemyx
-Version: 0.3.1
+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.1 → lush_sqlalchemyx-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lush-sqlalchemyx"
-version = "0.3.1"
+version = "0.4.0"
 description = "SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -149,9 +149,6 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"**/dal/_*_v2.py" = [
-    "ARG003",  # extra 参数是 ABC 合规所必需但在部分方法中未使用
-]
 "tests/**/*.py" = [
     # === 测试代码质量 ===
     "B011",    # assert False应改为raise AssertionError

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.1 → lush_sqlalchemyx-0.4.0}/src/lush_sqlalchemyx/base/dal/__init__.py

@@ -6,21 +6,14 @@
 # --- shared (sync/async agnostic) ---
 # --- lush-dal-protocol ABCs (ORM 无关的抽象层) ---
 from lush_dal_protocol import (
-    AbstractAsyncAdvancedWriteDAL,
     AbstractAsyncBaseDAL,
-    AbstractAsyncBatchFieldDAL,
-    AbstractAsyncLockDAL,
-    AbstractAsyncRawSQLDAL,
     AbstractAsyncReadDAL,
     AbstractAsyncWriteDAL,
-    AbstractSyncAdvancedWriteDAL,
     AbstractSyncBaseDAL,
-    AbstractSyncBatchFieldDAL,
-    AbstractSyncLockDAL,
-    AbstractSyncRawSQLDAL,
     AbstractSyncReadDAL,
     AbstractSyncWriteDAL,
 )
+from lush_dal_protocol.params.pagination import CursorPagination, CursorResult, OffsetPagination, PageResult
 
 # --- async (requires sqlalchemy[asyncio]) ---
 from ._async import (
@@ -40,9 +33,6 @@ from ._async import (
     async_temp_set_lock_wait_timeout,
     async_with_retry,
 )
-
-# --- V2 (ABC-compliant, options-based) ---
-from ._async_v2 import AsyncBaseDALV2, AsyncReadDALV2, AsyncWriteDALV2
 from ._common import (
     DEFAULT_RETRY_CONFIG,
     OPTIMISTIC_LOCK_ERROR_MSG_TRAIT,
@@ -53,6 +43,7 @@ from ._common import (
     CUModelT,
     DBRetryableError,
     DTOModelT,
+    FieldIsDeleteSoftDeleteTableMixin,
     FieldMixin,
     ReadOnlyMixin,
     RetryConfig,
@@ -62,16 +53,16 @@ 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).
 from ._common import __prevent_readonly_write as __prevent_readonly_write  # pyright: ignore[reportPrivateUsage]
 from ._common import __receive_before_flush as __receive_before_flush  # pyright: ignore[reportPrivateUsage]
 from ._pagination import (
-    CursorPagination,
-    CursorResult,
-    OffsetPagination,
-    PageResult,
     build_cursor_stmt,
     build_offset_stmt,
     decode_cursor,
@@ -79,7 +70,6 @@ from ._pagination import (
     make_cursor_result,
     make_page_result,
 )
-from ._params import SQLAExtra
 from ._repository import AsyncSQLAlchemyRepository, SyncSQLAlchemyRepository
 
 # --- sync ---
@@ -100,7 +90,6 @@ from ._sync import (
     sync_temp_set_lock_wait_timeout,
     sync_with_retry,
 )
-from ._sync_v2 import SyncBaseDALV2, SyncReadDALV2, SyncWriteDALV2
 
 __all__ = (
     # common
@@ -118,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",
@@ -165,30 +159,14 @@ __all__ = (
     "encode_cursor",
     "make_cursor_result",
     "make_page_result",
-    # V2
-    "AsyncBaseDALV2",
-    "AsyncReadDALV2",
-    "AsyncWriteDALV2",
-    "SQLAExtra",
-    "SyncBaseDALV2",
-    "SyncReadDALV2",
-    "SyncWriteDALV2",
     # repository
     "AsyncSQLAlchemyRepository",
     "SyncSQLAlchemyRepository",
     # lush-dal-protocol ABCs
-    "AbstractAsyncAdvancedWriteDAL",
     "AbstractAsyncBaseDAL",
-    "AbstractAsyncBatchFieldDAL",
-    "AbstractAsyncLockDAL",
-    "AbstractAsyncRawSQLDAL",
     "AbstractAsyncReadDAL",
     "AbstractAsyncWriteDAL",
-    "AbstractSyncAdvancedWriteDAL",
     "AbstractSyncBaseDAL",
-    "AbstractSyncBatchFieldDAL",
-    "AbstractSyncLockDAL",
-    "AbstractSyncRawSQLDAL",
     "AbstractSyncReadDAL",
     "AbstractSyncWriteDAL",
 )

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

@@ -15,6 +15,7 @@ from contextlib import asynccontextmanager, suppress
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, ParamSpec, TypeVar, cast
 
 import sqlalchemy as sa
+from lush_dal_protocol.abc import AbstractAsyncReadDAL, AbstractAsyncWriteDAL
 from pydantic import BaseModel
 from sqlalchemy import ColumnExpressionArgument
 from sqlalchemy.ext.asyncio import AsyncAttrs, AsyncSession
@@ -30,6 +31,7 @@ from ._common import (
     CUModelT,
     DBRetryableError,
     DTOModelT,
+    FieldIsDeleteSoftDeleteTableMixin,
     ReadOnlyMixin,
     RetryConfig,
     SoftDeleteTableMixin,
@@ -141,7 +143,7 @@ class ReadOnlyBasicAsyncBaseTable(AsyncSqlATableBase, ReadOnlyMixin):
     __abstract__ = True
 
 
-class StdAsyncBaseTable(BasicAsyncBaseTable, SoftDeleteTableMixin):
+class StdAsyncBaseTable(BasicAsyncBaseTable, FieldIsDeleteSoftDeleteTableMixin):
     """标准异步表类: 包含 id/时间戳/操作人/软删除等标准字段.
 
     .. deprecated::
@@ -316,7 +318,11 @@ class AsyncRawReadDAL:
             last_id = getattr(batch[-1], id_attr.key)
 
 
-class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
+class AsyncReadDAL(
+    AsyncRawReadDAL,
+    AbstractAsyncReadDAL[AsyncSession, AsyncSQLATableT, DTOModelT, int],
+    Generic[AsyncSQLATableT, DTOModelT],
+):
     """抽象只读数据访问层基类."""
 
     _Table: ClassVar[type[AsyncSQLATableT]]  # pyright: ignore[reportGeneralTypeIssues]
@@ -328,7 +334,10 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
         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(
@@ -402,6 +411,8 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
     ) -> 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)
@@ -423,18 +434,20 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
     @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_core(
+    async def get_by_id_for_update(
         cls,
         session: AsyncSession,
         entity_id: int,
         *,
-        timeout: int | None = None,
+        lock_wait_timeout: int | None = None,
     ) -> AsyncSQLATableT | None:
         try:
-            async with async_temp_set_lock_wait_timeout(session, timeout):
+            async with async_temp_set_lock_wait_timeout(session, lock_wait_timeout):
                 stmt = (
                     sa.select(cls._Table)
                     .where(cls._Table.id == entity_id)  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownArgumentType]
@@ -449,29 +462,19 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
             raise
 
     @classmethod
-    async def get_by_id_for_update(
-        cls,
-        session: AsyncSession,
-        entity_id: int,
-        *,
-        lock_wait_timeout: int | None = None,
-    ) -> AsyncSQLATableT | None:
-        return await cls._get_by_id_for_update_core(session, entity_id, timeout=lock_wait_timeout)
-
-    @classmethod
-    async def _batch_get_for_update_core(
+    async def batch_get_for_update(
         cls,
         session: AsyncSession,
         entity_ids: Iterable[int],
         *,
-        timeout: int | None = None,
+        lock_wait_timeout: int | None = None,
     ) -> list[AsyncSQLATableT]:
         filtered_ids = filtered_in_sql_values(entity_ids, int)
         if not filtered_ids:
             return []
 
         try:
-            async with async_temp_set_lock_wait_timeout(session, timeout):
+            async with async_temp_set_lock_wait_timeout(session, lock_wait_timeout):
                 stmt = (
                     sa.select(cls._Table)
                     .where(cls._Table.id.in_(filtered_ids))  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownArgumentType]
@@ -486,25 +489,15 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
             raise
 
     @classmethod
-    async def batch_get_for_update(
-        cls,
-        session: AsyncSession,
-        entity_ids: Iterable[int],
-        *,
-        lock_wait_timeout: int | None = None,
-    ) -> list[AsyncSQLATableT]:
-        return await cls._batch_get_for_update_core(session, entity_ids, timeout=lock_wait_timeout)
-
-    @classmethod
-    async def _get_one_for_update_core(
+    async def get_one_for_update(
         cls,
         session: AsyncSession,
         *,
         where_clauses: list[ColumnExpressionArgument[bool]],
-        timeout: int | None = None,
+        lock_wait_timeout: int | None = None,
     ) -> AsyncSQLATableT | None:
         try:
-            async with async_temp_set_lock_wait_timeout(session, timeout):
+            async with async_temp_set_lock_wait_timeout(session, lock_wait_timeout):
                 stmt = sa.select(cls._Table).with_for_update()
 
                 for clause in where_clauses:
@@ -518,16 +511,6 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
                 raise DBRetryableError(f"{PESSIMISTIC_LOCK_ERROR_MSG_TRAIT}-条件锁等待超时: {error_msg}") from e
             raise
 
-    @classmethod
-    async def get_one_for_update(
-        cls,
-        session: AsyncSession,
-        *,
-        where_clauses: list[ColumnExpressionArgument[bool]],
-        lock_wait_timeout: int | None = None,
-    ) -> AsyncSQLATableT | None:
-        return await cls._get_one_for_update_core(session, where_clauses=where_clauses, timeout=lock_wait_timeout)
-
     @classmethod
     async def iter_record_dtos(
         cls,
@@ -564,7 +547,12 @@ class AsyncRawDAL:
         return await session.execute(stmt, params)
 
 
-class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT, CUModelT]):
+class AsyncWriteDAL(
+    AsyncRawDAL,
+    AsyncRawReadDAL,
+    AbstractAsyncWriteDAL[AsyncSession, AsyncSQLATableT, DTOModelT, CUModelT, int],
+    Generic[AsyncSQLATableT, DTOModelT, CUModelT],
+):
     """写入数据访问层基类."""
 
     _Table: ClassVar[type[AsyncSQLATableT]]  # pyright: ignore[reportGeneralTypeIssues]
@@ -644,7 +632,7 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         _ensure_strict_fields(provided_keys=provided_keys, allowed_names=allowed_names, strict=strict)
 
     @classmethod
-    async def _update_full_by_id_core(
+    async def update_full_by_id(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -678,19 +666,7 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         return entity
 
     @classmethod
-    async def update_full_by_id(
-        cls,
-        session: AsyncSession,
-        entity_id: int,
-        cu: CUModelT,
-        *,
-        need_refresh: bool = False,
-        strict_missing: bool = True,
-    ) -> AsyncSQLATableT | None:
-        return await cls._update_full_by_id_core(session, entity_id, cu, need_refresh=need_refresh, strict_missing=strict_missing)
-
-    @classmethod
-    async def _update_partial_by_id_core(
+    async def update_partial_by_id(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -757,30 +733,6 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
             await session.refresh(entity)
         return entity
 
-    @classmethod
-    async def update_partial_by_id(
-        cls,
-        session: AsyncSession,
-        entity_id: int,
-        cu: CUModelT,
-        *,
-        need_refresh: bool = False,
-        fields: set[InstrumentedAttribute[Any]] | set[sa.Column[Any]] | None = None,
-        none_policy: Literal["ignore", "allow", "forbid"] = "ignore",
-        none_policy_overrides: dict[InstrumentedAttribute[Any] | sa.Column[Any], Literal["ignore", "allow", "forbid"]] | None = None,
-        strict: bool = False,
-    ) -> AsyncSQLATableT | None:
-        return await cls._update_partial_by_id_core(
-            session,
-            entity_id,
-            cu,
-            need_refresh=need_refresh,
-            fields=fields,
-            none_policy=none_policy,
-            none_policy_overrides=none_policy_overrides,
-            strict=strict,
-        )
-
     @classmethod
     async def delete_by_id(
         cls,
@@ -816,11 +768,11 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
             yield entity
 
     @classmethod
-    async def _batch_update_by_conditions_core(
+    async def batch_update_by_conditions(
         cls,
         session: AsyncSession,
         *,
-        conditions: list[ColumnExpressionArgument[bool]],
+        whereclause: list[ColumnExpressionArgument[bool]],
         update_data: dict[InstrumentedAttribute[Any], Any] | dict[sa.Column[Any], Any],
         updater_id: int | None = None,
     ) -> int:
@@ -845,24 +797,13 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         if hasattr(cls._Table, "update_operator_id") and updater_id is not None:
             final_update_data["update_operator_id"] = updater_id
 
-        stmt = sa.update(cls._Table).where(*conditions).values(**final_update_data)
+        stmt = sa.update(cls._Table).where(*whereclause).values(**final_update_data)
 
         result = await session.execute(stmt)
         await session.flush()
 
         return result.rowcount  # pyright: ignore[reportAttributeAccessIssue, reportUnknownMemberType, reportUnknownVariableType]
 
-    @classmethod
-    async def batch_update_by_conditions(
-        cls,
-        session: AsyncSession,
-        *,
-        whereclause: list[ColumnExpressionArgument[bool]],
-        update_data: dict[InstrumentedAttribute[Any], Any] | dict[sa.Column[Any], Any],
-        updater_id: int | None = None,
-    ) -> int:
-        return await cls._batch_update_by_conditions_core(session, conditions=whereclause, update_data=update_data, updater_id=updater_id)
-
     @classmethod
     async def batch_update_by_ids(
         cls,
@@ -876,15 +817,15 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         if not filtered_ids:
             return 0
         _id_column = cls._Table.id  # pyright: ignore[reportAttributeAccessIssue,reportUnknownVariableType, reportUnknownMemberType]
-        return await cls._batch_update_by_conditions_core(
+        return await cls.batch_update_by_conditions(
             session,
-            conditions=[_id_column.in_(filtered_ids)],  # pyright: ignore[reportUnknownMemberType]
+            whereclause=[_id_column.in_(filtered_ids)],  # pyright: ignore[reportUnknownMemberType]
             update_data=update_data,
             updater_id=updater_id,
         )
 
     @classmethod
-    async def _update_only_set_with_optimistic_lock_core(
+    async def update_only_set_with_optimistic_lock(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -935,45 +876,13 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
 
         raise DBRetryableError(f"{OPTIMISTIC_LOCK_ERROR_MSG_TRAIT}-版本号不匹配({entity_id=}, {expected_version=})")
 
-    @classmethod
-    async def update_only_set_with_optimistic_lock(
-        cls,
-        session: AsyncSession,
-        entity_id: int,
-        cu: CUModelT,
-        *,
-        expected_version: int,
-        need_refresh: bool = False,
-        version_field: str = "version",
-    ) -> AsyncSQLATableT | None:
-        return await cls._update_only_set_with_optimistic_lock_core(
-            session,
-            entity_id,
-            cu,
-            expected_version=expected_version,
-            need_refresh=need_refresh,
-            version_field=version_field,
-        )
-
 
 class AsyncXDALOp(AsyncRawReadDAL, AsyncRawDAL):
     """扩展数据访问操作类."""
 
 
 class AsyncBaseDAL(AsyncReadDAL[AsyncSQLATableT, DTOModelT], AsyncWriteDAL[AsyncSQLATableT, DTOModelT, CUModelT]):
-    """基础数据访问层.
-
-    .. deprecated:: 0.3.0
-        V1 DAL 将在 1.0 移除, 请迁移至 ``AsyncBaseDALV2``.
-    """
-
-    def __init_subclass__(cls, **kwargs: Any) -> None:
-        super().__init_subclass__(**kwargs)
-        warnings.warn(
-            f"{cls.__name__} 继承了 V1 AsyncBaseDAL, 建议迁移至 AsyncBaseDALV2",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+    """基础数据访问层."""
 
 
 class ReadOnlyAsyncBaseDAL(AsyncReadDAL[AsyncSQLATableT, ReadOnlyDTOModelT]):

{lush_sqlalchemyx-0.3.1 → 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.1 → lush_sqlalchemyx-0.4.0}/src/lush_sqlalchemyx/base/dal/_pagination.py

@@ -42,7 +42,7 @@ def build_offset_stmt(
     if order_by is not None:
         stmt = stmt.order_by(order_by)
     else:
-        stmt = stmt.order_by(table.id)  # pyright: ignore[reportAttributeAccessIssue]
+        stmt = stmt.order_by(table.id)
     return stmt.offset(p.skip).limit(p.limit)
 
 
@@ -55,7 +55,7 @@ def build_cursor_stmt(
     使用 id > cursor_value 的 keyset 分页方式.
     """
     p = pagination or CursorPagination()
-    id_col = table.id  # pyright: ignore[reportAttributeAccessIssue]
+    id_col = table.id
     stmt = sa.select(table).order_by(id_col)
 
     if p.cursor is not None: