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

python_ddd_framework/invocation/interception.py

@@ -9,66 +9,71 @@ from typing import cast
 
 from dishka import AsyncContainer, Scope
 
-from ..application_services.catalog import (
-    ApplicationServiceMethod,
+from ..application_services.invocation import _InvocationRuntime
+from ..authorization import PermissionCatalog
+from ..extensions.catalog import ExtensionCatalog
+from ..invocation.execution import _InterceptorPipeline
+from ..invocation.interceptors import InterceptionStage, InterceptorRegistration, _InterceptorRule
+from ..invocation.methods import (
+    ServiceMethod,
+    _compile_method,
+    _CompiledMethod,
     _match_interceptors,
     _method_source,
+    _policy_fingerprint,
 )
-from ..application_services.execution import _InterceptorPipeline
-from ..application_services.interceptors import (
-    InterceptionStage,
-    InterceptorRegistration,
-    _InterceptorRule,
-)
-from ..application_services.invocation import _InvocationRuntime
-from ..background_jobs import BackgroundJobCatalog
-from ..background_workers import BackgroundWorkerCatalog
-from ..events.catalog import LocalEventCatalog
-from ..events.contracts import LocalEventPhase
 from ..modularity import ModuleKey
 from ..unit_of_work.options import _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration, _declaration
 from .callables import _call_in_scope
 
 
+@dataclass(frozen=True, slots=True)
+class InvocationEntry:
+    target: type[object] | Callable[..., Awaitable[None]]
+    method: str
+    owner: ModuleKey
+    business_parameters: int
+    outer_scope: Scope = Scope.REQUEST
+    method_scope: Scope = Scope.ACTION
+    unit_of_work_default: UnitOfWorkDeclaration | None = None
+    managed_method: bool = False
+
+
 @dataclass(frozen=True, slots=True)
 class _CompiledEntry:
-    descriptor: ApplicationServiceMethod
+    descriptor: ServiceMethod
     steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]]
     outer_scope: Scope
     method_scope: Scope
+    managed: _CompiledMethod | None = None
 
 
 class _EntryInterceptionCatalog:
     def __init__(
         self,
-        events: LocalEventCatalog,
+        declarations: tuple[InvocationEntry, ...],
         rules: tuple[_InterceptorRule, ...],
-        workers: BackgroundWorkerCatalog,
-        jobs: BackgroundJobCatalog,
+        implementations: Mapping[type[object], type[object]],
+        permission_catalog: PermissionCatalog | None,
+        extensions: ExtensionCatalog,
     ) -> None:
         entries: dict[tuple[object, str], _CompiledEntry] = {}
-        for worker in workers.definitions:
+        for declaration in declarations:
             self._add(
                 entries,
-                worker.worker_type,
-                "run_iteration",
-                workers.owner_for(worker.name),
+                declaration.target,
+                declaration.method,
+                declaration.owner,
                 rules,
-                True,
-            )
-        for job in jobs.definitions:
-            self._add(entries, job.handler_type, "execute", jobs.owner_for(job), rules, False)
-        for subscription in events.subscriptions:
-            scope = Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
-            self._add(
-                entries,
-                subscription.handler_type,
-                "handle",
-                subscription.owner,
-                rules,
-                False,
-                outer_scope=scope,
-                method_scope=scope,
+                declaration.unit_of_work_default,
+                implementation=implementations.get(declaration.target)
+                if isinstance(declaration.target, type)
+                else None,
+                outer_scope=declaration.outer_scope,
+                method_scope=declaration.method_scope,
+                managed_method=declaration.managed_method,
+                permission_catalog=permission_catalog,
+                extensions=extensions,
             )
         self._entries: Mapping[tuple[object, str], _CompiledEntry] = MappingProxyType(entries)
 
@@ -92,13 +97,19 @@ class _EntryInterceptionCatalog:
         name: str,
         owner: ModuleKey,
         rules: tuple[_InterceptorRule, ...],
-        worker: bool,
+        unit_of_work_default: UnitOfWorkDeclaration | None,
         *,
+        implementation: type[object] | None,
         outer_scope: Scope = Scope.REQUEST,
         method_scope: Scope = Scope.ACTION,
+        managed_method: bool = False,
+        permission_catalog: PermissionCatalog | None = None,
+        extensions: ExtensionCatalog,
     ) -> None:
         if (target, name) in entries:
             current = entries[target, name]
+            if (current.managed is not None) != managed_method:
+                raise TypeError("The same entry cannot mix managed and lifecycle-only policies")
             # 同一 handler 可订阅两个 phase；构建时使用所有实际入口的最窄解析边界。
             entries[target, name] = replace(
                 current,
@@ -106,15 +117,38 @@ class _EntryInterceptionCatalog:
                 method_scope=min(current.method_scope, method_scope),
             )
             return
-        function = getattr(target, name) if isinstance(target, type) else target
-        implementation = target if isinstance(target, type) else type(target)
+        implementation = implementation or (target if isinstance(target, type) else type(target))
+        if managed_method:
+            if not isinstance(target, type):
+                raise TypeError("Managed entry requires a class binding")
+            compiled = _compile_method(
+                implementation,
+                implementation,
+                name,
+                owner,
+                owner,
+                permission_catalog,
+                rules,
+                auditing_default=False,
+                unit_of_work_default=unit_of_work_default or UnitOfWorkDeclaration(),
+                extensions=extensions,
+            )
+            entries[target, name] = _CompiledEntry(
+                compiled.descriptor,
+                compiled.interceptor_steps,
+                outer_scope,
+                method_scope,
+                compiled,
+            )
+            return
+        function = getattr(implementation, name) if isinstance(target, type) else target
         declaration = _declaration(implementation, function)
-        if worker and not any(
+        if unit_of_work_default is not None and not any(
             hasattr(item, _UNIT_OF_WORK_ATTRIBUTE) for item in (implementation, function)
         ):
-            declaration = UnitOfWorkDeclaration(disabled=True)
+            declaration = unit_of_work_default
         source = _method_source(function, owner)
-        descriptor = ApplicationServiceMethod(
+        descriptor = ServiceMethod(
             name=name,
             source=source,
             requires_authenticated_user=False,
@@ -152,6 +186,10 @@ class _EntryInterceptionCatalog:
         connection_name: str | None = None,
     ) -> object:
         entry = self._entries[target, name]
+        if entry.managed is not None:
+            return await _invoke_managed_entry(
+                entry.managed, runtime, container, target, args, connection_name
+            )
         pipeline = _InterceptorPipeline(entry.descriptor, entry.steps, args, {})
 
         async def call(scope: AsyncContainer) -> object:
@@ -191,3 +229,36 @@ class _EntryInterceptionCatalog:
             return await pipeline.run(stages[index], container, lambda: run(index + 1))
 
         return await run(0)
+
+
+async def _invoke_managed_entry(
+    method: _CompiledMethod,
+    runtime: _InvocationRuntime,
+    container: AsyncContainer,
+    target: object,
+    args: tuple[object, ...],
+    connection_name: str | None,
+) -> object:
+    from .dispatcher import _MethodDispatcher
+
+    implementation = method.descriptor.implementation
+    if (
+        getattr(implementation, method.name) is not method.implementation_method
+        or _policy_fingerprint(implementation, method.implementation_method)
+        != method.policy_fingerprint
+    ):
+        raise TypeError("Managed entry declaration changed after compilation")
+    if connection_name is None:
+        raise ValueError("Managed entry requires an execution connection")
+
+    async def invoke_target(
+        scope: AsyncContainer, arguments: tuple[object, ...], kwargs: dict[str, object]
+    ) -> object:
+        instance = await scope.get(cast(type[object], target))
+        return await cast(Callable[..., Awaitable[object]], getattr(instance, method.name))(
+            *arguments, **kwargs
+        )
+
+    return await _MethodDispatcher(container, runtime).invoke_method(
+        method, args, {}, invoke_target, connection_name
+    )

python_ddd_framework/{application_services → invocation}/interceptors.py

@@ -12,7 +12,7 @@ from ..diagnostics import SourceLocation
 from ..modularity import ModuleKey
 
 if TYPE_CHECKING:
-    from .catalog import ApplicationServiceMethod
+    from ..invocation.methods import ServiceMethod
     from .execution import MethodInvocation
 
 
@@ -41,4 +41,4 @@ class InterceptorRegistration:
 @dataclass(frozen=True, slots=True)
 class _InterceptorRule:
     registration: InterceptorRegistration
-    match: Callable[[ApplicationServiceMethod], bool]
+    match: Callable[[ServiceMethod], bool]

python_ddd_framework/invocation/managed_proxy.py

@@ -0,0 +1,116 @@
+"""最终普通 DI 绑定的方法解释、同 scope 原生装饰与图证明。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from functools import wraps
+
+from dishka import AsyncContainer, Scope
+
+from ..application_services.invocation import _InvocationRuntime, _managed_request
+from ..unit_of_work.options import (
+    _DEFAULT_CONNECTION_NAME,
+)
+from .contracts import ApplicationInvocationContext
+from .dispatcher import _MethodDispatcher
+from .methods import (
+    _CompiledMethod,
+)
+
+
+class _ManagedServiceProxy:
+    """只转交被标记的方法；实例、未标记成员和 finalizer 仍属于原生绑定。"""
+
+    __slots__ = (
+        "__auditing",
+        "__container",
+        "__instance",
+        "__methods",
+        "__runtime",
+        "__unit_of_work",
+    )
+    __instance: object
+    __container: AsyncContainer
+    __runtime: _InvocationRuntime
+    __methods: Mapping[str, _CompiledMethod]
+    __unit_of_work: bool
+    __auditing: bool
+
+    def __init__(
+        self,
+        instance: object,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+        methods: Mapping[str, _CompiledMethod],
+        *,
+        unit_of_work: bool,
+        auditing: bool,
+    ) -> None:
+        # 仅初始化代理自身；之后业务属性写入必须与方法使用同一个原生实例。
+        object.__setattr__(self, "_ManagedServiceProxy__instance", instance)
+        object.__setattr__(self, "_ManagedServiceProxy__container", container)
+        object.__setattr__(self, "_ManagedServiceProxy__runtime", runtime)
+        object.__setattr__(self, "_ManagedServiceProxy__methods", methods)
+        object.__setattr__(self, "_ManagedServiceProxy__unit_of_work", unit_of_work)
+        object.__setattr__(self, "_ManagedServiceProxy__auditing", auditing)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        setattr(self.__instance, name, value)
+
+    def __delattr__(self, name: str) -> None:
+        delattr(self.__instance, name)
+
+    def __getattr__(self, name: str) -> object:
+        method = self.__methods.get(name)
+        if method is None:
+            return getattr(self.__instance, name)
+        bound = getattr(self.__instance, name)
+
+        @wraps(bound)
+        async def invoke(*args: object, **kwargs: object) -> object:
+            async def target(
+                _: AsyncContainer, args: tuple[object, ...], kwargs: dict[str, object]
+            ) -> object:
+                return await method.implementation_method(self.__instance, *args, **kwargs)
+
+            runtime = self.__runtime
+            async with runtime.outer_lease():
+                ambient = runtime.current()
+                current = (
+                    ambient.action_container
+                    if ambient is not None
+                    else runtime.current_call_scope()
+                )
+                connection = (
+                    ambient.context.connection_name
+                    if ambient is not None
+                    else _DEFAULT_CONNECTION_NAME
+                )
+
+                async def call(container: AsyncContainer) -> object:
+                    action_connection = (
+                        (await container.get(ApplicationInvocationContext)).connection_name
+                        if container.scope is Scope.ACTION
+                        else connection
+                    )
+                    dispatcher = _MethodDispatcher(
+                        container,
+                        runtime,
+                        unit_of_work_enabled=self.__unit_of_work,
+                        auditing_enabled=self.__auditing,
+                    )
+                    return await dispatcher.invoke_method(
+                        method, args, kwargs, target, action_connection
+                    )
+
+                if current is not None:
+                    return await call(current)
+                if self.__container.scope is not Scope.APP:
+                    with runtime.call_scope(self.__container):
+                        return await call(self.__container)
+                # APP 对象不捕获某次 REQUEST；每次独立调用创建并排空自己的 scope。
+                async with _managed_request(self.__container) as request:
+                    with runtime.call_scope(request):
+                        return await call(request)
+
+        return invoke

python_ddd_framework/invocation/managed_services.py

@@ -0,0 +1,250 @@
+"""最终普通 DI 绑定的方法解释、同 scope 原生装饰与图证明。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import ParamSpec, TypeVar, TypeVarTuple, get_origin
+
+from dishka import AsyncContainer, DependencyKey, Provider, Scope
+from dishka.dependency_source import Factory
+from dishka.entities.factory_type import FactoryType
+
+from ..application_services.contracts import ApplicationService, ApplicationServiceContract
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..application_services.invocation import _InvocationRuntime
+from ..authorization.contracts import _AUTHORIZATION_ATTRIBUTE
+from ..extensions.module import ExtensionsModule
+from ..invocation.interceptors import InterceptionStage, _InterceptorRule
+from ..modularity.discovery import _require_type_dependencies
+from ..services.composition import ServiceBindingContext, ServiceValidationContext
+from ..services.registration import RegistrationDecision
+from ..unit_of_work.options import (
+    _UNIT_OF_WORK_ATTRIBUTE,
+    UnitOfWorkDeclaration,
+)
+from .managed_proxy import _ManagedServiceProxy
+from .methods import (
+    _compile_method,
+    _CompiledMethod,
+    _policy_fingerprint,
+    _public_method_names,
+    _require_async_instance_method,
+)
+from .policies import ValidationEnabled
+from .validation import _validate_interceptor_scopes
+
+
+def _managed_names(candidate: type[object]) -> tuple[str, ...]:
+    attributes = (_UNIT_OF_WORK_ATTRIBUTE, _AUTHORIZATION_ATTRIBUTE)
+    class_marked = issubclass(candidate, ValidationEnabled) or any(
+        hasattr(candidate, attribute) for attribute in attributes
+    )
+    names: list[str] = []
+    # 类级标记覆盖公开方法；显式方法标记即使位于非公开方法也必须接受形态校验。
+    members = {
+        name: value for base in reversed(candidate.__mro__) for name, value in vars(base).items()
+    }
+    public = _public_method_names(candidate, is_contract=False)
+    for name, value in members.items():
+        targets = (
+            (value, value.__func__) if isinstance(value, (staticmethod, classmethod)) else (value,)
+        )
+        marked = any(hasattr(target, attribute) for target in targets for attribute in attributes)
+        if marked or (class_marked and name in public):
+            _require_async_instance_method(candidate, name, role="managed service")
+            names.append(name)
+    return tuple(names)
+
+
+def _assert_methods(candidate: type[object], methods: Mapping[str, _CompiledMethod]) -> None:
+    if tuple(methods) != _managed_names(candidate) or any(
+        getattr(candidate, name) is not method.implementation_method
+        or _policy_fingerprint(candidate, method.implementation_method) != method.policy_fingerprint
+        for name, method in methods.items()
+    ):
+        raise ApplicationServiceDefinitionError(
+            symbol=candidate.__qualname__,
+            reason="managed method declaration differs from the compiled binding",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _ManagedBinding:
+    key: DependencyKey
+    factory: Factory
+    implementation: type[object]
+    methods: Mapping[str, _CompiledMethod]
+
+
+class _ManagedServices:
+    def __init__(self) -> None:
+        self._bindings: list[tuple[_ManagedBinding, object]] = []
+
+    def decorate(
+        self,
+        context: ServiceBindingContext,
+        runtime: _InvocationRuntime,
+        rules: tuple[_InterceptorRule, ...],
+        entry_targets: set[object],
+    ) -> None:
+        from ..auditing.module import AuditingModule
+        from ..authorization.module import AuthorizationModule
+        from ..unit_of_work.module import UnitOfWorkModule
+
+        modules = {descriptor.module_type for descriptor in context.modules.dependency_order}
+        permissions = (
+            context.modules.instance(AuthorizationModule).catalog
+            if AuthorizationModule in modules
+            else None
+        )
+        capabilities = dict(
+            unit_of_work=UnitOfWorkModule in modules, auditing=AuditingModule in modules
+        )
+        # 来源 owner 来自已仲裁贡献或派生记录，不另建服务类型清单。
+        contributions = [
+            (draft.key, draft.contribution.owner, draft.contribution.source, draft.factory)
+            for draft in context.arbitration.drafts
+            if draft.factory is not None and draft.decision is RegistrationDecision.ACCEPTED
+        ]
+        for descriptor, inspector, provider, _ in context._provider_checks:
+            for item in inspector.inspect(provider).factories:
+                contributions.append(
+                    (item.key, descriptor.key, descriptor.declaration_source, item.factory)
+                )
+        grouped: dict[DependencyKey, list[_ManagedBinding]] = {}
+        # 只消费仲裁胜出的 factory，原生 multi 的每项仍保留自己的最终实现事实。
+        for key, owner, source, factory in contributions:
+            factory_type = get_origin(factory.source) or factory.source
+            candidate = factory_type if isinstance(factory_type, type) else key.type_hint
+            candidate = get_origin(candidate) or candidate
+            if (
+                factory.type is FactoryType.ALIAS
+                or not isinstance(candidate, type)
+                or issubclass(candidate, ApplicationService)
+                or ApplicationServiceContract in candidate.__mro__
+                or candidate in entry_targets
+            ):
+                continue
+            names = _managed_names(candidate)
+            if names:
+                _require_type_dependencies(context.modules, owner, candidate, source=source)
+            service = key.type_hint if isinstance(key.type_hint, type) else candidate
+            methods = MappingProxyType(
+                {
+                    name: _compile_method(
+                        service if hasattr(service, name) else candidate,
+                        candidate,
+                        name,
+                        owner,
+                        owner,
+                        permissions,
+                        rules,
+                        validation_default=issubclass(candidate, ValidationEnabled),
+                        auditing_default=False,
+                        unit_of_work_default=UnitOfWorkDeclaration(disabled=True),
+                        extensions=context.modules.instance(ExtensionsModule).catalog,
+                    )
+                    for name in names
+                }
+            )
+            # 闭合 key 不能使仍含类型参数的方法悄悄退化成 Any 验证。
+            for method in methods.values():
+                annotations = (
+                    *(parameter.annotation for parameter in method.signature.parameters.values()),
+                    method.signature.return_annotation,
+                )
+                if any(
+                    isinstance(annotation, (TypeVar, ParamSpec, TypeVarTuple))
+                    or getattr(annotation, "__parameters__", ())
+                    for annotation in annotations
+                ):
+                    raise ApplicationServiceDefinitionError(
+                        symbol=f"{candidate.__qualname__}.{method.name}",
+                        reason="managed methods require concrete annotations",
+                    )
+            grouped.setdefault(key, []).append(_ManagedBinding(key, factory, candidate, methods))
+        for key, bindings in grouped.items():
+            if not any(
+                binding.methods
+                or binding.factory.type is FactoryType.CONTEXT
+                or not isinstance(
+                    get_origin(binding.factory.source) or binding.factory.source, type
+                )
+                for binding in bindings
+            ):
+                continue
+            decorator = self._decorator(key, runtime, tuple(bindings), **capabilities)
+            decorated = Provider(component=key.component)
+            decorated.decorate(decorator)
+            context._add_method_decorator(decorated)
+            self._bindings.extend((binding, decorator) for binding in bindings)
+
+    @staticmethod
+    def _decorator(
+        key: DependencyKey,
+        runtime: _InvocationRuntime,
+        bindings: tuple[_ManagedBinding, ...],
+        *,
+        unit_of_work: bool,
+        auditing: bool,
+    ) -> Callable[..., object]:
+        def decorate(instance: object, container: AsyncContainer) -> object:
+            # 外部 Provider 的实际返回对象必须符合已编译策略。
+            if not any(binding.methods for binding in bindings):
+                if isinstance(instance, ApplicationService) or _managed_names(type(instance)):
+                    raise ApplicationServiceDefinitionError(
+                        symbol=str(key), reason="factory result has uncompiled managed policies"
+                    )
+                return instance
+            binding = next(
+                (item for item in bindings if type(instance) is item.implementation), None
+            )
+            if binding is None:
+                raise ApplicationServiceDefinitionError(
+                    symbol=str(key), reason="factory result differs from the compiled binding"
+                )
+            methods = binding.methods
+            _assert_methods(type(instance), methods)
+            if not methods:
+                return instance
+            return _ManagedServiceProxy(
+                instance, container, runtime, methods, unit_of_work=unit_of_work, auditing=auditing
+            )
+
+        # 原生 decorate 用注解识别被装饰 key，依赖顺序是 instance -> 当前 scope 容器。
+        decorate.__annotations__ = {
+            "instance": key.type_hint,
+            "container": AsyncContainer,
+            "return": key.type_hint,
+        }
+        return decorate
+
+    def validate(self, context: ServiceValidationContext) -> None:
+        graph = context.native_graph
+        for binding, decorator in self._bindings:
+            _assert_methods(binding.implementation, binding.methods)
+            # collect 可移动 key.depth；真实装饰和底层 factory 身份仍须一一对应。
+            if not any(
+                row.factory.source is decorator
+                and row.scope is binding.factory.scope
+                and row.factory.cache == binding.factory.cache
+                and graph.effective_factory(row).source is binding.factory.source
+                for row in graph
+            ):
+                raise ApplicationServiceDefinitionError(
+                    symbol=str(binding.key),
+                    reason="managed decorator differs from final native binding",
+                )
+            _validate_interceptor_scopes(
+                graph,
+                (
+                    (
+                        rule,
+                        Scope.ACTION if rule.before is InterceptionStage.METHOD else Scope.REQUEST,
+                    )
+                    for method in binding.methods.values()
+                    for rule in method.descriptor.interceptors
+                ),
+            )