lush-dal-protocol 0.1.0__py3-none-any.whl

lush_dal_protocol/__init__.py

@@ -0,0 +1,40 @@
+"""lush-dal-protocol — ORM 无关的数据访问层协议抽象.
+
+本包仅包含纯 Protocol / 接口声明, 不依赖任何具体 ORM.
+下游适配包 (如 lush-sqlalchemyx) 负责实现这些协议.
+"""
+
+from .dto import BaseCU, BaseDTO, CUModelT, DTOModelT, StdBaseCU, StdBaseDTO
+from .errors import DBRetryableError
+from .protocols import (
+    AsyncBaseDALProtocol,
+    AsyncReadDALProtocol,
+    AsyncWriteDALProtocol,
+    SyncBaseDALProtocol,
+    SyncReadDALProtocol,
+    SyncWriteDALProtocol,
+)
+from .protocols.api_contracts import AsyncDALConformanceTests, SyncDALConformanceTests
+from .utils import DEFAULT_RETRY_CONFIG, RetryConfig, escape_like, filtered_in_sql_values
+
+__all__ = [
+    "AsyncDALConformanceTests",
+    "AsyncBaseDALProtocol",
+    "AsyncReadDALProtocol",
+    "AsyncWriteDALProtocol",
+    "BaseCU",
+    "BaseDTO",
+    "CUModelT",
+    "DBRetryableError",
+    "DEFAULT_RETRY_CONFIG",
+    "DTOModelT",
+    "RetryConfig",
+    "StdBaseCU",
+    "StdBaseDTO",
+    "SyncBaseDALProtocol",
+    "SyncDALConformanceTests",
+    "SyncReadDALProtocol",
+    "SyncWriteDALProtocol",
+    "escape_like",
+    "filtered_in_sql_values",
+]

lush_dal_protocol/dto.py

@@ -0,0 +1,75 @@
+"""数据传输对象 (DTO) 与创建/更新 (CU) 模型的 ORM 无关基类.
+
+这些基类只依赖 Pydantic, 不绑定任何具体 ORM.
+下游适配包可以通过子类化并绑定 ``_Table`` 来关联具体 ORM 模型.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any, ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+OrmModelT = TypeVar("OrmModelT")
+
+
+class BaseCU(BaseModel, Generic[OrmModelT]):
+    """创建/更新模型基类.
+
+    子类需设置 ``_Table`` 类变量指向具体 ORM 模型类,
+    并实现 ``to_orm_model()`` 返回对应的 ORM 实例.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    _Table: ClassVar[type]  # pyright: ignore[reportGeneralTypeIssues]
+
+    def to_orm_model(self) -> OrmModelT:
+        """将 CU 模型转换为 ORM 模型实例.
+
+        默认实现使用 ``model_dump`` 生成字典后传入 ``_Table`` 构造函数.
+        子类可覆盖此方法以适配不同 ORM 的构造方式.
+        """
+        model_data = self.model_dump(exclude_unset=True, exclude={"id"})
+        return self._Table(**model_data)
+
+
+CUModelT = TypeVar("CUModelT", bound=BaseCU[Any])
+
+
+class BaseDTO(BaseModel, Generic[CUModelT]):
+    """数据传输对象基类.
+
+    子类需设置 ``_CU`` 类变量指向对应的 CU 类.
+    """
+
+    model_config = ConfigDict(from_attributes=True)
+
+    _CU: ClassVar[type[CUModelT]]  # pyright: ignore[reportGeneralTypeIssues]
+
+    def to_cu(self) -> CUModelT:
+        """将 DTO 转换为对应的 CU 模型."""
+        return self._CU.model_validate(self)
+
+
+DTOModelT = TypeVar("DTOModelT", bound=BaseDTO[Any] | BaseModel)
+
+
+class StdBaseCU(BaseCU[OrmModelT]):
+    """标准 CU 基类: 包含创建人/修改人等标准字段."""
+
+    create_operator_id: int = 0
+    update_operator_id: int | None = None
+
+
+class StdBaseDTO(BaseDTO[CUModelT]):
+    """标准 DTO 基类: 包含 id、时间戳、操作人等标准字段."""
+
+    id: int = Field(..., description="ID")
+    create_datetime: datetime.datetime = Field(..., description="创建时间")
+    create_operator_id: int = Field(..., description="创建人")
+    update_datetime: datetime.datetime | None = Field(None, description="修改时间")
+    update_operator_id: int | None = Field(None, description="修改人")
+
+    model_config = ConfigDict(from_attributes=True)

lush_dal_protocol/errors.py

@@ -0,0 +1,30 @@
+"""DAL 层通用异常定义."""
+
+from __future__ import annotations
+
+from typing import Final
+
+OPTIMISTIC_LOCK_ERROR_MSG_TRAIT: Final[str] = "乐观锁更新失败"
+PESSIMISTIC_LOCK_ERROR_MSG_TRAIT: Final[str] = "悲观锁获取失败"
+
+
+class DBRetryableError(Exception):
+    """数据库可重试异常.
+
+    表示一个由于并发冲突导致的、可以通过重试解决的数据库操作异常.
+    这类异常不是错误, 而是正常的并发控制机制, 应该被捕获并重试.
+    """
+
+    def __init__(self, message: str = "数据库操作冲突,需要重试") -> None:
+        super().__init__(message)
+        self.message = message
+
+    @property
+    def is_pessimistic_lock_retry_error(self) -> bool:
+        """是否为悲观锁重试异常."""
+        return PESSIMISTIC_LOCK_ERROR_MSG_TRAIT in self.message
+
+    @property
+    def is_optimistic_lock_retry_error(self) -> bool:
+        """是否为乐观锁重试异常."""
+        return OPTIMISTIC_LOCK_ERROR_MSG_TRAIT in self.message

lush_dal_protocol/protocols/__init__.py

@@ -0,0 +1,22 @@
+"""协议定义与一致性验证子包."""
+
+from .api_contracts import AsyncDALConformanceTests, SyncDALConformanceTests
+from .dal import (
+    AsyncBaseDALProtocol,
+    AsyncReadDALProtocol,
+    AsyncWriteDALProtocol,
+    SyncBaseDALProtocol,
+    SyncReadDALProtocol,
+    SyncWriteDALProtocol,
+)
+
+__all__ = [
+    "AsyncBaseDALProtocol",
+    "AsyncDALConformanceTests",
+    "AsyncReadDALProtocol",
+    "AsyncWriteDALProtocol",
+    "SyncBaseDALProtocol",
+    "SyncDALConformanceTests",
+    "SyncReadDALProtocol",
+    "SyncWriteDALProtocol",
+]

lush_dal_protocol/protocols/api_contracts.py

@@ -0,0 +1,314 @@
+"""DAL 一致性验证测试套件.
+
+提供可复用的测试 mixin 类, 下游 ORM 适配包可以继承这些测试类
+并注入具体的 session、DAL、CU、DTO 来验证实现是否符合协议约定.
+
+使用方式::
+
+    from lush_dal_protocol.protocols.api_contracts import SyncDALConformanceTests
+
+    class TestMySQLAlchemyDAL(SyncDALConformanceTests):
+        @pytest.fixture
+        def dal_class(self):
+            return MyConcreteDAL
+
+        @pytest.fixture
+        def session(self):
+            # 返回你的 ORM session
+            ...
+
+        @pytest.fixture
+        def sample_cu(self):
+            # 返回一个有效的 CU 实例
+            return MyCU(name="test")
+
+        @pytest.fixture
+        def entity_id_field(self):
+            return "id"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SyncDALConformanceTests:
+    """同步 DAL 一致性验证测试套件.
+
+    下游实现继承此类并通过 pytest fixture 注入:
+    - ``dal_class``: DAL 类 (应实现 SyncBaseDALProtocol)
+    - ``session``: 数据库会话
+    - ``sample_cu``: 有效的 CU 实例
+    - ``entity_id_field``: 实体主键字段名, 默认 "id"
+    """
+
+    def _get_entity_id(self, entity: Any, field: str = "id") -> int:
+        return getattr(entity, field)
+
+    def test_create_returns_entity(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """create() 应返回具有有效 ID 的 ORM 实体."""
+        entity = dal_class.create(session, sample_cu)
+        assert entity is not None
+        assert hasattr(entity, "id")
+
+    def test_create_no_refresh(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """create(need_refresh=False) 应返回实体但不执行 refresh."""
+        entity = dal_class.create(session, sample_cu, need_refresh=False)
+        assert entity is not None
+
+    def test_get_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_by_id() 对已存在的实体应返回非 None."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        found = dal_class.get_by_id(session, eid)
+        assert found is not None
+
+    def test_get_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """get_by_id() 对不存在的 ID 应返回 None."""
+        result = dal_class.get_by_id(session, 999999)
+        assert result is None
+
+    def test_ret_dto_after_get_by_id(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """ret_dto_after_get_by_id() 应返回 DTO 对象."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        dto = dal_class.ret_dto_after_get_by_id(session, eid)
+        assert dto is not None
+
+    def test_ret_dto_after_get_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """ret_dto_after_get_by_id() 对不存在的 ID 应返回 None."""
+        result = dal_class.ret_dto_after_get_by_id(session, 999999)
+        assert result is None
+
+    def test_get_all_default_pagination(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_all() 默认参数应返回列表."""
+        dal_class.create(session, sample_cu)
+        result = dal_class.get_all(session)
+        assert isinstance(result, list)
+        assert len(result) >= 1
+
+    def test_get_all_with_pagination(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_all(skip, limit) 应正确分页."""
+        dal_class.create(session, sample_cu)
+        dal_class.create(session, sample_cu)
+        page1 = dal_class.get_all(session, skip=0, limit=1)
+        assert len(page1) == 1
+
+    def test_count_returns_int(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """count() 应返回非负整数."""
+        initial = dal_class.count(session)
+        assert isinstance(initial, int)
+        assert initial >= 0
+
+        dal_class.create(session, sample_cu)
+        after = dal_class.count(session)
+        assert after == initial + 1
+
+    def test_exists_true_for_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """exists() 对已存在的 ID 应返回 True."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        assert dal_class.exists(session, eid) is True
+
+    def test_exists_false_for_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """exists() 对不存在的 ID 应返回 False."""
+        assert dal_class.exists(session, 999999) is False
+
+    def test_batch_get_id__entity(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """batch_get_id__entity() 应返回 {id: entity} 字典."""
+        e1 = dal_class.create(session, sample_cu)
+        e2 = dal_class.create(session, sample_cu)
+        eid1, eid2 = self._get_entity_id(e1), self._get_entity_id(e2)
+
+        result = dal_class.batch_get_id__entity(session, [eid1, eid2, 999999])
+        assert eid1 in result
+        assert eid2 in result
+        assert 999999 not in result
+
+    def test_batch_get_id__dto(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """batch_get_id__dto() 应返回 {id: DTO} 字典."""
+        e1 = dal_class.create(session, sample_cu)
+        eid1 = self._get_entity_id(e1)
+
+        result = dal_class.batch_get_id__dto(session, [eid1])
+        assert eid1 in result
+
+    def test_ret_dto_after_create(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """ret_dto_after_create() 应返回 DTO 对象."""
+        dto = dal_class.ret_dto_after_create(session, sample_cu)
+        assert dto is not None
+
+    def test_update_only_set_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """update_only_set_by_id() 对已存在的实体应返回更新后的实体."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        updated = dal_class.update_only_set_by_id(session, eid, sample_cu)
+        assert updated is not None
+
+    def test_update_only_set_by_id_nonexistent(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """update_only_set_by_id() 对不存在的 ID 应返回 None."""
+        result = dal_class.update_only_set_by_id(session, 999999, sample_cu)
+        assert result is None
+
+    def test_delete_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """delete_by_id() 对已存在的实体应返回 True."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        assert dal_class.delete_by_id(session, eid) is True
+
+    def test_delete_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """delete_by_id() 对不存在的 ID 应返回 False."""
+        assert dal_class.delete_by_id(session, 999999) is False
+
+    def test_delete_then_get_returns_none(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """删除后再 get_by_id 应返回 None (验证软删除/物理删除生效)."""
+        entity = dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        dal_class.delete_by_id(session, eid)
+        session.expire_all()
+        result = dal_class.get_by_id(session, eid)
+        assert result is None
+
+    def test_iter_record_dtos_yields(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """iter_record_dtos() 应以迭代器方式返回 DTO."""
+        dal_class.create(session, sample_cu)
+        records = list(dal_class.iter_record_dtos(session, batch_size=10))
+        assert len(records) >= 1
+
+
+class AsyncDALConformanceTests:
+    """异步 DAL 一致性验证测试套件.
+
+    下游实现继承此类并通过 pytest fixture 注入:
+    - ``dal_class``: DAL 类 (应实现 AsyncBaseDALProtocol)
+    - ``session``: 异步数据库会话
+    - ``sample_cu``: 有效的 CU 实例
+    - ``entity_id_field``: 实体主键字段名, 默认 "id"
+    """
+
+    def _get_entity_id(self, entity: Any, field: str = "id") -> int:
+        return getattr(entity, field)
+
+    async def test_create_returns_entity(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """create() 应返回具有有效 ID 的 ORM 实体."""
+        entity = await dal_class.create(session, sample_cu)
+        assert entity is not None
+        assert hasattr(entity, "id")
+
+    async def test_create_no_refresh(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """create(need_refresh=False) 应返回实体但不执行 refresh."""
+        entity = await dal_class.create(session, sample_cu, need_refresh=False)
+        assert entity is not None
+
+    async def test_get_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_by_id() 对已存在的实体应返回非 None."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        found = await dal_class.get_by_id(session, eid)
+        assert found is not None
+
+    async def test_get_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """get_by_id() 对不存在的 ID 应返回 None."""
+        result = await dal_class.get_by_id(session, 999999)
+        assert result is None
+
+    async def test_ret_dto_after_get_by_id(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """ret_dto_after_get_by_id() 应返回 DTO 对象."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        dto = await dal_class.ret_dto_after_get_by_id(session, eid)
+        assert dto is not None
+
+    async def test_ret_dto_after_get_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """ret_dto_after_get_by_id() 对不存在的 ID 应返回 None."""
+        result = await dal_class.ret_dto_after_get_by_id(session, 999999)
+        assert result is None
+
+    async def test_get_all_default_pagination(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_all() 默认参数应返回列表."""
+        await dal_class.create(session, sample_cu)
+        result = await dal_class.get_all(session)
+        assert isinstance(result, list)
+        assert len(result) >= 1
+
+    async def test_get_all_with_pagination(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """get_all(skip, limit) 应正确分页."""
+        await dal_class.create(session, sample_cu)
+        await dal_class.create(session, sample_cu)
+        page1 = await dal_class.get_all(session, skip=0, limit=1)
+        assert len(page1) == 1
+
+    async def test_count_returns_int(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """count() 应返回非负整数."""
+        initial = await dal_class.count(session)
+        assert isinstance(initial, int)
+        await dal_class.create(session, sample_cu)
+        after = await dal_class.count(session)
+        assert after == initial + 1
+
+    async def test_exists_true_for_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """exists() 对已存在的 ID 应返回 True."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        assert await dal_class.exists(session, eid) is True
+
+    async def test_exists_false_for_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """exists() 对不存在的 ID 应返回 False."""
+        assert await dal_class.exists(session, 999999) is False
+
+    async def test_batch_get_id__entity(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """batch_get_id__entity() 应返回 {id: entity} 字典."""
+        e1 = await dal_class.create(session, sample_cu)
+        eid1 = self._get_entity_id(e1)
+        result = await dal_class.batch_get_id__entity(session, [eid1, 999999])
+        assert eid1 in result
+        assert 999999 not in result
+
+    async def test_batch_get_id__dto(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """batch_get_id__dto() 应返回 {id: DTO} 字典."""
+        e1 = await dal_class.create(session, sample_cu)
+        eid1 = self._get_entity_id(e1)
+        result = await dal_class.batch_get_id__dto(session, [eid1])
+        assert eid1 in result
+
+    async def test_ret_dto_after_create(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """ret_dto_after_create() 应返回 DTO 对象."""
+        dto = await dal_class.ret_dto_after_create(session, sample_cu)
+        assert dto is not None
+
+    async def test_update_only_set_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """update_only_set_by_id() 对已存在的实体应返回更新后的实体."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        updated = await dal_class.update_only_set_by_id(session, eid, sample_cu)
+        assert updated is not None
+
+    async def test_update_only_set_by_id_nonexistent(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """update_only_set_by_id() 对不存在的 ID 应返回 None."""
+        result = await dal_class.update_only_set_by_id(session, 999999, sample_cu)
+        assert result is None
+
+    async def test_delete_by_id_existing(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """delete_by_id() 对已存在的实体应返回 True."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        assert await dal_class.delete_by_id(session, eid) is True
+
+    async def test_delete_by_id_nonexistent(self, dal_class: Any, session: Any) -> None:
+        """delete_by_id() 对不存在的 ID 应返回 False."""
+        assert await dal_class.delete_by_id(session, 999999) is False
+
+    async def test_delete_then_get_returns_none(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """删除后再 get_by_id 应返回 None (验证软删除/物理删除生效)."""
+        entity = await dal_class.create(session, sample_cu)
+        eid = self._get_entity_id(entity)
+        await dal_class.delete_by_id(session, eid)
+        session.expire_all()
+        result = await dal_class.get_by_id(session, eid)
+        assert result is None
+
+    async def test_iter_record_dtos_yields(self, dal_class: Any, session: Any, sample_cu: Any) -> None:
+        """iter_record_dtos() 应以异步迭代器方式返回 DTO."""
+        await dal_class.create(session, sample_cu)
+        records = [dto async for dto in dal_class.iter_record_dtos(session, batch_size=10)]
+        assert len(records) >= 1

lush_dal_protocol/protocols/dal.py

@@ -0,0 +1,357 @@
+"""DAL 操作协议 (Protocol) 定义.
+
+定义了同步/异步两套 ReadDAL、WriteDAL、BaseDAL 的操作协议.
+下游 ORM 适配包应实现这些协议以保持一致的用户接口.
+
+注意: 这里的 Protocol 用 ``SessionT`` 和 ``EntityT`` 等泛型参数
+屏蔽了具体 ORM 的会话和实体类型.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterable, Iterator
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from ..dto import CUModelT, DTOModelT
+
+SessionT = TypeVar("SessionT", contravariant=True)
+EntityT = TypeVar("EntityT")
+
+
+@runtime_checkable
+class SyncReadDALProtocol(Protocol[SessionT, EntityT, DTOModelT]):
+    """同步只读 DAL 协议.
+
+    定义了下游实现必须提供的只读数据访问方法.
+    所有方法均为 classmethod, 接收显式 session 参数.
+    """
+
+    @classmethod
+    def get_by_id(cls, session: SessionT, entity_id: int) -> EntityT | None:
+        """根据主键 ID 获取单个 ORM 实体.
+
+        Args:
+            session: 数据库会话.
+            entity_id: 实体主键 ID.
+
+        Returns:
+            找到则返回 ORM 实体实例, 否则返回 ``None``.
+
+        行为约定:
+            - 应支持软删除过滤 (如果实体混入了软删除标记).
+            - 不应触发额外的 commit/flush.
+        """
+        ...
+
+    @classmethod
+    def get_all(cls, session: SessionT, skip: int = 0, limit: int = 100) -> list[DTOModelT]:
+        """分页获取实体列表, 以 DTO 形式返回.
+
+        Args:
+            session: 数据库会话.
+            skip: 跳过的记录数 (偏移量), 默认 0.
+            limit: 最大返回数量, 默认 100.
+
+        Returns:
+            DTO 对象列表, 可能为空.
+
+        行为约定:
+            - skip=0, limit=100 为默认值.
+            - 返回 DTO (而非 ORM 实体), 方便序列化.
+            - 应按主键升序或插入顺序排列.
+        """
+        ...
+
+    @classmethod
+    def count(cls, session: SessionT) -> int:
+        """统计实体总数.
+
+        Args:
+            session: 数据库会话.
+
+        Returns:
+            满足条件的记录数 (非负整数).
+
+        行为约定:
+            - 应排除软删除的记录.
+            - 无记录时返回 0 而非 None.
+        """
+        ...
+
+    @classmethod
+    def exists(cls, session: SessionT, entity_id: int) -> bool:
+        """判断指定 ID 的实体是否存在.
+
+        Args:
+            session: 数据库会话.
+            entity_id: 实体主键 ID.
+
+        Returns:
+            存在返回 ``True``, 否则 ``False``.
+
+        行为约定:
+            - 应排除软删除的记录.
+        """
+        ...
+
+    @classmethod
+    def ret_dto_after_get_by_id(cls, session: SessionT, entity_id: int, need_refresh: bool = True) -> DTOModelT | None:
+        """根据主键 ID 获取实体并转为 DTO 返回.
+
+        Args:
+            session: 数据库会话.
+            entity_id: 实体主键 ID.
+            need_refresh: 是否在返回前刷新实体 (从 DB 重新加载), 默认 True.
+
+        Returns:
+            找到则返回 DTO 对象, 否则返回 ``None``.
+
+        行为约定:
+            - need_refresh=True 时应确保返回的数据反映 DB 最新状态.
+            - 转换为 DTO 时应使用 ``_DTO.model_validate(entity, from_attributes=True)``.
+        """
+        ...
+
+    @classmethod
+    def batch_get_id__entity(cls, session: SessionT, entity_ids: Iterable[int]) -> dict[int, EntityT]:
+        """批量获取实体, 返回 {id: entity} 字典.
+
+        Args:
+            session: 数据库会话.
+            entity_ids: 主键 ID 可迭代对象.
+
+        Returns:
+            存在的实体映射, key 为 ID, value 为 ORM 实体.
+            不存在的 ID 不会出现在结果中.
+
+        行为约定:
+            - 应对 entity_ids 去重和过滤无效值 (None / 空字符串).
+            - 使用 SQL IN 查询, 避免 N+1.
+        """
+        ...
+
+    @classmethod
+    def batch_get_id__dto(cls, session: SessionT, entity_ids: Iterable[int]) -> dict[int, DTOModelT]:
+        """批量获取实体, 返回 {id: DTO} 字典.
+
+        Args:
+            session: 数据库会话.
+            entity_ids: 主键 ID 可迭代对象.
+
+        Returns:
+            存在的实体映射, key 为 ID, value 为 DTO 对象.
+
+        行为约定:
+            - 语义同 ``batch_get_id__entity``, 但值为 DTO.
+        """
+        ...
+
+    @classmethod
+    def iter_record_dtos(cls, session: SessionT, *, batch_size: int = 500) -> Iterator[DTOModelT]:
+        """以迭代器方式逐条返回全部记录的 DTO.
+
+        Args:
+            session: 数据库会话.
+            batch_size: 每批从数据库拉取的记录数, 默认 500.
+
+        Yields:
+            DTOModelT: 逐条的 DTO 对象.
+
+        行为约定:
+            - 用于大数据量场景, 避免一次性加载全部记录到内存.
+            - 内部应使用服务端游标 (yield_per / stream) 实现.
+        """
+        ...
+
+
+@runtime_checkable
+class SyncWriteDALProtocol(Protocol[SessionT, EntityT, DTOModelT, CUModelT]):
+    """同步写入 DAL 协议.
+
+    定义了下游实现必须提供的写入数据访问方法.
+    所有方法均为 classmethod, 接收显式 session 参数.
+    """
+
+    @classmethod
+    def create(cls, session: SessionT, cu: CUModelT, need_refresh: bool = True) -> EntityT:
+        """根据 CU 模型创建新实体.
+
+        Args:
+            session: 数据库会话.
+            cu: 创建/更新模型实例.
+            need_refresh: 创建后是否刷新实体 (获取自增 ID 等 DB 端生成值), 默认 True.
+
+        Returns:
+            新创建的 ORM 实体实例.
+
+        行为约定:
+            - 调用 ``cu.to_orm_model()`` (或等效方法) 生成 ORM 实体.
+            - 执行 ``session.add(entity)`` + ``session.flush()``.
+            - need_refresh=True 时应额外调用 ``session.refresh(entity)``.
+            - **不应** 自动 commit, 事务由调用方控制.
+        """
+        ...
+
+    @classmethod
+    def ret_dto_after_create(cls, session: SessionT, cu: CUModelT, need_refresh: bool = True) -> DTOModelT:
+        """创建新实体并以 DTO 形式返回.
+
+        Args:
+            session: 数据库会话.
+            cu: 创建/更新模型实例.
+            need_refresh: 同 ``create`` 的 need_refresh.
+
+        Returns:
+            新创建实体对应的 DTO 对象.
+
+        行为约定:
+            - 语义等同于 ``cls.create(session, cu) → convert to DTO``.
+        """
+        ...
+
+    @classmethod
+    def update_only_set_by_id(cls, session: SessionT, entity_id: int, cu: CUModelT, need_refresh: bool = False) -> EntityT | None:
+        """仅更新 CU 中已设置 (非 unset) 的字段.
+
+        Args:
+            session: 数据库会话.
+            entity_id: 要更新的实体主键 ID.
+            cu: 创建/更新模型, 仅 ``model_dump(exclude_unset=True)`` 中的字段会被更新.
+            need_refresh: 更新后是否刷新, 默认 False.
+
+        Returns:
+            更新后的 ORM 实体, 若 ID 不存在则返回 ``None``.
+
+        行为约定:
+            - 使用 ``cu.model_dump(exclude_unset=True, exclude={\"id\"})`` 获取变更字段.
+            - 仅 ``setattr`` 有效字段 (entity 上存在的属性).
+            - 执行 ``session.flush()`` 而非 commit.
+        """
+        ...
+
+    @classmethod
+    def delete_by_id(cls, session: SessionT, entity_id: int) -> bool:
+        """根据主键 ID 删除实体.
+
+        Args:
+            session: 数据库会话.
+            entity_id: 要删除的实体主键 ID.
+
+        Returns:
+            成功删除返回 ``True``, ID 不存在返回 ``False``.
+
+        行为约定:
+            - 如果实体混入了 ``SoftDeleteTableMixin``, 应执行软删除 (标记 is_delete=1)
+              而非物理删除.
+            - 软删除通过 ``session.delete(entity)`` 触发 before_flush 事件实现.
+            - 执行 ``session.flush()`` 而非 commit.
+        """
+        ...
+
+
+@runtime_checkable
+class SyncBaseDALProtocol(
+    SyncReadDALProtocol[SessionT, EntityT, DTOModelT],
+    SyncWriteDALProtocol[SessionT, EntityT, DTOModelT, CUModelT],
+    Protocol[SessionT, EntityT, DTOModelT, CUModelT],
+):
+    """同步完整 DAL 协议 (读 + 写).
+
+    组合了 ``SyncReadDALProtocol`` 和 ``SyncWriteDALProtocol`` 的全部方法.
+    """
+
+    ...
+
+
+@runtime_checkable
+class AsyncReadDALProtocol(Protocol[SessionT, EntityT, DTOModelT]):
+    """异步只读 DAL 协议.
+
+    语义与 ``SyncReadDALProtocol`` 完全一致, 所有方法为 ``async def``.
+    详细行为约定请参见同步版对应方法的 docstring.
+    """
+
+    @classmethod
+    async def get_by_id(cls, session: SessionT, entity_id: int) -> EntityT | None:
+        """根据主键 ID 获取单个 ORM 实体 (异步版)."""
+        ...
+
+    @classmethod
+    async def get_all(cls, session: SessionT, skip: int = 0, limit: int = 100) -> list[DTOModelT]:
+        """分页获取实体列表, 以 DTO 形式返回 (异步版)."""
+        ...
+
+    @classmethod
+    async def count(cls, session: SessionT) -> int:
+        """统计实体总数 (异步版)."""
+        ...
+
+    @classmethod
+    async def exists(cls, session: SessionT, entity_id: int) -> bool:
+        """判断指定 ID 的实体是否存在 (异步版)."""
+        ...
+
+    @classmethod
+    async def ret_dto_after_get_by_id(cls, session: SessionT, entity_id: int, need_refresh: bool = True) -> DTOModelT | None:
+        """根据主键 ID 获取实体并转为 DTO 返回 (异步版)."""
+        ...
+
+    @classmethod
+    async def batch_get_id__entity(cls, session: SessionT, entity_ids: Iterable[int]) -> dict[int, EntityT]:
+        """批量获取实体, 返回 {id: entity} 字典 (异步版)."""
+        ...
+
+    @classmethod
+    async def batch_get_id__dto(cls, session: SessionT, entity_ids: Iterable[int]) -> dict[int, DTOModelT]:
+        """批量获取实体, 返回 {id: DTO} 字典 (异步版)."""
+        ...
+
+    @classmethod
+    def iter_record_dtos(cls, session: SessionT, *, batch_size: int = 500) -> AsyncIterator[DTOModelT]:
+        """以异步迭代器方式逐条返回全部记录的 DTO (异步版)."""
+        ...
+
+
+@runtime_checkable
+class AsyncWriteDALProtocol(Protocol[SessionT, EntityT, DTOModelT, CUModelT]):
+    """异步写入 DAL 协议.
+
+    语义与 ``SyncWriteDALProtocol`` 完全一致, 所有方法为 ``async def``.
+    详细行为约定请参见同步版对应方法的 docstring.
+    """
+
+    @classmethod
+    async def create(cls, session: SessionT, cu: CUModelT, need_refresh: bool = True) -> EntityT:
+        """根据 CU 模型创建新实体 (异步版)."""
+        ...
+
+    @classmethod
+    async def ret_dto_after_create(cls, session: SessionT, cu: CUModelT, need_refresh: bool = True) -> DTOModelT:
+        """创建新实体并以 DTO 形式返回 (异步版)."""
+        ...
+
+    @classmethod
+    async def update_only_set_by_id(
+        cls, session: SessionT, entity_id: int, cu: CUModelT, need_refresh: bool = False
+    ) -> EntityT | None:
+        """仅更新 CU 中已设置的字段 (异步版)."""
+        ...
+
+    @classmethod
+    async def delete_by_id(cls, session: SessionT, entity_id: int) -> bool:
+        """根据主键 ID 删除实体 (异步版)."""
+        ...
+
+
+@runtime_checkable
+class AsyncBaseDALProtocol(
+    AsyncReadDALProtocol[SessionT, EntityT, DTOModelT],
+    AsyncWriteDALProtocol[SessionT, EntityT, DTOModelT, CUModelT],
+    Protocol[SessionT, EntityT, DTOModelT, CUModelT],
+):
+    """异步完整 DAL 协议 (读 + 写).
+
+    组合了 ``AsyncReadDALProtocol`` 和 ``AsyncWriteDALProtocol`` 的全部方法.
+    """
+
+    ...

lush_dal_protocol/utils/__init__.py

@@ -0,0 +1,11 @@
+"""通用工具函数子包."""
+
+from .retry import DEFAULT_RETRY_CONFIG, RetryConfig
+from .sql import escape_like, filtered_in_sql_values
+
+__all__ = [
+    "DEFAULT_RETRY_CONFIG",
+    "RetryConfig",
+    "escape_like",
+    "filtered_in_sql_values",
+]

lush_dal_protocol/utils/retry.py

@@ -0,0 +1,48 @@
+"""通用重试配置."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+
+@dataclass
+class RetryConfig:
+    """重试策略配置.
+
+    支持指数退避 + 可选抖动.
+    """
+
+    max_attempts: int = 3
+    initial_delay: float = 0.1
+    max_delay: float = 2.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError(f"max_attempts 必须>=1, 当前值: {self.max_attempts}")
+        if self.initial_delay < 0:
+            raise ValueError(f"initial_delay 必须>=0, 当前值: {self.initial_delay}")
+        if self.max_delay < self.initial_delay:
+            raise ValueError(f"max_delay({self.max_delay}) 必须>=initial_delay({self.initial_delay})")
+        if self.exponential_base <= 1:
+            raise ValueError(f"exponential_base 必须>1, 当前值: {self.exponential_base}")
+
+    def calculate_delay(self, attempt: int) -> float:
+        """根据当前重试次数计算等待时间 (秒)."""
+        if attempt <= 0:
+            return 0.0
+
+        delay = self.initial_delay * (self.exponential_base ** (attempt - 1))
+        delay = min(delay, self.max_delay)
+
+        if self.jitter and delay > 0:
+            jitter_range = delay * 0.2
+            delay = delay + random.uniform(-jitter_range, jitter_range)  # noqa: S311
+            delay = max(0, min(delay, self.max_delay))
+
+        return delay
+
+
+DEFAULT_RETRY_CONFIG = RetryConfig(max_attempts=3, initial_delay=0.1, max_delay=1.0)

lush_dal_protocol/utils/sql.py

@@ -0,0 +1,44 @@
+"""ORM 无关的通用工具函数."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TypeVar
+
+T = TypeVar("T")
+V = TypeVar("V")
+
+
+def filtered_in_sql_values(
+    values: Iterable[V] | None,
+    target_type_as: Callable[[V], T] = lambda x: x,
+) -> list[T]:
+    """过滤并去重 SQL IN 子句的值列表.
+
+    跳过 ``None`` 和空字符串, 类型转换失败的值也会被忽略.
+    """
+    if not values:
+        return []
+
+    items: list[T] = []
+    seen = set[T]()
+
+    for item in values:
+        if item is None or item == "":
+            continue
+        try:
+            converted_value = target_type_as(item)
+            if converted_value not in seen:
+                seen.add(converted_value)
+                items.append(converted_value)
+        except (ValueError, TypeError):
+            continue
+
+    return items
+
+
+def escape_like(value: str, escape_char: str = "\\") -> tuple[str, str]:
+    """转义用于 SQL LIKE 的特殊字符并返回转义后的值和转义字符."""
+    v = value.replace(escape_char, escape_char + escape_char)
+    v = v.replace("%", escape_char + "%").replace("_", escape_char + "_")
+    return v, escape_char

lush_dal_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: lush-dal-protocol
+Version: 0.1.0
+Summary: DAL (Data Access Layer) protocol for the lush ecosystem
+Author: straydragon
+Author-email: straydragon <straydragonl@foxmail.com>
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: pydantic>=2.11.0,<3.0.0
+Requires-Dist: typing-extensions>=4.12.2
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# lush-dal-protocol
+
+ORM 无关的数据访问层 (DAL) 协议抽象包。
+
+仅包含纯 Protocol / 接口声明，不依赖任何具体 ORM。
+下游适配包（如 `lush-sqlalchemyx`）负责实现这些协议。

lush_dal_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lush_dal_protocol/__init__.py,sha256=Josy6Xw8N2hOrmxOEs0NYcmacdx3n2fxYC_RXVqDjNM,1144
+lush_dal_protocol/dto.py,sha256=aoUppasqMoWuyexEQPHUfh3Rq4FQmfeM4y7rYQ-tf1I,2382
+lush_dal_protocol/errors.py,sha256=5DbtpGXNJhaedCEaV-gJoZ_dGiVuq8taEWApblU6F74,1012
+lush_dal_protocol/protocols/__init__.py,sha256=JV6HFrOM38xoQF6UoSE_ugmBcksGzBHrfElPfcP70hQ,543
+lush_dal_protocol/protocols/api_contracts.py,sha256=tDKlTOrDEqqjE8X6k9bsx5zdUVTdOy5e-nU3t_vep9Q,14687
+lush_dal_protocol/protocols/dal.py,sha256=UJE8P5kPZdRETgv2unt26BjUxQvOm1hBrhGuQawZXI4,11770
+lush_dal_protocol/utils/__init__.py,sha256=hc4RrHv57xIK3XIMNBl8J107RFxO8J-CBnxJhcGQVb4,250
+lush_dal_protocol/utils/retry.py,sha256=dhlJ7QSWhv3xOnjabmY0Gw8B18TNLsbozZsL-bG-j7E,1550
+lush_dal_protocol/utils/sql.py,sha256=L7M6SCUyAKgFsA-SHOXELsnRRtHh-cAhKkQw_cAUDmc,1217
+lush_dal_protocol-0.1.0.dist-info/WHEEL,sha256=XkDrRXQq-qVsrKMtsDUOHeLkiG7UK4Ds0JuG05OqKU4,81
+lush_dal_protocol-0.1.0.dist-info/METADATA,sha256=4htIAB8ism7XhsCWjDyp0HPds_-aod28Xcbuo8ySRbk,686
+lush_dal_protocol-0.1.0.dist-info/RECORD,,

lush_dal_protocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.13
+Root-Is-Purelib: true
+Tag: py3-none-any