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

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

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

{lush_sqlalchemyx-0.2.1 → lush_sqlalchemyx-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lush-sqlalchemyx"
-version = "0.2.1"
+version = "0.3.1"
 description = "SQLAlchemy helpers (DAL) and async MySQL managers, with some web frameworks integrations"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -47,6 +47,8 @@ dev = [
     "sqlalchemy[asyncio]>=2.0.43",
     "flask-sqlalchemy>=3.1.1",
     "flask>=3.0.0",
+    "pytest-benchmark>=5.2.3",
+    "pymysql>=1.1.2",
 ]
 
 [tool.pytest.ini_options]
@@ -147,6 +149,9 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
+"**/dal/_*_v2.py" = [
+    "ARG003",  # extra 参数是 ABC 合规所必需但在部分方法中未使用
+]
 "tests/**/*.py" = [
     # === 测试代码质量 ===
     "B011",    # assert False应改为raise AssertionError
@@ -249,6 +254,7 @@ reportAny = "none"
 reportExplicitAny = "none"
 reportConstantRedefinition = "none"
 reportUnnecessaryComparison = "none"
+reportImplicitOverride = false
 
 [[tool.basedpyright.executionEnvironments]]
 root = "tests"
@@ -277,10 +283,29 @@ reportMissingTypeArgument = false
 reportOptionalMemberAccess = false
 reportAttributeAccessIssue = "none"
 reportGeneralTypeIssues = false
+reportAssignmentType = false
 reportOperatorIssue = false
 reportIndexIssue = false
 reportInvalidTypeArguments = "none"
+reportUnknownLambdaType = false
+reportImplicitOverride = false
+reportUnusedClass = false
+
 
+[[tool.basedpyright.executionEnvironments]]
+root = "src/lush_sqlalchemyx/integrations"
+reportAttributeAccessIssue = "none"
+reportAssignmentType = false
+reportImportCycles = false
+reportUnknownVariableType = false
+reportUnknownParameterType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
 
 [[tool.basedpyright.executionEnvironments]]
 root = "src"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "examples"
+# examples 作为下游类型检查 SSOT, 仅继承全局设置, 不做额外放宽.
+# 如果此处报错, 说明库的类型变更破坏了合法下游用法.

{lush_sqlalchemyx-0.2.1 → lush_sqlalchemyx-0.3.1}/src/lush_sqlalchemyx/_compat.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 _HAS_ASYNC: bool
 try:
-    from sqlalchemy.ext.asyncio import AsyncSession as _AsyncSession  # noqa: F401
+    from sqlalchemy.ext.asyncio import AsyncSession as _AsyncSession  # noqa: F401  # pyright: ignore[reportUnusedImport]
 
     _HAS_ASYNC = True
 except ImportError:  # pragma: no cover

{lush_sqlalchemyx-0.2.1 → lush_sqlalchemyx-0.3.1}/src/lush_sqlalchemyx/base/dal/__init__.py

@@ -4,14 +4,22 @@
 """
 
 # --- shared (sync/async agnostic) ---
-# --- lush-dal-protocol protocols (ORM 无关的抽象层) ---
+# --- lush-dal-protocol ABCs (ORM 无关的抽象层) ---
 from lush_dal_protocol import (
-    AsyncBaseDALProtocol,
-    AsyncReadDALProtocol,
-    AsyncWriteDALProtocol,
-    SyncBaseDALProtocol,
-    SyncReadDALProtocol,
-    SyncWriteDALProtocol,
+    AbstractAsyncAdvancedWriteDAL,
+    AbstractAsyncBaseDAL,
+    AbstractAsyncBatchFieldDAL,
+    AbstractAsyncLockDAL,
+    AbstractAsyncRawSQLDAL,
+    AbstractAsyncReadDAL,
+    AbstractAsyncWriteDAL,
+    AbstractSyncAdvancedWriteDAL,
+    AbstractSyncBaseDAL,
+    AbstractSyncBatchFieldDAL,
+    AbstractSyncLockDAL,
+    AbstractSyncRawSQLDAL,
+    AbstractSyncReadDAL,
+    AbstractSyncWriteDAL,
 )
 
 # --- async (requires sqlalchemy[asyncio]) ---
@@ -32,6 +40,9 @@ 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,
@@ -39,7 +50,6 @@ from ._common import (
     READONLY_SESSION_FLAG,
     BaseCU,
     BaseDTO,
-    BaseModelT,
     CUModelT,
     DBRetryableError,
     DTOModelT,
@@ -50,16 +60,27 @@ from ._common import (
     SQLATableT,
     StdBaseCU,
     StdBaseDTO,
-    T,
-    V,
-    _ensure_strict_fields,
     escape_like,
     filtered_in_sql_values,
 )
 
 # Event listener references — accessed by tests via getattr(module, name).
-from ._common import __prevent_readonly_write as __prevent_readonly_write
-from ._common import __receive_before_flush as __receive_before_flush
+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,
+    encode_cursor,
+    make_cursor_result,
+    make_page_result,
+)
+from ._params import SQLAExtra
+from ._repository import AsyncSQLAlchemyRepository, SyncSQLAlchemyRepository
 
 # --- sync ---
 from ._sync import (
@@ -79,6 +100,7 @@ from ._sync import (
     sync_temp_set_lock_wait_timeout,
     sync_with_retry,
 )
+from ._sync_v2 import SyncBaseDALV2, SyncReadDALV2, SyncWriteDALV2
 
 __all__ = (
     # common
@@ -88,7 +110,6 @@ __all__ = (
     "READONLY_SESSION_FLAG",
     "BaseCU",
     "BaseDTO",
-    "BaseModelT",
     "CUModelT",
     "DBRetryableError",
     "DTOModelT",
@@ -99,9 +120,6 @@ __all__ = (
     "SoftDeleteTableMixin",
     "StdBaseCU",
     "StdBaseDTO",
-    "T",
-    "V",
-    "_ensure_strict_fields",
     "escape_like",
     "filtered_in_sql_values",
     # async
@@ -136,11 +154,41 @@ __all__ = (
     "SyncXDALOp",
     "sync_temp_set_lock_wait_timeout",
     "sync_with_retry",
-    # lush-dal-protocol protocols
-    "AsyncBaseDALProtocol",
-    "AsyncReadDALProtocol",
-    "AsyncWriteDALProtocol",
-    "SyncBaseDALProtocol",
-    "SyncReadDALProtocol",
-    "SyncWriteDALProtocol",
+    # pagination
+    "CursorPagination",
+    "CursorResult",
+    "OffsetPagination",
+    "PageResult",
+    "build_cursor_stmt",
+    "build_offset_stmt",
+    "decode_cursor",
+    "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.2.1 → lush_sqlalchemyx-0.3.1}/src/lush_sqlalchemyx/base/dal/_async.py

@@ -9,7 +9,8 @@ from __future__ import annotations
 import asyncio
 import datetime
 import logging
-from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+import warnings
+from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
 from contextlib import asynccontextmanager, suppress
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, ParamSpec, TypeVar, cast
 
@@ -101,7 +102,7 @@ def async_with_retry(
 async def async_temp_set_lock_wait_timeout(
     session: AsyncSession,
     timeout_seconds: int | None,
-) -> AsyncIterator[None]:
+) -> AsyncGenerator[None, None]:
     """临时设置锁等待超时时间的上下文管理器"""
     if timeout_seconds is None:
         yield
@@ -120,7 +121,8 @@ async def async_temp_set_lock_wait_timeout(
 # Async Table bases
 # ---------------------------------------------------------------------------
 
-AsyncSQLATableT = TypeVar("AsyncSQLATableT", bound="AsyncSqlATableBase")
+# 隐含约束: AsyncSQLATableT 应为 AsyncSqlATableBase (AsyncAttrs + DeclarativeBase) 子类.
+AsyncSQLATableT = TypeVar("AsyncSQLATableT")
 
 
 class AsyncSqlATableBase(AsyncAttrs, DeclarativeBase):
@@ -140,10 +142,23 @@ class ReadOnlyBasicAsyncBaseTable(AsyncSqlATableBase, ReadOnlyMixin):
 
 
 class StdAsyncBaseTable(BasicAsyncBaseTable, SoftDeleteTableMixin):
-    """标准异步表类:符合新规范的表应该使用这个."""
+    """标准异步表类: 包含 id/时间戳/操作人/软删除等标准字段.
+
+    .. deprecated::
+        此类预设了特定业务字段, 下游应自行继承 ``BasicAsyncBaseTable`` 定义所需字段.
+    """
 
     __abstract__ = True
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not cls.__dict__.get("__abstract__", False):
+            warnings.warn(
+                f"{cls.__name__} 继承了已废弃的 StdAsyncBaseTable, 请改为直接继承 BasicAsyncBaseTable 并自行定义所需字段",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     id: Mapped[int] = mapped_column(sa.Integer, primary_key=True, autoincrement=True)
 
     create_datetime: Mapped[datetime.datetime] = mapped_column(
@@ -177,10 +192,23 @@ class StdAsyncBaseTable(BasicAsyncBaseTable, SoftDeleteTableMixin):
 
 
 class StdReadOnlyBasicAsyncBaseTable(ReadOnlyBasicAsyncBaseTable):
-    """标准只读表基类."""
+    """标准只读异步表基类: 包含 id/时间戳/操作人等标准字段.
+
+    .. deprecated::
+        此类预设了特定业务字段, 下游应自行继承 ``ReadOnlyBasicAsyncBaseTable`` 定义所需字段.
+    """
 
     __abstract__ = True
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not cls.__dict__.get("__abstract__", False):
+            warnings.warn(
+                f"{cls.__name__} 继承了已废弃的 StdReadOnlyBasicAsyncBaseTable, 请改为直接继承 ReadOnlyBasicAsyncBaseTable 并自行定义所需字段",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     id: Mapped[int] = mapped_column(sa.Integer, primary_key=True, autoincrement=True)
 
     create_datetime: Mapped[datetime.datetime] = mapped_column(
@@ -252,7 +280,7 @@ class AsyncRawReadDAL:
         where_clauses: list[ColumnExpressionArgument[bool]] | None = None,
         with_deleted: bool = False,
         batch_size: int = 500,
-    ) -> AsyncIterator[AsyncSQLATableT]:
+    ) -> AsyncGenerator[AsyncSQLATableT, None]:
         if not hasattr(table_class, "id") or not isinstance(getattr(table_class, "id", None), InstrumentedAttribute):
             raise ValueError(f"表 {table_class.__name__} 必须有 id 字段才能使用迭代方法")
 
@@ -398,15 +426,15 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
         return entity is not None
 
     @classmethod
-    async def get_by_id_for_update(
+    async def _get_by_id_for_update_core(
         cls,
         session: AsyncSession,
         entity_id: int,
         *,
-        lock_wait_timeout: int | None = None,
+        timeout: int | None = None,
     ) -> AsyncSQLATableT | None:
         try:
-            async with async_temp_set_lock_wait_timeout(session, lock_wait_timeout):
+            async with async_temp_set_lock_wait_timeout(session, timeout):
                 stmt = (
                     sa.select(cls._Table)
                     .where(cls._Table.id == entity_id)  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownArgumentType]
@@ -421,19 +449,29 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
             raise
 
     @classmethod
-    async def batch_get_for_update(
+    async def get_by_id_for_update(
         cls,
         session: AsyncSession,
-        entity_ids: Iterable[int],
+        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(
+        cls,
+        session: AsyncSession,
+        entity_ids: Iterable[int],
+        *,
+        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, lock_wait_timeout):
+            async with async_temp_set_lock_wait_timeout(session, timeout):
                 stmt = (
                     sa.select(cls._Table)
                     .where(cls._Table.id.in_(filtered_ids))  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownArgumentType]
@@ -448,15 +486,25 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
             raise
 
     @classmethod
-    async def get_one_for_update(
+    async def batch_get_for_update(
         cls,
         session: AsyncSession,
+        entity_ids: Iterable[int],
         *,
-        where_clauses: list[ColumnExpressionArgument[bool]],
         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(
+        cls,
+        session: AsyncSession,
+        *,
+        where_clauses: list[ColumnExpressionArgument[bool]],
+        timeout: int | None = None,
     ) -> AsyncSQLATableT | None:
         try:
-            async with async_temp_set_lock_wait_timeout(session, lock_wait_timeout):
+            async with async_temp_set_lock_wait_timeout(session, timeout):
                 stmt = sa.select(cls._Table).with_for_update()
 
                 for clause in where_clauses:
@@ -470,6 +518,16 @@ 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,
@@ -478,7 +536,7 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
         where_clauses: list[ColumnExpressionArgument[bool]] | None = None,
         with_deleted: bool = False,
         batch_size: int = 500,
-    ) -> AsyncIterator[DTOModelT]:
+    ) -> AsyncGenerator[DTOModelT, None]:
         async for entity in cls._iter_records(
             session,
             cls._Table,
@@ -522,7 +580,7 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
     ) -> AsyncSQLATableT:
         if session.info.get(READONLY_SESSION_FLAG):
             raise TypeError("当前会话被标记为只读, 不允许执行写入操作")
-        entity = cu.to_sqla_model()
+        entity = cu.to_orm_model()
         session.add(entity)
         await session.flush()
         if need_refresh:
@@ -568,10 +626,10 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         cls,
         session: AsyncSession,
         entity_id: int,
-        vo: CUModelT,
+        cu: CUModelT,
         need_refresh: bool = True,
     ) -> DTOModelT | None:
-        entity = await cls.update_only_set_by_id(session, entity_id, vo, need_refresh)
+        entity = await cls.update_only_set_by_id(session, entity_id, cu, need_refresh)
         if entity:
             return cls._DTO.model_validate(entity)
         return None
@@ -586,7 +644,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(
+    async def _update_full_by_id_core(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -620,7 +678,19 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         return entity
 
     @classmethod
-    async def update_partial_by_id(
+    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(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -687,6 +757,30 @@ 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,
@@ -711,7 +805,7 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
         where_clauses: list[ColumnExpressionArgument[bool]] | None = None,
         with_deleted: bool = False,
         batch_size: int = 500,
-    ) -> AsyncIterator[AsyncSQLATableT]:
+    ) -> AsyncGenerator[AsyncSQLATableT, None]:
         async for entity in cls._iter_records(
             session,
             cls._Table,
@@ -722,11 +816,11 @@ class AsyncWriteDAL(AsyncRawDAL, AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOMo
             yield entity
 
     @classmethod
-    async def batch_update_by_conditions(
+    async def _batch_update_by_conditions_core(
         cls,
         session: AsyncSession,
         *,
-        whereclause: list[ColumnExpressionArgument[bool]],
+        conditions: list[ColumnExpressionArgument[bool]],
         update_data: dict[InstrumentedAttribute[Any], Any] | dict[sa.Column[Any], Any],
         updater_id: int | None = None,
     ) -> int:
@@ -751,13 +845,24 @@ 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(*whereclause).values(**final_update_data)
+        stmt = sa.update(cls._Table).where(*conditions).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,
@@ -771,15 +876,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(
+        return await cls._batch_update_by_conditions_core(
             session,
-            whereclause=[_id_column.in_(filtered_ids)],  # pyright: ignore[reportUnknownMemberType]
+            conditions=[_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(
+    async def _update_only_set_with_optimistic_lock_core(
         cls,
         session: AsyncSession,
         entity_id: int,
@@ -830,13 +935,45 @@ 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]):