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

python_ddd_framework/invocation/methods.py

@@ -0,0 +1,345 @@
+"""受管理异步方法的共享描述、策略解释与参数编译。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any, cast, get_type_hints
+
+from pydantic import ConfigDict, TypeAdapter, validate_call
+
+from ..application_services.errors import (
+    ApplicationServiceDefinitionError,
+)
+from ..auditing.control import _AUDITING_ATTRIBUTE
+from ..authorization import PermissionCatalog, PermissionName
+from ..authorization.contracts import (
+    _ALLOW_ANONYMOUS_ATTRIBUTE,
+    _AUTHORIZATION_ATTRIBUTE,
+    _authorization_requirement,
+    _AuthorizationRequirement,
+)
+from ..authorization.errors import AuthorizationDefinitionError
+from ..diagnostics import SourceLocation
+from ..extensions.catalog import ExtensionCatalog
+from ..invocation.interceptors import InterceptionStage, InterceptorRegistration, _InterceptorRule
+from ..invocation.signature import _business_signature
+from ..modularity import ModuleKey
+from ..unit_of_work.options import _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration, _declaration
+from .policies import _VALIDATION_ATTRIBUTE, ValidationEnabled, _effective_switch
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceMethod:
+    name: str
+    source: SourceLocation
+    requires_authenticated_user: bool
+    permissions: tuple[PermissionName, ...]
+    allows_anonymous: bool
+    service: type[object]
+    implementation: type[object]
+    method: Callable[..., Awaitable[object]]
+    validation_enabled: bool
+    auditing_enabled: bool
+    policy_sources: tuple[SourceLocation, ...]
+    interceptors: tuple[InterceptorRegistration, ...] = ()
+    unit_of_work: UnitOfWorkDeclaration = field(default_factory=UnitOfWorkDeclaration)
+
+
+_ValidatedArguments = tuple[tuple[object, ...], dict[str, object]]
+
+
+@dataclass(frozen=True, slots=True)
+class _CompiledMethod:
+    name: str
+    contract_method: Callable[..., Awaitable[object]]
+    implementation_method: Callable[..., Awaitable[object]]
+    validator: Callable[..., Awaitable[_ValidatedArguments]]
+    parameter_names: frozenset[str]
+    authorization: _AuthorizationRequirement
+    descriptor: ServiceMethod
+    signature: inspect.Signature
+    implementation_signature: inspect.Signature
+    interceptor_steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]]
+    policy_fingerprint: tuple[object, ...]
+    result_adapter: TypeAdapter[object] | None = None
+
+
+def _compile_method(
+    contract: type[object],
+    implementation: type[object],
+    name: str,
+    owner: ModuleKey,
+    implementation_owner: ModuleKey,
+    permission_catalog: PermissionCatalog | None,
+    interceptor_rules: tuple[_InterceptorRule, ...],
+    *,
+    validation_default: bool = True,
+    auditing_default: bool = True,
+    unit_of_work_default: UnitOfWorkDeclaration,
+    extensions: ExtensionCatalog,
+) -> _CompiledMethod:
+    implementation_symbol = f"{implementation.__module__}.{implementation.__qualname__}"
+    contract_method = _require_async_instance_method(contract, name, role="contract")
+    implementation_method = _require_async_instance_method(
+        implementation,
+        name,
+        role="implementation",
+    )
+    contract_signature, annotations = _resolved_signature(contract_method)
+    implementation_signature, _ = _resolved_signature(implementation_method)
+    if contract_signature.return_annotation is inspect.Signature.empty:
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{implementation_symbol}.{name}",
+            reason="public service methods must declare a return annotation",
+        )
+    if _business_signature(contract_signature) != _business_signature(implementation_signature):
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{implementation_symbol}.{name}",
+            reason="implementation signature must exactly match its public contract",
+        )
+    declared_return = contract_signature.return_annotation
+    annotations = {name: extensions.annotation(value) for name, value in annotations.items()}
+    contract_signature = contract_signature.replace(
+        parameters=tuple(
+            parameter.replace(annotation=extensions.annotation(parameter.annotation))
+            for parameter in contract_signature.parameters.values()
+        ),
+        return_annotation=extensions.annotation(declared_return),
+    )
+    try:
+        validator = _compile_argument_validator(
+            contract_method,
+            contract_signature,
+            annotations,
+        )
+    except Exception as original_error:
+        raise ApplicationServiceDefinitionError(
+            symbol=f"{contract.__module__}.{contract.__qualname__}.{name}",
+            reason=f"Pydantic could not compile the method: {type(original_error).__name__}",
+        ) from None
+    source = _method_source(contract_method, owner)
+    authorization = _authorization_requirement(implementation, implementation_method)
+    unknown_permissions = tuple(
+        permission
+        for permission in authorization.permissions
+        if permission_catalog is None or permission not in permission_catalog
+    )
+    if unknown_permissions:
+        raise AuthorizationDefinitionError(
+            symbol=f"{contract.__module__}.{contract.__qualname__}.{name}",
+            reason=(
+                "authorization references unknown permissions: "
+                f"{tuple(str(item) for item in unknown_permissions)!r}"
+            ),
+        )
+    descriptor = ServiceMethod(
+        name=name,
+        source=source,
+        requires_authenticated_user=authorization.requires_authenticated_user,
+        permissions=authorization.permissions,
+        allows_anonymous=authorization.allows_anonymous,
+        service=contract,
+        implementation=implementation,
+        method=implementation_method,
+        unit_of_work=_declaration(implementation, implementation_method)
+        if any(
+            hasattr(item, _UNIT_OF_WORK_ATTRIBUTE)
+            for item in (implementation, implementation_method)
+        )
+        else unit_of_work_default,
+        validation_enabled=_effective_switch(
+            implementation, implementation_method, _VALIDATION_ATTRIBUTE, validation_default
+        ),
+        auditing_enabled=_effective_switch(
+            implementation, implementation_method, _AUDITING_ATTRIBUTE, auditing_default
+        ),
+        policy_sources=_policy_sources(implementation, implementation_method, implementation_owner),
+    )
+    descriptor = replace(
+        descriptor, interceptors=_match_interceptors(descriptor, interceptor_rules)
+    )
+    return _CompiledMethod(
+        name=name,
+        contract_method=contract_method,
+        implementation_method=implementation_method,
+        validator=validator,
+        parameter_names=frozenset(tuple(contract_signature.parameters)[1:]),
+        authorization=authorization,
+        descriptor=descriptor,
+        signature=contract_signature,
+        implementation_signature=implementation_signature.replace(
+            parameters=tuple(
+                parameter.replace(annotation=extensions.annotation(parameter.annotation))
+                for parameter in implementation_signature.parameters.values()
+            ),
+            return_annotation=extensions.annotation(implementation_signature.return_annotation),
+        ),
+        result_adapter=TypeAdapter(contract_signature.return_annotation)
+        if contract_signature.return_annotation != declared_return
+        else None,
+        policy_fingerprint=_policy_fingerprint(implementation, implementation_method),
+        interceptor_steps=MappingProxyType(
+            {
+                stage: tuple(item for item in descriptor.interceptors if item.before is stage)
+                for stage in InterceptionStage
+            }
+        ),
+    )
+
+
+_POLICY_ATTRIBUTES = (
+    _UNIT_OF_WORK_ATTRIBUTE,
+    _AUTHORIZATION_ATTRIBUTE,
+    _ALLOW_ANONYMOUS_ATTRIBUTE,
+    _VALIDATION_ATTRIBUTE,
+    _AUDITING_ATTRIBUTE,
+)
+
+
+def _policy_fingerprint(implementation: type[object], method: object) -> tuple[object, ...]:
+    return (
+        issubclass(implementation, ValidationEnabled),
+        tuple(
+            tuple(vars(target).get(attribute) for attribute in _POLICY_ATTRIBUTES)
+            for target in (*implementation.__mro__, method)
+            if any(attribute in vars(target) for attribute in _POLICY_ATTRIBUTES)
+        ),
+    )
+
+
+def _policy_sources(
+    implementation: type[object], method: Callable[..., Any], owner: ModuleKey
+) -> tuple[SourceLocation, ...]:
+    return tuple(
+        _method_source(target, owner)
+        for target in (*reversed(implementation.__mro__), method)
+        if any(attribute in vars(target) for attribute in _POLICY_ATTRIBUTES)
+    )
+
+
+def _match_interceptors(
+    method: ServiceMethod, rules: tuple[_InterceptorRule, ...]
+) -> tuple[InterceptorRegistration, ...]:
+    matched: list[InterceptorRegistration] = []
+    for rule in rules:
+        try:
+            accepted = rule.match(method)
+            if not isinstance(accepted, bool):
+                raise TypeError("interceptor match must return bool")
+        except Exception as error:
+            raise ApplicationServiceDefinitionError(
+                symbol=rule.registration.source.symbol
+                or rule.registration.interceptor.__qualname__,
+                reason=(
+                    f"interceptor match failed for {rule.registration.owner}: "
+                    f"{type(error).__name__}"
+                ),
+            ) from None
+        if accepted:
+            matched.append(rule.registration)
+    return tuple(sorted(matched, key=lambda item: tuple(InterceptionStage).index(item.before)))
+
+
+def _public_method_names(candidate: type[object], *, is_contract: bool) -> tuple[str, ...]:
+    names: dict[str, None] = {}
+    for owner in reversed(candidate.__mro__):
+        if owner is object:
+            continue
+        if is_contract and owner.__module__ == "typing":
+            continue
+        for name, value in owner.__dict__.items():
+            if name.startswith("_"):
+                continue
+            if inspect.isfunction(value) or isinstance(value, (staticmethod, classmethod)):
+                names[name] = None
+    return tuple(names)
+
+
+def _require_async_instance_method(
+    owner: type[object],
+    name: str,
+    *,
+    role: str,
+) -> Callable[..., Awaitable[object]]:
+    symbol = f"{owner.__module__}.{owner.__qualname__}.{name}"
+    descriptor = inspect.getattr_static(owner, name)
+    if isinstance(descriptor, (staticmethod, classmethod)):
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must be instance methods",
+        )
+    method = getattr(owner, name)
+    if not inspect.isfunction(method) or not inspect.iscoroutinefunction(method):
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must use async def",
+        )
+    parameters = tuple(inspect.signature(method).parameters.values())
+    if not parameters or parameters[0].kind not in (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    ):
+        # Catalog 与 HTTP generator 都会剥离 receiver；缺少首个位置参数时不能伪装成实例方法。
+        raise ApplicationServiceDefinitionError(
+            symbol=symbol,
+            reason=f"public {role} methods must declare an instance receiver",
+        )
+    return cast(Callable[..., Awaitable[object]], method)
+
+
+def _resolved_signature(
+    method: Callable[..., Awaitable[object]],
+) -> tuple[inspect.Signature, dict[str, object]]:
+    annotations = get_type_hints(method, include_extras=True)
+    signature = inspect.signature(method)
+    parameters = tuple(
+        parameter.replace(annotation=annotations.get(name, parameter.annotation))
+        for name, parameter in signature.parameters.items()
+    )
+    resolved = signature.replace(
+        parameters=parameters,
+        return_annotation=annotations.get("return", signature.return_annotation),
+    )
+    return resolved, annotations
+
+
+def _compile_argument_validator(
+    method: Callable[..., Awaitable[object]],
+    signature: inspect.Signature,
+    annotations: Mapping[str, object],
+) -> Callable[..., Awaitable[_ValidatedArguments]]:
+    async def capture(*args: object, **kwargs: object) -> _ValidatedArguments:
+        # 第一个值是 validation-only self sentinel；业务 implementation 尚未解析或执行。
+        return tuple(args[1:]), dict(kwargs)
+
+    capture.__name__ = method.__name__
+    capture.__qualname__ = method.__qualname__
+    cast(Any, capture).__signature__ = signature
+    capture.__annotations__ = dict(annotations)
+    validated = validate_call(
+        config=ConfigDict(
+            arbitrary_types_allowed=True,
+            validate_by_name=True,
+            hide_input_in_errors=True,
+        )
+    )(capture)
+    return cast(Callable[..., Awaitable[_ValidatedArguments]], validated)
+
+
+def _method_source(method: Any, owner: ModuleKey) -> SourceLocation:
+    file_name: str | None = None
+    line: int | None = None
+    try:
+        file_name = inspect.getsourcefile(method)
+        _, line = inspect.getsourcelines(method)
+    except (OSError, TypeError):
+        pass
+    return SourceLocation(
+        owner=str(owner),
+        file=file_name,
+        line=line,
+        symbol=f"{method.__module__}.{method.__qualname__}",
+    )

python_ddd_framework/invocation/module.py

@@ -0,0 +1,113 @@
+"""Application-local 调用上下文、准入和入口编译的能力 owner。"""
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
+
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..application_services.invocation import _InvocationRuntime
+from ..extensions.module import ExtensionsModule
+from ..invocation.interceptors import _InterceptorRule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceValidationContext,
+)
+from .entries import _validate_entry
+from .interception import InvocationEntry, _EntryInterceptionCatalog
+from .managed_services import _ManagedServices
+from .validation import _validate_interceptor_scopes
+
+
+class InvocationModule(AppModule):
+    dependencies = (ExtensionsModule,)
+    catalog: _EntryInterceptionCatalog
+    invocation_runtime: _InvocationRuntime
+
+    def __init__(self) -> None:
+        self._managed_services = _ManagedServices()
+        self.entries: list[InvocationEntry] = []
+        self._rules: list[_InterceptorRule] = []
+        self._targets: dict[type[object], type[object]] = {}
+
+    @property
+    def rules(self) -> tuple[_InterceptorRule, ...]:
+        return tuple(self._rules)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_composition(
+            ServiceComposition(
+                bind=self._bind,
+                finalize=self._finalize,
+                decorate=self._decorate,
+                validate=self._validate,
+            )
+        )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        application = context.application
+        runtime = _InvocationRuntime(
+            application_id=application.id,
+            state_getter=lambda: application.state,
+        )
+        self.invocation_runtime = runtime
+        self.runtime = runtime.runtime_participant()
+        provider = Provider()
+        provider.provide(lambda: runtime, provides=_InvocationRuntime, scope=Scope.APP)
+        provider.provide(runtime.context_for_action, scope=Scope.ACTION)
+        provider.provide(lambda: self.catalog, provides=_EntryInterceptionCatalog, scope=Scope.APP)
+        context.add_provider(provider)
+
+    def _finalize(self, context: ServiceBindingContext) -> None:
+        for entry in self.entries:
+            if isinstance(entry.target, type):
+                factory = context.arbitration.single_factory(
+                    DependencyKey(entry.target, DEFAULT_COMPONENT),
+                )
+                if factory is None:
+                    raise ApplicationServiceDefinitionError(
+                        symbol=entry.target.__qualname__,
+                        reason="entry requires a single binding",
+                    )
+                self._targets[entry.target] = (
+                    factory.source if isinstance(factory.source, type) else entry.target
+                )
+        from ..authorization.module import AuthorizationModule
+
+        permissions = (
+            context.modules.instance(AuthorizationModule).catalog
+            if any(
+                item.module_type is AuthorizationModule for item in context.modules.dependency_order
+            )
+            else None
+        )
+        self.catalog = _EntryInterceptionCatalog(
+            tuple(self.entries),
+            self.rules,
+            self._targets,
+            permissions,
+            context.modules.instance(ExtensionsModule).catalog,
+        )
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        self._managed_services.validate(context)
+        _validate_interceptor_scopes(context.native_graph, self.catalog.interceptor_scopes)
+        for entry in self.entries:
+            target = entry.target
+            if isinstance(target, type):
+                target = self._targets[target]
+            _validate_entry(
+                context.container,
+                target,
+                entry.method,
+                entry.business_parameters,
+                entry.method_scope,
+            )
+
+    def _decorate(self, context: ServiceBindingContext) -> None:
+        self._managed_services.decorate(
+            context,
+            self.invocation_runtime,
+            self.rules,
+            {entry.target for entry in self.entries} | set(self._targets.values()),
+        )

python_ddd_framework/{application_services → invocation}/policies.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 from typing import TypeVar
 
-from .errors import ApplicationServiceDefinitionError
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..modularity import ModuleRef, ModuleRequirement
 
 _T = TypeVar("_T")
 _VALIDATION_ATTRIBUTE = "__python_ddd_framework_validation_enabled__"
@@ -44,3 +45,9 @@ def _effective_switch(
                 )
             return value
     return default
+
+
+class ValidationEnabled:
+    __validation_module__ = ModuleRequirement(
+        ModuleRef("python_ddd_framework.invocation.module:InvocationModule")
+    )

python_ddd_framework/invocation/validation.py

@@ -0,0 +1,25 @@
+"""根据已编译入口所需 scope 核对原生 DI 图。"""
+
+from collections.abc import Iterable
+
+from dishka import Scope
+
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..invocation.interceptors import InterceptorRegistration
+from ..services.native_graph import _NativeServiceGraph
+
+
+def _validate_interceptor_scopes(
+    graph: _NativeServiceGraph,
+    requirements: Iterable[tuple[InterceptorRegistration, Scope]],
+) -> None:
+    for registration, available in requirements:
+        scope = graph.interceptor_scope(registration.interceptor)
+        if scope not in (Scope.APP, Scope.REQUEST, Scope.ACTION) or scope > available:
+            raise ApplicationServiceDefinitionError(
+                symbol=registration.interceptor.__qualname__,
+                reason=(
+                    f"interceptor scope is unavailable before {registration.before.value}; "
+                    f"owner={registration.owner}"
+                ),
+            )

python_ddd_framework/lifecycle/__init__.py

@@ -2,6 +2,7 @@
 
 from .composition import ConfigureContext, PostConfigureContext, PreConfigureContext
 from .context import ApplicationView, LifecycleContext
+from .participants import RuntimeParticipant
 from .runtime import (
     InitializeContext,
     PostInitializeContext,
@@ -20,6 +21,7 @@ __all__ = (
     "PostInitializeContext",
     "PreConfigureContext",
     "PreInitializeContext",
+    "RuntimeParticipant",
     "ShutdownContext",
     "ShutdownReason",
 )

python_ddd_framework/lifecycle/composition.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from ..configuration import ConfigurationRoot
-from ..events import EventContributor
+from ..modularity import ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
 from ..options import PreOptionsSnapshot
 from ..options.contribution import _OptionsContributor
 from ..services import ServiceContributor
@@ -20,15 +21,17 @@ class PreConfigureContext(LifecycleContext):
 
 @dataclass(frozen=True, slots=True)
 class ConfigureContext(LifecycleContext):
+    modules: ModuleRegistry
+    discoveries: tuple[_DiscoveredType, ...]
     configuration: ConfigurationRoot
     pre_options: PreOptionsSnapshot
     configure: _OptionsContributor
     services: ServiceContributor
-    events: EventContributor
 
 
 @dataclass(frozen=True, slots=True)
 class PostConfigureContext(LifecycleContext):
+    modules: ModuleRegistry
     configuration: ConfigurationRoot
     pre_options: PreOptionsSnapshot
     configure: _OptionsContributor

python_ddd_framework/lifecycle/participants.py

@@ -0,0 +1,33 @@
+"""能力贡献的运行生命周期；内核只编排回调，不解释具体协调器。"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from ..errors.lifecycle import ApplicationRuntimeError
+from .state import ShutdownReason
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeParticipant:
+    start: Callable[[], Awaitable[None]]
+    stop: Callable[[ShutdownReason], Awaitable[tuple[BaseException, ...]]]
+    prepare: Callable[[bool], None] | None = None
+    close_admission: Callable[[], None] | None = None
+    ready: Callable[[], bool] | None = None
+    failure: Callable[[], Awaitable[ApplicationRuntimeError] | None] | None = None
+    drain: Callable[[], Awaitable[None]] | None = None
+
+    def __post_init__(self) -> None:
+        if not callable(self.start) or not callable(self.stop):
+            raise TypeError("runtime start and stop must be callable")
+        if any(
+            callback is not None and not callable(callback)
+            for callback in (
+                self.prepare,
+                self.close_admission,
+                self.ready,
+                self.failure,
+                self.drain,
+            )
+        ):
+            raise TypeError("runtime callbacks must be callable")

python_ddd_framework/messaging/__init__.py

@@ -0,0 +1,25 @@
+"""有界进程内消息与显式状态快照合并。"""
+
+from .channel import MessageChannel
+from .contracts import (
+    MessageChannelDefinition,
+    MessageHandler,
+    MessageOutcome,
+    MessageRejectedError,
+    MessageState,
+)
+from .module import MessagingModule
+from .options import MessagingOptions
+from .receipt import MessageReceipt
+
+__all__ = (
+    "MessageChannel",
+    "MessageChannelDefinition",
+    "MessageHandler",
+    "MessageOutcome",
+    "MessageReceipt",
+    "MessageRejectedError",
+    "MessageState",
+    "MessagingModule",
+    "MessagingOptions",
+)