python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/sqlalchemy/module_migration.py

@@ -12,11 +12,12 @@ from alembic.config import Config
 from alembic.migration import MigrationContext
 from alembic.operations.ops import MigrationScript
 from alembic.script import ScriptDirectory
-from sqlalchemy import Connection
+from sqlalchemy import Column, Connection, Index
 
 from ..modularity import AppModule, ModuleKey
 from .errors import SqlAlchemyModelRegistrationError
 from .metadata import SqlAlchemyModelCatalog
+from .migration_operations import _MigrationOperations
 
 
 class _ModuleMigration:
@@ -35,6 +36,31 @@ class _ModuleMigration:
             for item in models.for_connection(connection_name)
             if item.owner == self.owner
         )
+        self.extension = self.sources[0].extension if len(self.sources) == 1 else None
+        self._columns = tuple(
+            column
+            for model in models.extension_models
+            for column in model.columns
+            if any(
+                column.column.table.metadata is item.registration.metadata
+                for item in models.for_connection(connection_name)
+            )
+        )
+        if self.extension is not None:
+            tables = {column.column.table for column in self._columns if column.owner == self.owner}
+            self.metadata = tuple(
+                item.registration.metadata
+                for item in models.for_connection(connection_name)
+                if any(table in item.registration.metadata.tables.values() for table in tables)
+            )
+        self._operations = _MigrationOperations(
+            (
+                item.column
+                for item in self._columns
+                if self.extension is None or item.owner == self.owner
+            ),
+            extension=self.extension is not None,
+        )
         self.script = ScriptDirectory.from_config(config)
         self._version_table_options = config.attributes["version_table_options"]
         self.revisions = tuple(self.script.walk_revisions())
@@ -111,12 +137,19 @@ class _ModuleMigration:
             item.revision
             for item in self.script.iterate_revisions(heads, "base", implicit_base=True)
         )
+        dependencies = self.extension.depends_on if self.extension is not None else ()
+        if dependencies:
+            required |= frozenset(
+                item.revision
+                for item in self.script.iterate_revisions(dependencies, "base", implicit_base=True)
+            )
         # Schema 依赖只来自原生 revision；Module 的运行时依赖不推断为数据库前置关系。
         self._require(required, self._applied(connection))
         config.attributes.update(
             connection=connection,
             target_metadata=self.metadata,
             include_name=self._include_name,
+            include_object=self._include_object,
         )
         config.set_main_option("revision_environment", "true")
         # command.revision 的整库 autogenerate 检查会误阻塞无关未升级分支；改用其公开 hook
@@ -131,6 +164,14 @@ class _ModuleMigration:
         )
 
     def _include_name(self, name: str | None, type_: str, parents: dict[str, Any]) -> bool:
+        if self.extension is not None:
+            tables = {column.column.table for column in self._columns if column.owner == self.owner}
+            if type_ == "schema":
+                return name in {table.schema for table in tables if table is not None}
+            if type_ == "table":
+                return parents["schema_qualified_table_name"] in {
+                    table.key for table in tables if table is not None
+                }
         if type_ == "schema":
             return name in {
                 table.schema for meta in self.metadata for table in meta.tables.values()
@@ -141,11 +182,38 @@ class _ModuleMigration:
             )
         return True
 
+    def _include_object(
+        self,
+        obj: Any,
+        name: str | None,
+        type_: str,
+        reflected: bool,
+        compare_to: Any,
+    ) -> bool:
+        if type_ == "table" and self.extension is not None:
+            if not self._include_name(name, type_, {"schema_qualified_table_name": obj.key}):
+                return False
+            if compare_to is None:
+                raise ValueError("extension revisions cannot create or remove a base table")
+            return True
+        table = getattr(obj, "table", None)
+        if isinstance(obj, Column) and table is not None:
+            return self._operations.column(table.schema, table.name, name)
+        if isinstance(obj, Index) and table is not None:
+            # 同列上反射到的其他索引仍归其原 owner，不能被本扩展自动删除。
+            return self._operations.index(table.schema, table.name, name)
+        return self.extension is None
+
     def _generate(
         self, context: MigrationContext, revision: Any, directives: list[MigrationScript]
     ) -> None:
         # 一个 migration source 对应一份已登记 MetaData；不复制表形成影子 metadata。
-        generated = produce_migrations(context, self.metadata[0])
+        # Alembic 1.19.1 AutogenContext.sorted_tables 原生支持 metadata 序列，入口注解滞后。
+        generated = produce_migrations(context, self.metadata)  # type: ignore[arg-type]
         assert generated.upgrade_ops is not None and generated.downgrade_ops is not None
+        self._operations.restrict(generated.upgrade_ops)
         directives[0].upgrade_ops = generated.upgrade_ops
-        directives[0].downgrade_ops = generated.downgrade_ops
+        # 限定后的 upgrade 由 Alembic 原生 reverse 生成 downgrade，所有权范围保持对称。
+        directives[0].downgrade_ops = generated.upgrade_ops.reverse()
+        if self.extension is not None:
+            directives[0].depends_on = self.extension.depends_on

python_ddd_framework/sqlalchemy/repository.py

@@ -1,9 +1,19 @@
-"""刻意窄化的 SQLAlchemy repository base；查询语义仍由业务 Module 拥有。"""
+"""原生 ORM 仓储；业务筛选和领域映射由具体仓储拥有。"""
 
 from __future__ import annotations
 
-from typing import Generic, TypeVar, cast
+from collections.abc import Iterable
+from typing import Any, Generic, TypeVar, cast
 
+from sqlalchemy import Select, func, inspect, select
+from sqlalchemy.orm import LoaderCriteriaOption, Mapper
+from sqlalchemy.orm.exc import StaleDataError
+from sqlalchemy.orm.interfaces import ORMOption
+from sqlalchemy.sql.elements import ColumnElement
+
+from ..domain import OptimisticConcurrencyError
+from ..errors import ResourceNotFoundError
+from ..events.entities import EntityCreatedEvent, EntityDeletedEvent, EntityUpdatedEvent
 from .session_provider import SqlAlchemySessionProvider
 
 _TModel = TypeVar("_TModel")
@@ -11,23 +21,217 @@ _TId = TypeVar("_TId")
 
 
 class SqlAlchemyRepository(Generic[_TModel, _TId]):
-    __slots__ = ("_model_type", "_provider")
-
-    def __init__(self, provider: SqlAlchemySessionProvider, model_type: type[_TModel]) -> None:
+    def __init__(
+        self,
+        provider: SqlAlchemySessionProvider,
+        model_type: type[_TModel],
+        *,
+        detail_options: tuple[ORMOption, ...] = (),
+    ) -> None:
         self._provider = provider
         self._model_type = model_type
+        self._detail_options = detail_options
+
+    def _query(self) -> Select[tuple[_TModel]]:
+        """业务仓储覆写此原生查询时，list/count/page 共享同一筛选。"""
+        return select(self._model_type)
+
+    def _default_sorting(self) -> str | None:
+        return None
+
+    def _entity_query(self) -> Select[tuple[_TModel]]:
+        mapper = inspect(self._model_type)
+        assert isinstance(mapper, Mapper)
+        query = self._query()
+        source = query.order_by(None).subquery()
+        predicates = []
+        for primary_key in mapper.primary_key:
+            selected = source.c.corresponding_column(primary_key)
+            if selected is None:
+                raise ValueError("_query must select the mapped entity primary key")
+            predicates.append(primary_key == selected)
+        # 关联筛选只决定实体是否入选；EXISTS 在 SQL 分页前消除关联行的倍增。
+        # 只比较真实主键（含复合键），不要求 JSON 等实体字段支持 DISTINCT。
+        # SQLAlchemy 2.0 的 ORM options 只由顶层语句解释；子查询不会自行携带它们。
+        # 原生语句没有公开的 options 读取器，仅在此边界转交已声明元数据。
+        return (
+            select(self._model_type)
+            .where(select(1).select_from(source).where(*predicates).exists())
+            .options(*query._with_options)
+            .execution_options(**query.get_execution_options())
+        )
 
-    async def get(self, entity_id: _TId) -> _TModel | None:
+    def _order_by(self, sorting: str | None) -> tuple[ColumnElement[Any], ...]:
+        mapper = inspect(self._model_type)
+        assert isinstance(mapper, Mapper)
+        attributes = {item.key: item for item in mapper.column_attrs}
+        result: list[ColumnElement[Any]] = []
+        used: set[str] = set()
+        for term in (sorting or self._default_sorting() or "").split(","):
+            if not term.strip():
+                continue
+            parts = term.split()
+            if (
+                len(parts) > 2
+                or parts[0] not in attributes
+                or (len(parts) == 2 and parts[1].lower() not in ("asc", "desc"))
+            ):
+                raise ValueError("sorting must use mapped column names and asc/desc")
+            name = parts[0]
+            column = attributes[name].columns[0]
+            result.append(
+                column.desc() if len(parts) == 2 and parts[1].lower() == "desc" else column.asc()
+            )
+            used.add(name)
+        # 唯一补序来自 ORM 的真实主键，不维护第二份排序字段名单。
+        for primary_key in mapper.primary_key:
+            if mapper.get_property_by_column(primary_key).key not in used:
+                result.append(primary_key.asc())
+        return tuple(result)
+
+    async def find(self, entity_id: _TId, include_details: bool = True) -> _TModel | None:
         async with self._provider.operation("get"):
             session = await self._provider.get_session()
-            return cast(_TModel | None, await session.get(self._model_type, entity_id))
+            if include_details and self._detail_options:
+                mapper = inspect(self._model_type)
+                assert isinstance(mapper, Mapper)
+                values = (
+                    tuple(
+                        entity_id[mapper.get_property_by_column(column).key]
+                        for column in mapper.primary_key
+                    )
+                    if isinstance(entity_id, dict)
+                    else entity_id
+                    if isinstance(entity_id, tuple)
+                    else (entity_id,)
+                )
+                if len(values) != len(mapper.primary_key):
+                    raise ValueError("identity must match the mapped primary key")
+                # Session.get 的 identity-map 命中不会执行 loader options；显式 SELECT
+                # 补加载关系而不 populate_existing，避免覆盖同事务尚未 flush 的修改。
+                result = await session.scalars(
+                    select(self._model_type)
+                    .where(
+                        *(
+                            column == value
+                            for column, value in zip(mapper.primary_key, values, strict=True)
+                        )
+                    )
+                    .options(*self._detail_options)
+                )
+                return result.unique().one_or_none()
+            return cast(
+                _TModel | None,
+                await session.get(
+                    self._model_type,
+                    entity_id,
+                    options=self._detail_options if include_details else (),
+                ),
+            )
+
+    async def get(self, entity_id: _TId, include_details: bool = True) -> _TModel:
+        entity = await self.find(entity_id, include_details)
+        if entity is None:
+            raise ResourceNotFoundError(f"{self._model_type.__name__} was not found")
+        return entity
+
+    async def get_list(self, include_details: bool = False) -> list[_TModel]:
+        async with self._provider.operation("get_list"):
+            session = await self._provider.get_session()
+            query = self._entity_query().order_by(*self._order_by(None))
+            if include_details:
+                query = query.options(*self._detail_options)
+            return list((await session.scalars(query)).unique().all())
 
-    async def add(self, entity: _TModel) -> None:
-        async with self._provider.operation("add"):
+    async def get_count(self) -> int:
+        async with self._provider.operation("get_count"):
             session = await self._provider.get_session()
-            session.add(entity)
+            query = self._entity_query()
+            count = await session.scalar(
+                select(func.count())
+                .select_from(query.subquery())
+                # 计数保留 ORM 筛选，但不对表达式结果应用关系加载选项。
+                .options(
+                    *(
+                        option
+                        for option in query._with_options
+                        if isinstance(option, LoaderCriteriaOption)
+                    )
+                )
+            )
+            assert isinstance(count, int)
+            return count
 
-    async def delete(self, entity: _TModel) -> None:
-        async with self._provider.operation("delete"):
+    async def get_paged_list(
+        self,
+        skip_count: int,
+        max_result_count: int,
+        sorting: str | None = None,
+        include_details: bool = False,
+    ) -> list[_TModel]:
+        if skip_count < 0 or max_result_count <= 0:
+            raise ValueError("skip_count must be nonnegative and max_result_count positive")
+        async with self._provider.operation("get_paged_list"):
             session = await self._provider.get_session()
-            await session.delete(entity)
+            query = self._entity_query().order_by(*self._order_by(sorting))
+            if include_details:
+                query = query.options(*self._detail_options)
+            return list(
+                (await session.scalars(query.offset(skip_count).limit(max_result_count)))
+                .unique()
+                .all()
+            )
+
+    async def insert(self, entity: _TModel, auto_save: bool = False) -> _TModel:
+        async with self._provider.operation(
+            "insert", entity_event=EntityCreatedEvent(entity), auto_save=auto_save
+        ):
+            (await self._provider.get_session()).add(entity)
+        return entity
+
+    async def update(self, entity: _TModel, auto_save: bool = False) -> _TModel:
+        async with self._provider.operation("update", write=True, auto_save=auto_save):
+            session = await self._provider.get_session()
+            # 原生 merge 保留 version_id_col 的竞争检查，不使用 bulk DML 绕过事件/审计。
+            try:
+                entity = await session.merge(entity)
+            except StaleDataError:
+                raise OptimisticConcurrencyError from None
+            if session.is_modified(entity):
+                async with self._provider.operation(
+                    "update", entity_event=EntityUpdatedEvent(entity)
+                ):
+                    pass
+        return entity
+
+    async def delete(self, entity: _TModel, auto_save: bool = False) -> None:
+        async with self._provider.operation(
+            "delete", entity_event=EntityDeletedEvent(entity), auto_save=auto_save
+        ):
+            await (await self._provider.get_session()).delete(entity)
+
+    async def delete_by_id(self, entity_id: _TId, auto_save: bool = False) -> None:
+        async with self._provider.operation("delete_by_id", write=True, auto_save=auto_save):
+            entity = await self.find(entity_id)
+            if entity is not None:
+                await self.delete(entity)
+
+    async def insert_many(self, entities: Iterable[_TModel], auto_save: bool = False) -> None:
+        async with self._provider.operation("insert_many", write=True, auto_save=auto_save):
+            for entity in entities:
+                await self.insert(entity)
+
+    async def update_many(self, entities: Iterable[_TModel], auto_save: bool = False) -> None:
+        async with self._provider.operation("update_many", write=True, auto_save=auto_save):
+            for entity in entities:
+                await self.update(entity)
+
+    async def delete_many(self, entities: Iterable[_TModel], auto_save: bool = False) -> None:
+        async with self._provider.operation("delete_many", write=True, auto_save=auto_save):
+            for entity in entities:
+                await self.delete(entity)
+
+    async def delete_many_by_ids(self, entity_ids: Iterable[_TId], auto_save: bool = False) -> None:
+        async with self._provider.operation("delete_many_by_ids", write=True, auto_save=auto_save):
+            for entity_id in entity_ids:
+                await self.delete_by_id(entity_id)

python_ddd_framework/sqlalchemy/session_provider.py

@@ -8,6 +8,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..domain import AggregateRoot
 from ..events.aggregate import _collect_aggregate_events
+from ..events.entities import EntityChangedEvent
+from ..events.unit_of_work import _local_event_queue
 from ..unit_of_work.manager import UnitOfWorkManager
 from ..unit_of_work.options import UnitOfWorkDeclaration
 from .unit_of_work import _SqlAlchemyUnitOfWork
@@ -29,17 +31,28 @@ class SqlAlchemySessionProvider:
         method_name: str,
         *,
         aggregate: AggregateRoot[Any] | None = None,
+        entity_event: EntityChangedEvent | None = None,
+        auto_save: bool = False,
+        write: bool = False,
     ) -> AsyncIterator[None]:
         """仓储暂存边界；成功后收集聚合事件，Session 仍由 get_session 懒创建。"""
         if aggregate is not None and not isinstance(aggregate, AggregateRoot):
             raise TypeError("aggregate must be AggregateRoot")
         options = self._manager._resolve_options(None, UnitOfWorkDeclaration(), method_name)
         async with self._manager._begin(options) as work:
-            owner = self._manager.require_current(transactional=aggregate is not None)
+            # 自动事件的资格检查先于写入、版本暂存和 flush，已保存批次不受影响。
+            owner = self._manager.require_current(
+                transactional=write or aggregate is not None or entity_event is not None
+            )
             yield
             if aggregate is not None:
                 # 参与者不拥有提交权；成功暂存后必须仍在进入时的同一有效事务中。
                 if self._manager.require_current(transactional=True) is not owner:
                     raise RuntimeError("aggregate operation changed its UnitOfWork owner")
                 _collect_aggregate_events(owner, aggregate)
+            if entity_event is not None:
+                queue = _local_event_queue(owner)
+                queue.enqueue(entity_event)
+            if auto_save:
+                await owner.flush()
             await work.complete()

python_ddd_framework/testing/runtime.py

@@ -9,6 +9,7 @@ from typing import Concatenate, ParamSpec, TypeVar
 from ..application import Application, ApplicationBuilder
 from ..application_services import ApplicationServiceContract
 from ..authorization import CurrentUser
+from ..invocation import entrypoints
 
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
@@ -80,7 +81,7 @@ class TestApplication:
         *args: object,
         **kwargs: object,
     ) -> _R:
-        return await self.application.call(function, *args, **kwargs)
+        return await entrypoints.call(self.application, function, *args, **kwargs)
 
     async def call_as(
         self,
@@ -90,7 +91,7 @@ class TestApplication:
         *args: object,
         **kwargs: object,
     ) -> _R:
-        return await self.application.call_as(current_user, function, *args, **kwargs)
+        return await entrypoints.call_as(self.application, current_user, function, *args, **kwargs)
 
     async def invoke(
         self,
@@ -99,7 +100,7 @@ class TestApplication:
         *args: _P.args,
         **kwargs: _P.kwargs,
     ) -> _R:
-        return await self.application.invoke(method, *args, **kwargs)
+        return await entrypoints.invoke(self.application, method, *args, **kwargs)
 
     async def invoke_as(
         self,
@@ -109,4 +110,4 @@ class TestApplication:
         *args: _P.args,
         **kwargs: _P.kwargs,
     ) -> _R:
-        return await self.application.invoke_as(current_user, method, *args, **kwargs)
+        return await entrypoints.invoke_as(self.application, current_user, method, *args, **kwargs)

python_ddd_framework/unit_of_work/__init__.py

@@ -1,10 +1,11 @@
 from .contracts import UnitOfWork, UnitOfWorkState
-from .errors import UnitOfWorkStateError
+from .errors import UnitOfWorkCompletionError, UnitOfWorkStateError
 from .manager import UnitOfWorkManager
 from .options import UnitOfWorkOptions, UnitOfWorkTransactionBehavior, unit_of_work
 
 __all__ = (
     "UnitOfWork",
+    "UnitOfWorkCompletionError",
     "UnitOfWorkManager",
     "UnitOfWorkOptions",
     "UnitOfWorkState",

python_ddd_framework/unit_of_work/contracts.py

@@ -5,14 +5,11 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Awaitable, Callable
 from enum import Enum
-from typing import TYPE_CHECKING
 
 from .errors import UnitOfWorkStateError
+from .lifecycle import UnitOfWorkLifecycle
 from .options import _ResolvedUnitOfWorkOptions
 
-if TYPE_CHECKING:
-    from ..events.runtime import _LocalEventQueue
-
 
 class UnitOfWorkState(str, Enum):
     ACTIVE = "active"
@@ -34,7 +31,7 @@ class UnitOfWork:
         self._saved_batches = 0
         self._cleanup_failures: tuple[BaseException, ...] = ()
         self._options: _ResolvedUnitOfWorkOptions | None = None
-        self._event_queue: _LocalEventQueue | None = None
+        self._lifecycles: tuple[UnitOfWorkLifecycle, ...] = ()
         self._after_commit: Callable[[], Awaitable[None]] | None = None
 
     @property
@@ -101,8 +98,10 @@ class UnitOfWork:
         self._require_active("complete")
         self._completing = True
         try:
-            if self._event_queue is not None:
-                await self._event_queue._dispatch_domain()
+            # 能力在提交前完成自己的工作；任何失败都必须阻止后续 flush/commit。
+            # UoW 只编排生命周期，不认识事件队列或其他能力的运行状态。
+            for lifecycle in self._lifecycles:
+                await lifecycle.before_commit()
             await self.flush()
             await self._save_batch()
             self._committed = True

python_ddd_framework/unit_of_work/errors.py

@@ -25,3 +25,14 @@ class UnitOfWorkStateError(FrameworkError):
         super().__init__(
             f"UnitOfWork.{operation} requires state in ({allowed_values}), got {current.value}"
         )
+
+
+class UnitOfWorkCompletionError(FrameworkError):
+    """提交后参与者失败；数据库提交事实不随缓存/通知失败撤销。"""
+
+    def __init__(self, failures: tuple[Exception, ...]) -> None:
+        self.committed = True
+        self.failures = failures
+        super().__init__(
+            f"UnitOfWork committed, but {len(failures)} completion participant(s) failed"
+        )

python_ddd_framework/unit_of_work/lifecycle.py

@@ -0,0 +1,19 @@
+"""事务完成的能力扩展点；不依赖事件、缓存或具体持久化实现。"""
+
+from typing import Protocol
+
+from dishka import AsyncContainer
+
+from ..invocation import ApplicationInvocationContext
+
+
+class UnitOfWorkLifecycle(Protocol):
+    async def before_commit(self) -> None: ...
+
+    async def after_commit(self) -> None: ...
+
+
+class UnitOfWorkLifecycleFactory(Protocol):
+    def create(
+        self, container: AsyncContainer, context: ApplicationInvocationContext
+    ) -> UnitOfWorkLifecycle: ...