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

python_ddd_framework/application_services/module.py

@@ -0,0 +1,168 @@
+"""应用服务发现、最终实现策略和 REQUEST 到 ACTION 代理的组装 owner。"""
+
+from typing import cast
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
+
+from ..auditing.module import AuditingModule
+from ..authorization.module import AuthorizationModule
+from ..extensions.module import ExtensionsModule
+from ..invocation.interceptors import InterceptionStage
+from ..invocation.module import InvocationModule
+from ..invocation.validation import _validate_interceptor_scopes
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..modularity.discovery import _is_concrete_implementation
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceConvention,
+    ServiceDiscoveryContext,
+    ServiceValidationContext,
+)
+from ..services.convention_contracts import (
+    _SERVICE_DEFINITION_ATTRIBUTE,
+    ConventionDiscoveryKind,
+    _ServiceDefinition,
+)
+from ..settings.module import SettingsModule
+from ..unit_of_work.module import UnitOfWorkModule
+from .bindings import (
+    _bind_application_services,
+    _runtime_providers,
+    _validate_application_service_bindings,
+    _validate_application_service_dependencies,
+)
+from .catalog import (
+    ApplicationServiceCatalog,
+    _build_application_service_catalog,
+    _DiscoveredApplicationService,
+)
+from .contracts import (
+    _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE,
+    ApplicationService,
+    _definition_for,
+)
+from .dispatcher import _ApplicationServiceDispatcher, _proxy_factory
+from .errors import ApplicationServiceDefinitionError
+from .invocation import _ScopedApplicationServiceInvoker
+
+
+class ApplicationServicesModule(AppModule):
+    dependencies = (
+        InvocationModule,
+        UnitOfWorkModule,
+        AuthorizationModule,
+        AuditingModule,
+        SettingsModule,
+    )
+    catalog: ApplicationServiceCatalog
+
+    def __init__(self) -> None:
+        self._discoveries: list[_DiscoveredApplicationService] = []
+        self._proxy_factories: dict[DependencyKey, object] = {}
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_composition(
+            ServiceComposition(
+                discover=self._discover,
+                bind=self._bind,
+                validate=self._validate,
+            )
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        seen: set[tuple[object, type[object]]] = set()
+        for discovery in context.discoveries:
+            candidate = discovery.candidate
+            identity = (discovery.owner, candidate)
+            if identity in seen or not _is_concrete_implementation(candidate):
+                continue
+            seen.add(identity)
+            definition = _definition_for(candidate)
+            if definition is None:
+                continue
+            if _SERVICE_DEFINITION_ATTRIBUTE in candidate.__dict__:
+                raise ApplicationServiceDefinitionError(
+                    symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+                    reason="application_service and service metadata cannot be combined",
+                )
+            decorated = _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE in candidate.__dict__
+            context.conventions[discovery.owner, candidate] = ServiceConvention(
+                _ServiceDefinition(provides=definition.contract or candidate, scope=Scope.ACTION),
+                ConventionDiscoveryKind.APPLICATION_SERVICE_DECORATOR
+                if decorated
+                else ConventionDiscoveryKind.FRAMEWORK_MARKER,
+                "accepted from immutable application_service decorator metadata"
+                if decorated
+                else "accepted from unique inherited ApplicationService contract",
+            )
+            # 公开契约仍由扫描该契约的 Module 拥有；实现所在模块不是第二个契约 owner。
+            declarations = {
+                item.owner: item
+                for item in context.discoveries
+                if item.candidate is definition.contract
+            }
+            if len(declarations) > 1:
+                raise ApplicationServiceDefinitionError(
+                    symbol=str(definition.contract),
+                    reason="application service contract is scanned by multiple Modules",
+                )
+            declaration = next(iter(declarations.values()), discovery)
+            self._discoveries.append(
+                _DiscoveredApplicationService(
+                    service_type=cast(type[ApplicationService], candidate),
+                    definition=definition,
+                    owner=declaration.owner,
+                    source=declaration.source,
+                    declaration_index=len(self._discoveries),
+                )
+            )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        bound = _bind_application_services(tuple(self._discoveries), context.arbitration.drafts)
+        _validate_application_service_dependencies(
+            context.modules, bound, context.arbitration.drafts
+        )
+        self.catalog = _build_application_service_catalog(
+            tuple(item.binding for item in bound),
+            context.modules.instance(AuthorizationModule).catalog,
+            context.modules.instance(InvocationModule).rules,
+            context.modules.instance(ExtensionsModule).catalog,
+        )
+        # 只重定位仲裁后的原生绑定，保留其他能力已经生成的目录 Provider。
+        for provider in context.arbitration.providers:
+            context._providers.remove(provider)
+        context._providers[0:0] = _runtime_providers(context.arbitration, bound)
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=ApplicationServiceCatalog, scope=Scope.APP)
+        provider.provide(_ApplicationServiceDispatcher, scope=Scope.REQUEST)
+        provider.provide(_ScopedApplicationServiceInvoker, scope=Scope.APP)
+        for registration in self.catalog.registrations:
+            factory = _proxy_factory(self.catalog._for_registration(registration))
+            self._proxy_factories[DependencyKey(registration.contract, DEFAULT_COMPONENT)] = factory
+            provider.provide(
+                factory,
+                provides=registration.contract,
+                scope=Scope.REQUEST,
+            )
+        context.add_provider(provider)
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        _validate_application_service_bindings(
+            context.native_graph, self.catalog, self._proxy_factories
+        )
+        _validate_interceptor_scopes(
+            context.native_graph,
+            (
+                (
+                    registration,
+                    Scope.ACTION
+                    if registration.before is InterceptionStage.METHOD
+                    else Scope.REQUEST,
+                )
+                for service in self.catalog.registrations
+                for method in service.methods
+                for registration in method.interceptors
+            ),
+        )

python_ddd_framework/application_services/pagination.py

@@ -0,0 +1,21 @@
+"""标准分页 DTO；默认值只在输入契约声明。"""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+_T = TypeVar("_T")
+
+
+class PagedResultRequestDto(BaseModel):
+    skip_count: int = Field(default=0, ge=0)
+    max_result_count: int = Field(default=10, ge=1, le=1000)
+
+
+class PagedAndSortedResultRequestDto(PagedResultRequestDto):
+    sorting: str | None = None
+
+
+class PagedResult(BaseModel, Generic[_T]):
+    items: list[_T]
+    total_count: int = Field(ge=0)

python_ddd_framework/auditing/control.py

@@ -9,7 +9,7 @@ from typing import TypeVar
 
 from pydantic import ConfigDict
 
-from ..application_services.policies import _declare_switch
+from ..invocation.policies import _declare_switch
 from ..options import BaseOptions
 
 _T = TypeVar("_T")

python_ddd_framework/auditing/module.py

@@ -0,0 +1,15 @@
+"""审计默认配置与 Application-local 控制状态的 owner。"""
+
+from dishka import Provider, Scope
+
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from .control import AuditingControl, AuditingOptions
+
+
+class AuditingModule(AppModule):
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure.default(AuditingOptions, section="auditing")
+        provider = Provider()
+        provider.provide(AuditingControl, scope=Scope.APP)
+        context.services.contribute(provider, reason="Application-local auditing control")

python_ddd_framework/authorization/__init__.py

@@ -17,10 +17,12 @@ from .errors import (
     PermissionDeniedError,
     UnauthenticatedError,
 )
+from .options import AuthorizationOptions
 
 __all__ = (
     "AccessTokenAuthenticator",
     "AuthorizationDefinitionError",
+    "AuthorizationOptions",
     "CurrentUser",
     "PermissionCatalog",
     "PermissionChecker",

python_ddd_framework/authorization/contracts.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Protocol, TypeVar, runtime_checkable
 from uuid import UUID
 
+from ..modularity import ModuleDeclaration, ModuleRef
 from .errors import AuthorizationDefinitionError, PermissionDefinitionError
 
 _AUTHORIZATION_ATTRIBUTE = "__python_ddd_framework_authorization__"
@@ -129,9 +130,13 @@ class AccessTokenAuthenticator(Protocol):
 
 
 @dataclass(frozen=True, slots=True)
-class _AuthorizationMetadata:
+class _AuthorizationMetadata(ModuleDeclaration):
     permissions: tuple[PermissionName, ...]
 
+    @property
+    def required_module(self) -> ModuleRef:
+        return ModuleRef("python_ddd_framework.authorization.module:AuthorizationModule")
+
 
 @dataclass(frozen=True, slots=True)
 class _AuthorizationRequirement:
@@ -228,7 +233,7 @@ def _metadata_for(target: object) -> _AuthorizationMetadata | None:
 
 
 def _validate_authorization_target(target: object) -> None:
-    if not isinstance(target, type) and not callable(target):
+    if not isinstance(target, (type, staticmethod, classmethod)) and not callable(target):
         raise AuthorizationDefinitionError(
             symbol=repr(target),
             reason="authorization decorator target must be a class or callable",

python_ddd_framework/authorization/definitions.py

@@ -5,11 +5,16 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 
 from ..diagnostics import SourceLocation
+from ..modularity import ModuleRef, ModuleRequirement
 from .contracts import PermissionDefinition
 from .errors import PermissionDefinitionError
 
 
 class PermissionDefinitionProvider(ABC):
+    __authorization_module__ = ModuleRequirement(
+        ModuleRef("python_ddd_framework.authorization.module:AuthorizationModule")
+    )
+
     @abstractmethod
     def define(self, context: PermissionDefinitionContext) -> None:
         """同步贡献静态权限定义；无构造注入、I/O 或运行期服务解析。"""

python_ddd_framework/authorization/module.py

@@ -0,0 +1,40 @@
+"""权限声明与当前身份的注册 owner；认证和存储实现由 Host 选择。"""
+
+from dishka import Provider, Scope
+
+from ..application_services.invocation import _InvocationRuntime
+from ..invocation.module import InvocationModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceDiscoveryContext,
+)
+from .catalog import PermissionCatalog, _build_permission_catalog
+from .contracts import CurrentUser
+from .options import AuthorizationOptions
+
+
+class AuthorizationModule(AppModule):
+    dependencies = (InvocationModule,)
+    catalog: PermissionCatalog
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure.default(AuthorizationOptions, section="authorization")
+        context.services.add_composition(
+            ServiceComposition(discover=self._discover, bind=self._bind)
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        self.catalog = _build_permission_catalog(context.modules, context.discoveries)
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=PermissionCatalog, scope=Scope.APP)
+        provider.provide(_current_user, provides=CurrentUser, scope=Scope.REQUEST)
+        context.add_provider(provider)
+
+
+def _current_user(runtime: _InvocationRuntime) -> CurrentUser:
+    return runtime.current_user()

python_ddd_framework/authorization/options.py

@@ -0,0 +1,7 @@
+"""Host-owned 授权策略；不改变认证和业务身份。"""
+
+from ..options import BaseOptions
+
+
+class AuthorizationOptions(BaseOptions):
+    always_allow: bool = False

python_ddd_framework/background_execution/child.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 import asyncio
 from typing import TYPE_CHECKING
 
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..hosted_services.runtime import _HostedServiceCoordinator
+
 if TYPE_CHECKING:
     from multiprocessing.connection import _ConnectionBase as Connection
 
@@ -51,8 +54,10 @@ async def _serve_child(
     pipe: Connection,
 ) -> None:
     application = spec.build()
-    application._root.require_hosted_service_coordinator().select_child()
-    coordinator = application._root.require_background_coordinator()
+    container = application._container_for_integration()
+    hosted = await container.get(_HostedServiceCoordinator)
+    hosted.select_child()
+    coordinator = await container.get(_BackgroundCoordinator)
     coordinator.select_child(tasks, initial)
     try:
         await _start_while_parent_present(application, pipe)
@@ -91,7 +96,12 @@ async def _start_while_parent_present(application: Application, pipe: Connection
         await application.start()
         # 启动确认与 start 返回处于同一 task 连续段；首轮业务崩溃不能被误判为初始化失败。
         pipe.send(
-            (_Message.SNAPSHOTS, application._root.require_background_coordinator().snapshots())
+            (
+                _Message.SNAPSHOTS,
+                (
+                    await application._container_for_integration().get(_BackgroundCoordinator)
+                ).snapshots(),
+            )
         )
         pipe.send((_Message.READY,))
 

python_ddd_framework/background_execution/declarations.py

@@ -0,0 +1,45 @@
+"""后台执行的模块声明；任务身份和调度事实仍由原有定义契约校验。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from ..modularity import ModuleDeclaration, ModuleDependency, ModuleRef
+
+if TYPE_CHECKING:
+    from ..background_jobs import BackgroundJobDefinition, BackgroundJobSchedule
+    from ..background_workers.contracts import BackgroundWorker, BackgroundWorkerDefinition
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundWorkers(ModuleDeclaration):
+    workers: tuple[type[BackgroundWorker] | BackgroundWorkerDefinition, ...]
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef(
+            "python_ddd_framework.background_execution.module:BackgroundExecutionModule"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundJobs(ModuleDeclaration):
+    definitions: tuple[BackgroundJobDefinition[Any], ...]
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef(
+            "python_ddd_framework.background_execution.module:BackgroundExecutionModule"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundSchedules(ModuleDeclaration):
+    schedules: tuple[BackgroundJobSchedule[Any], ...]
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef(
+            "python_ddd_framework.background_execution.module:BackgroundExecutionModule"
+        )

python_ddd_framework/background_execution/lifecycle.py

@@ -5,6 +5,18 @@ from __future__ import annotations
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 
+from ..errors import FrameworkError
+
+
+class _BackgroundExecutionStartFailure(FrameworkError):
+    """后台启动错误归能力 owner；不伪造 Module hook 的诊断位置。"""
+
+    def __init__(self, *, original_error: BaseException) -> None:
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Background execution start failed with {type(original_error).__name__}")
+
 
 @dataclass(frozen=True, slots=True)
 class _BackgroundRuntimeFailure:

python_ddd_framework/background_execution/local.py

@@ -30,12 +30,19 @@ class _LocalTask:
         self.operation: asyncio.Task[None] | None = None
         self._failed = failed
         self._monitor: asyncio.Task[None] | None = None
+        self._quiescing = False
+        self._claiming_stopped = False
 
     async def start(self) -> None:
+        self._claiming_stopped = False
         self.state = BackgroundTaskState.STARTING
         if self.execution is None:
             raise RuntimeError("Task execution provider is unavailable")
         await self.execution.start()
+        if self._quiescing:
+            # start 可能与关闭重叠；完成后再次请求停止，不能重新打开领取。
+            self._claiming_stopped = False
+            self._stop_claiming()
         self.state = BackgroundTaskState.RUNNING
         if self.execution.wait_for_failure is not None:
             self._monitor = asyncio.create_task(
@@ -82,6 +89,9 @@ class _LocalTask:
     async def _operate(self, start: bool) -> None:
         try:
             if start:
+                if self._quiescing:
+                    self.state = BackgroundTaskState.STOPPED
+                    return
                 await self.start()
             else:
                 await self._drain()
@@ -91,6 +101,15 @@ class _LocalTask:
             self.state = BackgroundTaskState.FAILED
             # 失败转为 Application-owned 状态供查询；task 不留下未观察异常。
 
+    def quiesce(self) -> None:
+        self._quiescing = True
+        self._stop_claiming()
+
+    def _stop_claiming(self) -> None:
+        if self.execution is not None and not self._claiming_stopped:
+            self._claiming_stopped = True
+            self.execution.stop_claiming()
+
     async def shutdown(self) -> None:
         if self.operation is not None:
             await self.operation
@@ -112,7 +131,7 @@ class _LocalTask:
         execution = self.execution
         if execution is None:
             return
-        execution.stop_claiming()
+        self._stop_claiming()
         draining = asyncio.ensure_future(execution.wait())
         _, pending = await asyncio.wait((draining,), timeout=self.deadline)
         if pending:

python_ddd_framework/background_execution/module.py

@@ -1,9 +1,115 @@
-"""后台管理由 Host 显式选择，业务任务声明保持独立。"""
+"""后台 Worker/Job 的组装与运行 owner；执行模式仍由 Host 配置决定。"""
 
+from dishka import Provider, Scope
+
+from ..background_jobs import BackgroundJobCatalog
+from ..background_jobs.catalog import _build_background_job_catalog
+from ..background_workers import BackgroundWorkerCatalog
+from ..background_workers.catalog import _build_background_worker_catalog
+from ..background_workers.contracts import BackgroundExecutionOptions
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..hosted_services.module import HostedServicesModule
+from ..invocation import BackgroundSystemCaller
+from ..invocation.interception import InvocationEntry
+from ..invocation.module import InvocationModule
+from ..lifecycle import ConfigureContext
 from ..modularity import AppModule
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceDiscoveryContext,
+    ServiceValidationContext,
+)
+from ..unit_of_work.options import UnitOfWorkDeclaration
+
+
+class BackgroundExecutionModule(AppModule):
+    dependencies = (HostedServicesModule,)
+    workers: BackgroundWorkerCatalog
+    jobs: BackgroundJobCatalog
+    coordinator: _BackgroundCoordinator
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.configure.default(BackgroundExecutionOptions, section="background_execution")
+        context.services.add_composition(
+            ServiceComposition(
+                discover=self._discover,
+                bind=self._bind,
+                validate=self._validate,
+            )
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        self.workers = _build_background_worker_catalog(context.modules)
+        self.jobs = _build_background_job_catalog(context.modules, context.discoveries)
+        # 默认实现也经过统一仲裁，显式替换后只保留最终获选的原生 binding。
+        targets = dict.fromkeys(
+            [
+                (item.worker_type, self.workers.owner_for(item.name))
+                for item in self.workers.definitions
+            ]
+            + [(item.handler_type, self.jobs.owner_for(item)) for item in self.jobs.definitions]
+        )
+        for target, owner in targets:
+            if not isinstance(target, type):
+                continue
+            provider = Provider()
+            provider.provide(target, scope=Scope.ACTION)
+            context.services._add_framework_default(
+                provider=provider,
+                owner=owner,
+                source=context.modules.descriptors[owner].declaration_source,
+                reason="Background entry default implementation",
+            )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        invocation = context.modules.instance(InvocationModule)
+        self.coordinator = _BackgroundCoordinator(
+            worker_catalog=self.workers,
+            job_catalog=self.jobs,
+            options=context.options.get(BackgroundExecutionOptions),
+            invocation_runtime=invocation.invocation_runtime,
+            build_spec=context.build_spec,
+        )
+        self.runtime = self.coordinator.runtime_participant()
+        for worker in self.workers.definitions:
+            invocation.entries.append(
+                InvocationEntry(
+                    worker.worker_type,
+                    "run_iteration",
+                    self.workers.owner_for(worker.name),
+                    1,
+                    unit_of_work_default=UnitOfWorkDeclaration(disabled=True),
+                )
+            )
+        for job in self.jobs.definitions:
+            invocation.entries.append(
+                InvocationEntry(
+                    job.handler_type,
+                    "execute",
+                    self.jobs.owner_for(job),
+                    2,
+                )
+            )
+        provider = Provider()
+        provider.provide(lambda: self.workers, provides=BackgroundWorkerCatalog, scope=Scope.APP)
+        provider.provide(lambda: self.jobs, provides=BackgroundJobCatalog, scope=Scope.APP)
+        provider.provide(lambda: self.coordinator, provides=_BackgroundCoordinator, scope=Scope.APP)
+        provider.provide(
+            lambda: self.coordinator.system_caller,
+            provides=BackgroundSystemCaller,
+            scope=Scope.APP,
+        )
+        context.add_provider(provider)
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        self.coordinator.attach_container(context.container)
 
 
 class BackgroundManagementModule(AppModule):
+    """管理接口由 Host 选择；任务声明不因此自动暴露管理入口。"""
+
+    dependencies = (BackgroundExecutionModule,)
     scan_packages = (
         "python_ddd_framework.background_execution.application",
         "python_ddd_framework.background_execution.permissions",

python_ddd_framework/background_execution/processes.py

@@ -60,6 +60,7 @@ class _ProcessSlot:
         self._exited = asyncio.Event()
         self._exited.set()
         self._stopping = False
+        self._shutdown_request: asyncio.Task[None] | None = None
         self._restart_count = 0
         self._wanted: set[str] = set()
         self._serial = 0
@@ -307,14 +308,23 @@ class _ProcessSlot:
                 if not self._stopping and self._wanted and self._process is None:
                     self._spawn()
 
-    async def shutdown(self) -> None:
+    def quiesce(self) -> None:
         self._stopping = True
         self._set_enabled_state(BackgroundTaskState.STOPPING)
+        if self._shutdown_request is None:
+            self._shutdown_request = asyncio.create_task(self._request_shutdown())
+
+    async def _request_shutdown(self) -> None:
         if self._process is not None and self._process.is_alive():
             try:
                 await self._send((_Message.SHUTDOWN,))
             except (EOFError, OSError):
                 pass
+
+    async def shutdown(self) -> None:
+        self.quiesce()
+        assert self._shutdown_request is not None
+        await self._shutdown_request
         if self._monitor is not None:
             await self._monitor
         if self._operations: