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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "lush-sqlalchemyx"
-version = "0.3.0"
+version = "0.3.2"
 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
@@ -304,3 +301,8 @@ reportUnknownArgumentType = false
 
 [[tool.basedpyright.executionEnvironments]]
 root = "src"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "examples"
+# examples 作为下游类型检查 SSOT, 仅继承全局设置, 不做额外放宽.
+# 如果此处报错, 说明库的类型变更破坏了合法下游用法.

{lush_sqlalchemyx-0.3.0 → lush_sqlalchemyx-0.3.2}/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,
@@ -68,10 +58,6 @@ from ._common import (
 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 +65,6 @@ from ._pagination import (
     make_cursor_result,
     make_page_result,
 )
-from ._params import SQLAExtra
 from ._repository import AsyncSQLAlchemyRepository, SyncSQLAlchemyRepository
 
 # --- sync ---
@@ -100,7 +85,6 @@ from ._sync import (
     sync_temp_set_lock_wait_timeout,
     sync_with_retry,
 )
-from ._sync_v2 import SyncBaseDALV2, SyncReadDALV2, SyncWriteDALV2
 
 __all__ = (
     # common
@@ -165,30 +149,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.0 → lush_sqlalchemyx-0.3.2}/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
@@ -121,7 +122,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):
@@ -315,7 +317,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]
@@ -425,15 +431,15 @@ class AsyncReadDAL(AsyncRawReadDAL, Generic[AsyncSQLATableT, DTOModelT]):
         return entity is not None
 
     @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]
@@ -448,29 +454,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]
@@ -485,25 +481,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:
@@ -517,16 +503,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,
@@ -563,7 +539,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]
@@ -643,7 +624,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,
@@ -677,19 +658,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,
@@ -756,30 +725,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,
@@ -815,11 +760,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:
@@ -844,24 +789,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,
@@ -875,15 +809,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,
@@ -934,45 +868,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.0 → lush_sqlalchemyx-0.3.2}/src/lush_sqlalchemyx/base/dal/_common.py

@@ -21,7 +21,7 @@ from lush_dal_protocol.dto import DTOModelT as DTOModelT  # noqa: PLC0414
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import event as sa_event
 from sqlalchemy.exc import OperationalError as SQLAlchemyOperationalError
-from sqlalchemy.orm import DeclarativeBase, Mapped, ORMExecuteState, mapped_column, with_loader_criteria
+from sqlalchemy.orm import Mapped, ORMExecuteState, mapped_column, with_loader_criteria
 from sqlalchemy.orm import Session as SyncSession
 
 READONLY_SESSION_FLAG: Final[str] = "__lush_sqlalchemyx__readonly_session__"
@@ -139,7 +139,10 @@ DEFAULT_RETRY_CONFIG = RetryConfig(max_attempts=3, initial_delay=0.1, max_delay=
 # Pydantic CU / DTO models
 # ---------------------------------------------------------------------------
 
-SQLATableT = TypeVar("SQLATableT", bound=DeclarativeBase)
+# 隐含约束: SQLATableT 应为 SQLAlchemy DeclarativeBase 子类 (含 Flask-SQLAlchemy db.Model).
+# 不设 bound 是因为 Flask-SQLAlchemy 的 db.Model 运行时继承 DeclarativeBase,
+# 但静态类型系统看不到该链路, bound 会误拦合法下游.
+SQLATableT = TypeVar("SQLATableT")
 
 
 class BaseCU(_ProtocolBaseCU[SQLATableT]):

{lush_sqlalchemyx-0.3.0 → lush_sqlalchemyx-0.3.2}/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:

{lush_sqlalchemyx-0.3.0 → lush_sqlalchemyx-0.3.2}/src/lush_sqlalchemyx/base/dal/_repository.py

@@ -1,15 +1,21 @@
 """SQLAlchemy 具体 Repository 实现.
 
-提供高层声明式 CRUD 接口, 内部委托给 DAL V2.
+提供高层声明式 CRUD 接口, 内部委托给 DAL.
 """
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Generator, Iterable
 from contextlib import contextmanager
-from typing import Any, ClassVar, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
 
 import sqlalchemy as sa
+
+if TYPE_CHECKING:
+    from contextlib import AbstractAsyncContextManager
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+    from sqlalchemy.orm import Session
 from lush_dal_protocol.params.pagination import CursorPagination, CursorResult, OffsetPagination, PageResult
 from lush_dal_protocol.repository import AbstractAsyncRepository, AbstractSyncRepository
 
@@ -31,15 +37,21 @@ class SyncSQLAlchemyRepository(
         _session_factory: 返回 Session 的工厂函数
     """
 
-    _Table: ClassVar[type]
-    _DTO: ClassVar[type]
-    _session_factory: ClassVar[Callable[[], Any]]
+    _Table: ClassVar[type[TableT]]  # pyright: ignore[reportGeneralTypeIssues] — ClassVar + TypeVar 是 pyright 已知限制
+    _DTO: ClassVar[type[DTOModelT]]  # pyright: ignore[reportGeneralTypeIssues]
+    _session_factory: ClassVar[Callable[[], Session]]
 
     @classmethod
-    @contextmanager
-    def _get_session(cls) -> Any:
-        session = cls._session_factory()  # pyright: ignore[reportAttributeAccessIssue]
+    def _make_session(cls) -> Session:
+        """创建并配置一个新的 Session."""
+        session = cls._session_factory()  # pyright: ignore[reportAttributeAccessIssue] — pyright generic classmethod limitation
         session.expire_on_commit = False
+        return session
+
+    @classmethod
+    @contextmanager
+    def _get_session(cls) -> Generator[Session, None, None]:
+        session = cls._make_session()
         try:
             yield session
             session.commit()
@@ -150,10 +162,10 @@ class SyncSQLAlchemyRepository(
         if not pk_list:
             return 0
         with cls._get_session() as session:
-            id_col = cls._Table.id  # pyright: ignore[reportAttributeAccessIssue]
+            id_col: sa.Column[int] = cast("sa.Column[int]", cls._Table.id)  # pyright: ignore[reportAttributeAccessIssue] — SA 列描述符对 pyright 不可见  # SA 列描述符对 pyright 不可见
             stmt = sa.update(cls._Table).where(id_col.in_(pk_list)).values(**data)
-            result = session.execute(stmt)
-            return result.rowcount  # pyright: ignore[reportReturnType]
+            result = cast("sa.CursorResult[Any]", session.execute(stmt))  # SA stubs 返回 Result, 但运行时为 CursorResult
+            return result.rowcount
 
     @classmethod
     def bulk_delete(cls, pks: Iterable[int]) -> int:
@@ -162,10 +174,10 @@ class SyncSQLAlchemyRepository(
         if not pk_list:
             return 0
         with cls._get_session() as session:
-            id_col = cls._Table.id  # pyright: ignore[reportAttributeAccessIssue]
+            id_col: sa.Column[int] = cast("sa.Column[int]", cls._Table.id)  # pyright: ignore[reportAttributeAccessIssue] — SA 列描述符对 pyright 不可见
             stmt = sa.delete(cls._Table).where(id_col.in_(pk_list))
-            result = session.execute(stmt)
-            return result.rowcount  # pyright: ignore[reportReturnType]
+            result = cast("sa.CursorResult[Any]", session.execute(stmt))
+            return result.rowcount
 
 
 class AsyncSQLAlchemyRepository(
@@ -180,9 +192,9 @@ class AsyncSQLAlchemyRepository(
         _session_factory: 返回 async context manager 的工厂
     """
 
-    _Table: ClassVar[type]
-    _DTO: ClassVar[type]
-    _session_factory: ClassVar[Callable[..., Any]]
+    _Table: ClassVar[type[TableT]]  # pyright: ignore[reportGeneralTypeIssues]
+    _DTO: ClassVar[type[DTOModelT]]  # pyright: ignore[reportGeneralTypeIssues]
+    _session_factory: ClassVar[Callable[..., AbstractAsyncContextManager[AsyncSession]]]
 
     @classmethod
     async def get(cls, pk: int) -> TableT | None:
@@ -291,11 +303,11 @@ class AsyncSQLAlchemyRepository(
         if not pk_list:
             return 0
         async with cls._session_factory() as session:
-            id_col = cls._Table.id  # pyright: ignore[reportAttributeAccessIssue]
+            id_col: sa.Column[int] = cast("sa.Column[int]", cls._Table.id)  # pyright: ignore[reportAttributeAccessIssue] — SA 列描述符对 pyright 不可见
             stmt = sa.update(cls._Table).where(id_col.in_(pk_list)).values(**data)
-            result = await session.execute(stmt)
+            result = cast("sa.CursorResult[Any]", await session.execute(stmt))
             await session.commit()
-            return result.rowcount  # pyright: ignore[reportReturnType]
+            return result.rowcount
 
     @classmethod
     async def bulk_delete(cls, pks: Iterable[int]) -> int:
@@ -304,8 +316,8 @@ class AsyncSQLAlchemyRepository(
         if not pk_list:
             return 0
         async with cls._session_factory() as session:
-            id_col = cls._Table.id  # pyright: ignore[reportAttributeAccessIssue]
+            id_col: sa.Column[int] = cast("sa.Column[int]", cls._Table.id)  # pyright: ignore[reportAttributeAccessIssue] — SA 列描述符对 pyright 不可见
             stmt = sa.delete(cls._Table).where(id_col.in_(pk_list))
-            result = await session.execute(stmt)
+            result = cast("sa.CursorResult[Any]", await session.execute(stmt))
             await session.commit()
-            return result.rowcount  # pyright: ignore[reportReturnType]
+            return result.rowcount