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

python_ddd_framework/background_jobs/catalog.py

@@ -5,15 +5,18 @@ from __future__ import annotations
 import hashlib
 import json
 from collections.abc import Iterator, Mapping
-from dataclasses import replace
+from dataclasses import dataclass
 from datetime import UTC, datetime
 from types import MappingProxyType
 from typing import TypeVar, cast
 
 from pydantic import BaseModel, ValidationError
+from pydantic_core import PydanticSerializationError
 
-from ..modularity import AppModule, ModuleDescriptor, ModuleKey, ModuleRegistry
+from ..background_execution.declarations import BackgroundJobs, BackgroundSchedules
+from ..modularity import ModuleDescriptor, ModuleKey, ModuleRegistry
 from ..modularity.discovery import _DiscoveredType, _is_concrete_implementation
+from ..validation.models import _revalidate_model
 from .contracts import BackgroundJobDefinition, BackgroundJobHandler, BackgroundJobSchedule
 from .declaration import _definition_from_type
 from .errors import BackgroundJobDefinitionError, BackgroundJobPayloadError
@@ -21,10 +24,19 @@ from .errors import BackgroundJobDefinitionError, BackgroundJobPayloadError
 _TPayload = TypeVar("_TPayload", bound=BaseModel)
 
 
+@dataclass(frozen=True, slots=True)
+class _CompiledJobSchedule:
+    """单个 Application 解释后的计划；持久任务事实仍引用冻结定义。"""
+
+    name: str
+    cron: str
+    definition: BackgroundJobDefinition[BaseModel]
+    payload: bytes
+
+
 class BackgroundJobCatalog:
     __slots__ = (
         "_current",
-        "_declarations",
         "_definitions",
         "_fingerprint",
         "_owners",
@@ -34,9 +46,8 @@ class BackgroundJobCatalog:
     def __init__(
         self,
         definitions: tuple[BackgroundJobDefinition[BaseModel], ...],
-        schedules: tuple[BackgroundJobSchedule, ...],
+        schedules: tuple[_CompiledJobSchedule, ...],
         *,
-        declarations: tuple[tuple[type[AppModule], str, tuple[object, ...]], ...],
         owners: Mapping[tuple[str, int], ModuleKey],
     ) -> None:
         self._definitions = MappingProxyType(
@@ -44,7 +55,6 @@ class BackgroundJobCatalog:
         )
         self._current = MappingProxyType({item.name: item for item in definitions if item.current})
         self._schedules = MappingProxyType({item.name: item for item in schedules})
-        self._declarations = declarations
         self._owners = MappingProxyType(dict(owners))
         encoded = json.dumps(
             {
@@ -66,8 +76,8 @@ class BackgroundJobCatalog:
                     {
                         "name": item.name,
                         "cron": item.cron,
-                        "job_name": item.job_name,
-                        "job_version": item.job_version,
+                        "job_name": item.definition.name,
+                        "job_version": item.definition.version,
                         "payload": item.payload.decode(),
                     }
                     for item in schedules
@@ -83,7 +93,7 @@ class BackgroundJobCatalog:
         return tuple(self._definitions.values())
 
     @property
-    def schedules(self) -> tuple[BackgroundJobSchedule, ...]:
+    def schedules(self) -> tuple[_CompiledJobSchedule, ...]:
         return tuple(self._schedules.values())
 
     @property
@@ -99,7 +109,7 @@ class BackgroundJobCatalog:
     def current(self, name: str) -> BackgroundJobDefinition[BaseModel] | None:
         return self._current.get(name)
 
-    def get_schedule(self, name: str) -> BackgroundJobSchedule | None:
+    def get_schedule(self, name: str) -> _CompiledJobSchedule | None:
         return self._schedules.get(name)
 
     def owns(self, definition: BackgroundJobDefinition[_TPayload]) -> bool:
@@ -127,20 +137,16 @@ class BackgroundJobCatalog:
                 raise BackgroundJobDefinitionError(
                     job=definition.name, reason="Job class metadata changed after build"
                 )
-        for module_type, attribute, declared in self._declarations:
-            if module_type.__dict__.get(attribute, ()) is not declared:
-                raise BackgroundJobDefinitionError(
-                    job=f"{module_type.__module__}.{module_type.__qualname__}",
-                    reason=f"Module {attribute} metadata changed after build",
-                )
 
 
 def _build_background_job_catalog(
     registry: ModuleRegistry, discoveries: tuple[_DiscoveredType, ...]
 ) -> BackgroundJobCatalog:
     builder = _BackgroundJobCatalogBuilder()
-    for descriptor in registry.dependency_order:
-        builder.add_module(descriptor)
+    for descriptor, declaration in registry.declarations(BackgroundJobs):
+        builder.add_definitions(descriptor, declaration.definitions)
+    for descriptor, schedules in registry.declarations(BackgroundSchedules):
+        builder.add_schedules(descriptor, schedules.schedules)
     seen: set[tuple[ModuleKey, type[object]]] = set()
     for discovery in discoveries:
         candidate = discovery.candidate
@@ -159,7 +165,6 @@ class _BackgroundJobCatalogBuilder:
     """拥有 catalog build 期间的 mutable arbitration state，产物仍为 immutable。"""
 
     __slots__ = (
-        "_declarations",
         "_definitions",
         "_name_owners",
         "_owners",
@@ -169,31 +174,21 @@ class _BackgroundJobCatalogBuilder:
 
     def __init__(self) -> None:
         self._definitions: list[BackgroundJobDefinition[BaseModel]] = []
-        self._raw_schedules: list[BackgroundJobSchedule] = []
+        self._raw_schedules: list[BackgroundJobSchedule[BaseModel]] = []
         self._owners: dict[tuple[str, int], ModuleKey] = {}
         self._name_owners: dict[str, ModuleKey] = {}
         self._schedule_owners: dict[str, ModuleKey] = {}
-        self._declarations: list[tuple[type[AppModule], str, tuple[object, ...]]] = []
 
-    def add_module(self, descriptor: ModuleDescriptor) -> None:
-        declared_definitions = descriptor.module_type.__dict__.get("background_job_definitions", ())
-        declared_schedules = descriptor.module_type.__dict__.get("background_job_schedules", ())
+    def add_definitions(
+        self,
+        descriptor: ModuleDescriptor,
+        declared_definitions: tuple[object, ...],
+    ) -> None:
         _validate_metadata_tuple(
             declared_definitions,
             owner=str(descriptor.key),
             attribute="background_job_definitions",
         )
-        _validate_metadata_tuple(
-            declared_schedules,
-            owner=str(descriptor.key),
-            attribute="background_job_schedules",
-        )
-        self._declarations.extend(
-            (
-                (descriptor.module_type, "background_job_definitions", declared_definitions),
-                (descriptor.module_type, "background_job_schedules", declared_schedules),
-            )
-        )
         for definition in declared_definitions:
             if isinstance(definition, BackgroundJobDefinition) and isinstance(
                 definition.handler_type, type
@@ -203,6 +198,17 @@ class _BackgroundJobCatalogBuilder:
                     reason="class Jobs must be discovered through Module scan_packages",
                 )
             self._add_definition(definition, descriptor.key)
+
+    def add_schedules(
+        self,
+        descriptor: ModuleDescriptor,
+        declared_schedules: tuple[object, ...],
+    ) -> None:
+        _validate_metadata_tuple(
+            declared_schedules,
+            owner=str(descriptor.key),
+            attribute="background_job_schedules",
+        )
         for schedule in declared_schedules:
             self._add_schedule(schedule, descriptor.key)
 
@@ -226,7 +232,6 @@ class _BackgroundJobCatalogBuilder:
         return BackgroundJobCatalog(
             tuple(self._definitions),
             schedules,
-            declarations=tuple(self._declarations),
             owners=self._owners,
         )
 
@@ -278,19 +283,31 @@ def _validate_metadata_tuple(value: object, *, owner: str, attribute: str) -> No
 
 
 def _canonicalize_schedule(
-    schedule: BackgroundJobSchedule,
+    schedule: BackgroundJobSchedule[BaseModel],
     definitions: Mapping[tuple[str, int], BackgroundJobDefinition[BaseModel]],
-) -> BackgroundJobSchedule:
-    definition = definitions.get((schedule.job_name, schedule.job_version))
+) -> _CompiledJobSchedule:
+    target = schedule.job
+    definition = (
+        next((item for item in definitions.values() if item.handler_type is target), None)
+        if isinstance(target, type)
+        else definitions.get((target.name, target.version))
+    )
     if definition is None:
         raise BackgroundJobDefinitionError(
             job=schedule.name,
             reason="schedule target does not exist in the Application catalog",
         )
+    if not isinstance(target, type) and definition is not target:
+        raise BackgroundJobDefinitionError(
+            job=schedule.name, reason="schedule definition is not owned by this Application catalog"
+        )
     cron = _normalize_cron(schedule.name, schedule.cron)
     try:
-        payload = definition.payload_type.model_validate_json(schedule.payload)
-    except ValidationError:
+        if not isinstance(schedule.payload, definition.payload_type):
+            raise TypeError("scheduled payload does not match the job definition")
+        # 重验显式对象，不能让 model_construct 或事后修改绕过持久 payload schema。
+        payload = _revalidate_model(definition.payload_type, schedule.payload)
+    except (TypeError, ValidationError, PydanticSerializationError):
         raise BackgroundJobPayloadError(
             job=definition.name,
             version=definition.version,
@@ -302,7 +319,7 @@ def _canonicalize_schedule(
         separators=(",", ":"),
         ensure_ascii=False,
     ).encode()
-    return replace(schedule, cron=cron, payload=canonical)
+    return _CompiledJobSchedule(schedule.name, cron, definition, canonical)
 
 
 def _normalize_cron(schedule_name: str, expression: str) -> str:

python_ddd_framework/background_jobs/contracts.py

@@ -10,9 +10,11 @@ from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from typing import ClassVar, Generic, Protocol, TypeVar, cast
 
+from dishka import Scope
 from pydantic import BaseModel
 
 from ..invocation import BackgroundSystemCaller
+from ..modularity import ModuleRef, ModuleRequirement
 from .errors import BackgroundJobDefinitionError
 
 _TPayload = TypeVar("_TPayload", bound=BaseModel)
@@ -35,6 +37,7 @@ class BackgroundJobContext:
 
 @dataclass(frozen=True, slots=True)
 class BackgroundJobRetryPolicy:
+    # 包含首次执行的总次数；1 表示失败后不再重试。
     max_attempts: int = 5
     initial_delay: timedelta = timedelta(seconds=1)
     max_delay: timedelta = timedelta(minutes=5)
@@ -80,6 +83,11 @@ class BackgroundJobRetryPolicy:
 class BackgroundJobHandler(ABC, Generic[_TPayload]):
     """Module 扫描的任务声明；queue loop/retry 仍由 provider 独占。"""
 
+    _fixed_service_scope: ClassVar[Scope] = Scope.ACTION
+    __background_execution_module__ = ModuleRequirement(
+        ModuleRef("python_ddd_framework.background_execution.module:BackgroundExecutionModule")
+    )
+
     name: ClassVar[str]
     version: ClassVar[int]
     timeout: ClassVar[timedelta]
@@ -143,42 +151,31 @@ class BackgroundJobDefinition(Generic[_TPayload]):
 
 
 @dataclass(frozen=True, slots=True)
-class BackgroundJobSchedule:
+class BackgroundJobSchedule(Generic[_TPayload]):
     name: str
     cron: str
-    job_name: str
-    job_version: int
-    payload: bytes
+    job: type[BackgroundJobHandler[_TPayload]] | BackgroundJobDefinition[_TPayload]
+    payload: _TPayload
 
     def __post_init__(self) -> None:
         _validate_name(self.name)
-        _validate_name(self.job_name)
-        if (
-            not isinstance(self.job_version, int)
-            or isinstance(self.job_version, bool)
-            or self.job_version < 1
+        if not isinstance(self.job, BackgroundJobDefinition) and not (
+            isinstance(self.job, type) and issubclass(self.job, BackgroundJobHandler)
         ):
             raise BackgroundJobDefinitionError(
                 job=self.name,
-                reason="job_version must be a positive integer",
+                reason="schedule job must be a Job type or BackgroundJobDefinition",
             )
         if not isinstance(self.cron, str) or not self.cron.strip():
             raise BackgroundJobDefinitionError(
                 job=self.name,
                 reason="cron must be a non-empty string",
             )
-        if not isinstance(self.payload, bytes):
+        if not isinstance(self.payload, BaseModel):
             raise BackgroundJobDefinitionError(
                 job=self.name,
-                reason="payload must be immutable UTF-8 JSON bytes",
+                reason="schedule payload must be a typed Pydantic model",
             )
-        try:
-            self.payload.decode("utf-8")
-        except UnicodeDecodeError:
-            raise BackgroundJobDefinitionError(
-                job=self.name,
-                reason="payload must be UTF-8 JSON bytes",
-            ) from None
 
 
 class BackgroundJobEnqueuer(Protocol):

python_ddd_framework/background_jobs/pgqueuer/enqueue.py

@@ -69,6 +69,10 @@ class _PgQueuerBackgroundJobEnqueuer:
         driver_connection: Any = raw.driver_connection
         if not isinstance(driver_connection, asyncpg.Connection):
             raise TypeError("SQLAlchemy connection does not expose an asyncpg connection")
+        # asyncpg 方言直到首次 SQL 才真正 BEGIN；仅取得 Session connection 仍可能未开事务。
+        # 经 SQLAlchemy 公开执行路径启动事务，保留 UoW 的提交/回滚 owner，再交给原生队列。
+        if not driver_connection.is_in_transaction():
+            await connection.exec_driver_sql("SELECT 1")
         queries = _queries_for_connection(
             driver_connection,
             self._options,

python_ddd_framework/background_jobs/pgqueuer/module.py

@@ -8,6 +8,7 @@ from typing import Any
 import asyncpg  # type: ignore[import-untyped]
 from dishka import Provider, Scope
 
+from ...background_execution.module import BackgroundExecutionModule
 from ...background_jobs import BackgroundJobCatalog
 from ...background_workers.runtime import _BackgroundCoordinator
 from ...lifecycle import ConfigureContext, InitializeContext, ShutdownContext
@@ -38,7 +39,7 @@ def _migration_registration(options: OptionsSnapshot) -> SqlAlchemyMigrationRegi
 
 @contributes_sqlalchemy_migrations(_migration_registration)
 class PgQueuerBackgroundJobsModule(AppModule):
-    dependencies = (SqlAlchemyPersistenceModule,)
+    dependencies = (SqlAlchemyPersistenceModule, BackgroundExecutionModule)
 
     def __init__(self) -> None:
         self._runtimes: list[_PgQueuerRuntime] = []

python_ddd_framework/background_jobs/pgqueuer/runtime.py

@@ -31,8 +31,8 @@ from ...background_execution.lifecycle import (
     _TaskExecution,
 )
 from ...options import Options
-from ..catalog import BackgroundJobCatalog
-from ..contracts import BackgroundJobDefinition, BackgroundJobSchedule
+from ..catalog import BackgroundJobCatalog, _CompiledJobSchedule
+from ..contracts import BackgroundJobDefinition
 from ..errors import (
     BackgroundJobDefinitionError,
     BackgroundJobExecutionError,
@@ -329,10 +329,9 @@ class _PgQueuerRuntime:
         if not self._options.scheduler_enabled:
             return
         for schedule in self._catalog.schedules:
-            if schedule.job_name != self._job_name:
+            if schedule.definition.name != self._job_name:
                 continue
-            definition = self._catalog.get(schedule.job_name, schedule.job_version)
-            assert definition is not None
+            definition = schedule.definition
             envelope = _encode_scheduled_envelope(definition, schedule.payload)
             target_entrypoint = _entrypoint_name(definition.name, definition.version)
 
@@ -360,7 +359,8 @@ class _PgQueuerRuntime:
         def create(parameters: EntrypointExecutorParameters) -> _ShutdownAwareRetryExecutor:
             return _ShutdownAwareRetryExecutor(
                 parameters=parameters,
-                max_attempts=policy.max_attempts,
+                # PgQueuer 从 0 计数，原生阈值代表额外重试；公开策略包含首次执行。
+                max_attempts=policy.max_attempts - 1,
                 initial_delay=policy.initial_delay,
                 max_delay=policy.max_delay,
                 backoff_multiplier=policy.backoff_multiplier,
@@ -426,7 +426,7 @@ def _entrypoint_name(name: str, version: int) -> str:
     return f"{name}.v{version}"
 
 
-def _schedule_entrypoint_name(schedule: BackgroundJobSchedule) -> str:
+def _schedule_entrypoint_name(schedule: _CompiledJobSchedule) -> str:
     return f"schedule.{schedule.name}"
 
 

python_ddd_framework/background_workers/catalog.py

@@ -7,24 +7,23 @@ import json
 from collections.abc import Iterator, Mapping
 from types import MappingProxyType
 
-from ..modularity import AppModule, ModuleKey, ModuleRegistry
+from ..background_execution.declarations import BackgroundWorkers
+from ..modularity import ModuleKey, ModuleRegistry
 from .contracts import BackgroundWorker, BackgroundWorkerDefinition, _definition_from_type
 from .errors import BackgroundWorkerDefinitionError
 
 
 class BackgroundWorkerCatalog:
-    __slots__ = ("_declarations", "_definitions", "_fingerprint", "_owners")
+    __slots__ = ("_definitions", "_fingerprint", "_owners")
 
     def __init__(
         self,
         definitions: tuple[BackgroundWorkerDefinition, ...],
         *,
         owners: Mapping[str, ModuleKey],
-        declarations: tuple[tuple[type[AppModule], str, tuple[object, ...]], ...],
     ) -> None:
         self._definitions = MappingProxyType({item.name: item for item in definitions})
         self._owners = MappingProxyType(dict(owners))
-        self._declarations = declarations
         encoded = json.dumps(
             [
                 {
@@ -66,53 +65,41 @@ class BackgroundWorkerCatalog:
                 raise BackgroundWorkerDefinitionError(
                     worker=definition.name, reason="Worker class metadata changed after build"
                 )
-        for module_type, attribute, declared in self._declarations:
-            if module_type.__dict__.get(attribute, ()) is not declared:
-                raise BackgroundWorkerDefinitionError(
-                    worker=f"{module_type.__module__}.{module_type.__qualname__}",
-                    reason="Module background worker metadata changed after build",
-                )
 
 
 def _build_background_worker_catalog(registry: ModuleRegistry) -> BackgroundWorkerCatalog:
     definitions: list[BackgroundWorkerDefinition] = []
     owners: dict[str, ModuleKey] = {}
-    declarations: list[tuple[type[AppModule], str, tuple[object, ...]]] = []
-    for descriptor in registry.dependency_order:
-        for attribute in ("background_workers", "background_worker_definitions"):
-            declared = descriptor.module_type.__dict__.get(attribute, ())
-            if not isinstance(declared, tuple):
+    for descriptor, declaration in registry.declarations(BackgroundWorkers):
+        if not isinstance(declaration.workers, tuple):
+            raise BackgroundWorkerDefinitionError(
+                worker=str(descriptor.key),
+                reason="workers must be an immutable tuple",
+            )
+        for candidate in declaration.workers:
+            definition = _interpret_worker(candidate)
+            previous = owners.get(definition.name)
+            if previous is not None:
                 raise BackgroundWorkerDefinitionError(
-                    worker=str(descriptor.key),
-                    reason=f"Module {attribute} must be an immutable tuple",
+                    worker=definition.name,
+                    reason=f"worker is already owned by {previous}",
                 )
-            declarations.append((descriptor.module_type, attribute, declared))
-            for candidate in declared:
-                definition = _interpret_worker(candidate, attribute)
-                previous = owners.get(definition.name)
-                if previous is not None:
-                    raise BackgroundWorkerDefinitionError(
-                        worker=definition.name,
-                        reason=f"worker is already owned by {previous}",
-                    )
-                owners[definition.name] = descriptor.key
-                definitions.append(definition)
+            owners[definition.name] = descriptor.key
+            definitions.append(definition)
     return BackgroundWorkerCatalog(
         tuple(definitions),
         owners=owners,
-        declarations=tuple(declarations),
     )
 
 
-def _interpret_worker(candidate: object, attribute: str) -> BackgroundWorkerDefinition:
-    if attribute == "background_workers":
-        if isinstance(candidate, type) and issubclass(candidate, BackgroundWorker):
-            return _definition_from_type(candidate)
-    elif isinstance(candidate, BackgroundWorkerDefinition) and not isinstance(
+def _interpret_worker(candidate: object) -> BackgroundWorkerDefinition:
+    if isinstance(candidate, type) and issubclass(candidate, BackgroundWorker):
+        return _definition_from_type(candidate)
+    if isinstance(candidate, BackgroundWorkerDefinition) and not isinstance(
         candidate.worker_type, type
     ):
         return candidate
     raise BackgroundWorkerDefinitionError(
-        worker=attribute,
-        reason="background_workers requires Worker types; definitions require async functions",
+        worker=str(candidate),
+        reason="workers requires Worker types or definitions of async functions",
     )

python_ddd_framework/background_workers/contracts.py

@@ -11,6 +11,7 @@ from datetime import timedelta
 from enum import Enum
 from typing import ClassVar, cast
 
+from dishka import Scope
 from pydantic import ConfigDict, Field, field_serializer
 
 from ..background_execution import BackgroundJobOptions, BackgroundTaskOptions
@@ -53,6 +54,8 @@ class BackgroundExecutionOptions(BaseOptions):
 class BackgroundWorker(ABC):
     """一次 iteration 的实现边界；永久 loop 由 Application coordinator 独占。"""
 
+    _fixed_service_scope: ClassVar[Scope] = Scope.ACTION
+
     name: ClassVar[str]
     interval: ClassVar[timedelta]
     iteration_timeout: ClassVar[timedelta]

python_ddd_framework/background_workers/execution.py

@@ -9,12 +9,12 @@ from uuid import uuid4
 
 from dishka import AsyncContainer, Scope
 
-from ..application_services.contracts import _DEFAULT_CONNECTION_NAME
 from ..application_services.errors import ApplicationInvocationRejectedError
 from ..application_services.invocation import _InvocationRuntime
 from ..authorization import CurrentUser
 from ..background_execution.lifecycle import _TaskExecution
 from ..invocation import BackgroundSystemCaller
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
 from .contracts import BackgroundWorkerContext, BackgroundWorkerDefinition
 
 _LOGGER = logging.getLogger(__name__)

python_ddd_framework/background_workers/runtime.py

@@ -16,18 +16,56 @@ from ..background_execution import (
     BackgroundTaskOptions,
     BackgroundTaskSnapshot,
 )
-from ..background_execution.lifecycle import _BackgroundRuntimeFailure, _TaskExecution
+from ..background_execution.lifecycle import (
+    _BackgroundExecutionStartFailure,
+    _BackgroundRuntimeFailure,
+    _TaskExecution,
+)
 from ..background_execution.local import _LocalTask
 from ..background_execution.locks import _check_previous_owners
 from ..background_execution.processes import _ProcessSlot
 from ..background_jobs import BackgroundJobCatalog
+from ..errors.lifecycle import ApplicationRuntimeError
 from ..invocation import BackgroundSystemCaller
+from ..lifecycle import RuntimeParticipant, ShutdownReason
 from .catalog import BackgroundWorkerCatalog
 from .contracts import BackgroundExecutionOptions, BackgroundExecutionProfile
 from .execution import _WorkerExecution
 
 
 class _BackgroundCoordinator:
+    def runtime_participant(self) -> RuntimeParticipant:
+        def prepare(run_services: bool) -> None:
+            if not run_services:
+                self.disable_for_database()
+
+        async def start() -> None:
+            try:
+                await self.start()
+            except BaseException as error:
+                raise _BackgroundExecutionStartFailure(original_error=error) from error
+
+        async def stop(reason: ShutdownReason) -> tuple[BaseException, ...]:
+            return ()
+
+        async def wait() -> ApplicationRuntimeError:
+            failure = await self.wait_for_runtime_failure()
+            error = ApplicationRuntimeError(
+                component=failure.component,
+                error_type=failure.error_type,
+            )
+            error._source = failure._source
+            return error
+
+        return RuntimeParticipant(
+            prepare=prepare,
+            start=start,
+            stop=stop,
+            quiesce=self.quiesce,
+            drain=self.stop,
+            failure=lambda: wait() if self.has_runtime_failure_source else None,
+        )
+
     def __init__(
         self,
         *,
@@ -205,6 +243,14 @@ class _BackgroundCoordinator:
             return slot.request(key, start)
         return self._tasks[key].request(start)
 
+    def quiesce(self) -> None:
+        self._started = False
+        for key, task in self._tasks.items():
+            if key in self._local:
+                task.quiesce()
+        for slot in self._slots.values():
+            slot.quiesce()
+
     async def stop(self) -> None:
         # 即使启动前的预占或 Module 初始化失败，也必须释放已取得的位置。
         operations = [task.shutdown() for key, task in self._tasks.items() if key in self._local]

python_ddd_framework/caching/__init__.py

@@ -1,11 +1,12 @@
-from .catalog import CacheCatalog
-from .contracts import CacheDefinition, DistributedCache
-from .errors import CacheDefinitionError, DistributedCacheError
+from .contracts import DistributedCache
+from .errors import DistributedCacheError
+from .naming import cache_name
+from .options import DistributedCacheEntryOptions, DistributedCacheOptions
 
 __all__ = (
-    "CacheCatalog",
-    "CacheDefinition",
-    "CacheDefinitionError",
     "DistributedCache",
+    "DistributedCacheEntryOptions",
     "DistributedCacheError",
+    "DistributedCacheOptions",
+    "cache_name",
 )