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

python_ddd_framework/application_services/__init__.py

@@ -1,9 +1,4 @@
-from ..invocation import ApplicationInvocationContext
-from .catalog import (
-    ApplicationServiceCatalog,
-    ApplicationServiceMethod,
-    ApplicationServiceRegistration,
-)
+from .catalog import ApplicationServiceCatalog, ApplicationServiceRegistration
 from .contracts import (
     ApplicationService,
     ApplicationServiceContract,
@@ -20,35 +15,24 @@ from .errors import (
     CrossTaskInvocationError,
     NestedConnectionError,
 )
-from .execution import MethodInvocation
-from .interceptors import InterceptionStage, Interceptor, InterceptorRegistration
-from .policies import disable_validation, enable_validation
-from .seeding import DataSeedContributor, DataSeeder, DataSeedError
+from .pagination import PagedAndSortedResultRequestDto, PagedResult, PagedResultRequestDto
 
 __all__ = (
     "ApplicationInvocationCleanupError",
-    "ApplicationInvocationContext",
     "ApplicationInvocationRejectedError",
     "ApplicationService",
     "ApplicationServiceCatalog",
     "ApplicationServiceContract",
     "ApplicationServiceDefinitionError",
-    "ApplicationServiceMethod",
     "ApplicationServiceMethodError",
     "ApplicationServiceRegistration",
     "ApplicationServiceValidationError",
     "ApplicationServiceValidationIssue",
     "CrossTaskInvocationError",
-    "DataSeedContributor",
-    "DataSeedError",
-    "DataSeeder",
     "IntegrationService",
-    "InterceptionStage",
-    "Interceptor",
-    "InterceptorRegistration",
-    "MethodInvocation",
     "NestedConnectionError",
+    "PagedAndSortedResultRequestDto",
+    "PagedResult",
+    "PagedResultRequestDto",
     "application_service",
-    "disable_validation",
-    "enable_validation",
 )

python_ddd_framework/{services/application_bindings.py → application_services/bindings.py}

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass
+from typing import get_origin
 
 from dishka import (
     DEFAULT_COMPONENT,
@@ -11,24 +13,26 @@ from dishka import (
     Scope,
 )
 
-from ..application_services import ApplicationService
-from ..application_services.catalog import (
-    _APPLICATION_SERVICE_COMPONENT,
-    _ApplicationServiceBinding,
-    _DiscoveredApplicationService,
-)
-from ..application_services.errors import ApplicationServiceDefinitionError
 from ..diagnostics import SourceLocation
 from ..modularity import ModuleRegistry
-from .arbitration import (
+from ..services.arbitration import (
     _ArbitrationResult,
     _provider_with_active_sources,
     _RegistrationDraft,
 )
-from .registration import (
+from ..services.native_graph import _NativeServiceGraph
+from ..services.registration import (
     RegistrationDecision,
     RegistrationKind,
 )
+from .catalog import (
+    _APPLICATION_SERVICE_COMPONENT,
+    ApplicationServiceCatalog,
+    _ApplicationServiceBinding,
+    _DiscoveredApplicationService,
+)
+from .contracts import ApplicationService
+from .errors import ApplicationServiceDefinitionError
 
 
 @dataclass(frozen=True, slots=True)
@@ -160,6 +164,45 @@ def _validate_application_service_dependencies(
                 )
 
 
+def _validate_application_service_bindings(
+    native_graph: _NativeServiceGraph,
+    catalog: ApplicationServiceCatalog,
+    proxy_factories: Mapping[DependencyKey, object],
+) -> None:
+    implementations = {
+        DependencyKey(item.contract, _APPLICATION_SERVICE_COMPONENT): item.implementation
+        for item in catalog.registrations
+    }
+    for row in native_graph:
+        factory = native_graph.effective_factory(row)
+        candidates = (get_origin(row.key.type_hint) or row.key.type_hint, factory.source)
+        is_implementation = any(
+            isinstance(candidate, type) and issubclass(candidate, ApplicationService)
+            for candidate in candidates
+        )
+        is_proxy = any(factory.source is source for source in proxy_factories.values())
+        if not (is_implementation or is_proxy or row.key in proxy_factories):
+            continue
+        expected_source = implementations.get(row.key) or proxy_factories.get(row.key)
+        expected_scope = Scope.ACTION if row.key in implementations else Scope.REQUEST
+        # scope 相同不代表经过管线；必须证明是本次最终实现或 owner 实际生成的代理。
+        # 沿 alias 识别角色，但 alias 不能额外发布私有实现或冒充正式公开身份。
+        if (
+            expected_source is None
+            or row.factory.source is not expected_source
+            or row.factory is not factory
+            or row.scope is not expected_scope
+            or not factory.cache
+        ):
+            raise ApplicationServiceDefinitionError(
+                symbol=str(row.key.type_hint),
+                reason=(
+                    "ApplicationService must use its managed proxy "
+                    "or private implementation binding"
+                ),
+            )
+
+
 def _runtime_providers(
     arbitration: _ArbitrationResult,
     services: tuple[_BoundApplicationService, ...],

python_ddd_framework/application_services/catalog.py

@@ -3,58 +3,35 @@
 from __future__ import annotations
 
 import inspect
-from collections.abc import Awaitable, Callable, Mapping
-from dataclasses import dataclass, field, replace
+from collections.abc import Mapping
+from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Any, cast, get_type_hints
 
-from pydantic import ConfigDict, validate_call
-
-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 ..authorization import PermissionCatalog
 from ..diagnostics import SourceLocation
+from ..extensions.catalog import ExtensionCatalog
+from ..invocation.interceptors import _InterceptorRule
+from ..invocation.methods import (
+    _POLICY_ATTRIBUTES,
+    ServiceMethod,
+    _compile_method,
+    _CompiledMethod,
+    _public_method_names,
+)
 from ..modularity import ModuleKey
-from ..unit_of_work.options import _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration, _declaration
+from ..unit_of_work.options import UnitOfWorkDeclaration
 from .contracts import (
     ApplicationService,
     ApplicationServiceContract,
     IntegrationService,
     _ApplicationServiceDefinition,
     _inherited_contracts,
-    _is_internal_contributor,
 )
 from .errors import ApplicationServiceDefinitionError, ApplicationServiceMethodError
-from .interceptors import InterceptionStage, InterceptorRegistration, _InterceptorRule
-from .policies import _VALIDATION_ATTRIBUTE, _effective_switch
-from .signature import _business_signature
 
 _APPLICATION_SERVICE_COMPONENT = "__python_ddd_framework_application_service_implementation__"
 
 
-@dataclass(frozen=True, slots=True)
-class ApplicationServiceMethod:
-    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)
-
-
 @dataclass(frozen=True, slots=True)
 class ApplicationServiceRegistration:
     contract: type[object]
@@ -66,8 +43,7 @@ class ApplicationServiceRegistration:
     implementation_source: SourceLocation
     replaced_sources: tuple[SourceLocation, ...]
     declaration_index: int
-    methods: tuple[ApplicationServiceMethod, ...]
-    is_public_service: bool
+    methods: tuple[ServiceMethod, ...]
     has_contract: bool
     is_integration_service: bool
 
@@ -90,22 +66,6 @@ class _ApplicationServiceBinding:
     replaced_sources: tuple[SourceLocation, ...]
 
 
-_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: ApplicationServiceMethod
-    signature: inspect.Signature
-    interceptor_steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]]
-
-
 @dataclass(frozen=True, slots=True)
 class _CompiledApplicationService:
     registration: ApplicationServiceRegistration
@@ -120,15 +80,14 @@ class ApplicationServiceCatalog:
     def __init__(self, services: tuple[_CompiledApplicationService, ...]) -> None:
         self._compiled = services
         self._registrations = tuple(item.registration for item in services)
-        public_services = tuple(item for item in services if item.registration.is_public_service)
         self._by_contract: Mapping[type[object], _CompiledApplicationService] = MappingProxyType(
-            {item.registration.contract: item for item in public_services}
+            {item.registration.contract: item for item in services}
         )
         methods_by_identity: dict[
             object,
             tuple[_CompiledApplicationService, _CompiledMethod],
         ] = {}
-        for service in public_services:
+        for service in services:
             for method in service.methods.values():
                 previous = methods_by_identity.get(method.contract_method)
                 if previous is not None:
@@ -181,17 +140,22 @@ class ApplicationServiceCatalog:
 def _build_application_service_catalog(
     bindings: tuple[_ApplicationServiceBinding, ...],
     permission_catalog: PermissionCatalog,
-    interceptor_rules: tuple[_InterceptorRule, ...] = (),
+    interceptor_rules: tuple[_InterceptorRule, ...],
+    extensions: ExtensionCatalog,
 ) -> ApplicationServiceCatalog:
     return ApplicationServiceCatalog(
-        tuple(_compile_service(item, permission_catalog, interceptor_rules) for item in bindings)
+        tuple(
+            _compile_service(item, permission_catalog, interceptor_rules, extensions)
+            for item in bindings
+        )
     )
 
 
 def _compile_service(
     binding: _ApplicationServiceBinding,
     permission_catalog: PermissionCatalog,
-    interceptor_rules: tuple[_InterceptorRule, ...] = (),
+    interceptor_rules: tuple[_InterceptorRule, ...],
+    extensions: ExtensionCatalog,
 ) -> _CompiledApplicationService:
     """把 contract declaration 与仲裁胜出的 implementation 编译成唯一调用事实。"""
 
@@ -199,7 +163,6 @@ def _compile_service(
     implementation = binding.implementation
     contract: type[object] = discovery.definition.contract or discovery.service_type
     has_contract = discovery.definition.contract is not None
-    is_public_service = not _is_internal_contributor(implementation)
     is_integration = issubclass(implementation, IntegrationService)
     _validate_policy_locations(contract if has_contract else None, implementation, is_integration)
     if is_integration and not has_contract:
@@ -218,92 +181,22 @@ def _compile_service(
     contract_methods = _public_method_names(contract, is_contract=has_contract)
 
     compiled_methods: dict[str, _CompiledMethod] = {}
-    public_methods: list[ApplicationServiceMethod] = []
+    public_methods: list[ServiceMethod] = []
     for name in contract_methods:
-        contract_method = _require_async_instance_method(contract, name, role="contract")
-        implementation_method = _require_async_instance_method(
+        method = _compile_method(
+            contract,
             implementation,
             name,
-            role="implementation",
+            discovery.owner,
+            binding.implementation_owner,
+            permission_catalog,
+            interceptor_rules,
+            auditing_default=not is_integration,
+            unit_of_work_default=UnitOfWorkDeclaration(),
+            extensions=extensions,
         )
-        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",
-            )
-        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, discovery.owner)
-        authorization = _authorization_requirement(implementation, implementation_method)
-        unknown_permissions = tuple(
-            permission
-            for permission in authorization.permissions
-            if 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 = ApplicationServiceMethod(
-            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),
-            validation_enabled=_effective_switch(
-                implementation, implementation_method, _VALIDATION_ATTRIBUTE, True
-            ),
-            auditing_enabled=_effective_switch(
-                implementation, implementation_method, _AUDITING_ATTRIBUTE, not is_integration
-            ),
-            policy_sources=_policy_sources(
-                implementation, implementation_method, binding.implementation_owner
-            ),
-        )
-        descriptor = replace(
-            descriptor, interceptors=_match_interceptors(descriptor, interceptor_rules)
-        )
-        compiled_methods[name] = _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,
-            interceptor_steps=MappingProxyType(
-                {
-                    stage: tuple(item for item in descriptor.interceptors if item.before is stage)
-                    for stage in InterceptionStage
-                }
-            ),
-        )
-        public_methods.append(descriptor)
+        compiled_methods[name] = method
+        public_methods.append(method.descriptor)
 
     if not public_methods:
         raise ApplicationServiceDefinitionError(
@@ -321,7 +214,6 @@ def _compile_service(
         replaced_sources=binding.replaced_sources,
         declaration_index=discovery.declaration_index,
         methods=tuple(public_methods),
-        is_public_service=is_public_service,
         has_contract=has_contract,
         is_integration_service=is_integration,
     )
@@ -331,15 +223,6 @@ def _compile_service(
     )
 
 
-_POLICY_ATTRIBUTES = (
-    _UNIT_OF_WORK_ATTRIBUTE,
-    _AUTHORIZATION_ATTRIBUTE,
-    _ALLOW_ANONYMOUS_ATTRIBUTE,
-    _VALIDATION_ATTRIBUTE,
-    _AUDITING_ATTRIBUTE,
-)
-
-
 def _validate_policy_locations(
     contract: type[object] | None, implementation: type[object], integration: bool
 ) -> None:
@@ -363,138 +246,3 @@ def _validate_policy_locations(
                         if root in contracts
                         else "IntegrationService cannot declare user authorization",
                     )
-
-
-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: ApplicationServiceMethod, 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 in (object, ApplicationService, ApplicationServiceContract):
-            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/application_services/contracts.py

@@ -4,8 +4,12 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Protocol, TypeVar
+from typing import TYPE_CHECKING, ClassVar, Protocol, TypeVar
 
+from dishka import Scope
+
+from ..modularity import ModuleRef, ModuleRequirement
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
 from .errors import ApplicationServiceDefinitionError
 
 if TYPE_CHECKING:
@@ -15,7 +19,6 @@ _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE = (
     "__python_ddd_framework_application_service_definition__"
 )
 _TApplicationService = TypeVar("_TApplicationService", bound="ApplicationService")
-_DEFAULT_CONNECTION_NAME = "default"
 
 
 class ApplicationServiceContract(Protocol):
@@ -25,6 +28,14 @@ class ApplicationServiceContract(Protocol):
 class ApplicationService:
     """业务实现；无独立 Contract 时，以自身类型发布受管理代理。"""
 
+    _fixed_service_scope: ClassVar[Scope] = Scope.ACTION
+    _public_service_scope: ClassVar[Scope] = Scope.REQUEST
+    _requires_convention: ClassVar[bool] = True
+
+    __application_services_module__ = ModuleRequirement(
+        ModuleRef("python_ddd_framework.application_services.module:ApplicationServicesModule")
+    )
+
     _setting_provider: SettingProvider | None = None
 
     @property
@@ -39,10 +50,6 @@ class IntegrationService(ApplicationService):
     """仅供应用内协作的服务；必须声明 Contract，不承载用户授权。"""
 
 
-class _InternalApplicationServiceContributor(ApplicationService):
-    """框架内部多贡献者基类；不发布含糊的 single Protocol。"""
-
-
 @dataclass(frozen=True, slots=True)
 class _ApplicationServiceDefinition:
     contract: type[ApplicationServiceContract] | None
@@ -74,8 +81,7 @@ def application_service(
             )
         contract = provides
         if contract is None:
-            if not _is_internal_contributor(service_type):
-                contract = _infer_contract(service_type)
+            contract = _infer_contract(service_type)
         else:
             _validate_contract(
                 provides,
@@ -100,7 +106,6 @@ def _definition_for(
     if not issubclass(candidate, ApplicationService) or candidate in (
         ApplicationService,
         IntegrationService,
-        _InternalApplicationServiceContributor,
     ):
         return None
     metadata = candidate.__dict__.get(_APPLICATION_SERVICE_DEFINITION_ATTRIBUTE)
@@ -170,10 +175,6 @@ def _validate_contract(candidate: object, *, symbol: str) -> None:
         )
 
 
-def _is_internal_contributor(candidate: type[object]) -> bool:
-    return issubclass(candidate, _InternalApplicationServiceContributor)
-
-
 def _validate_connection_name(connection_name: str) -> str:
     if not isinstance(connection_name, str) or not connection_name:
         raise ApplicationServiceDefinitionError(